Skip to content

Specify the host-neutral, config-only role-profile projection contract #23

Description

@Punisheroot

Context

RoleProfileDefinition and revision provenance are Needle's canonical role
configuration. ConfigExport currently carries runtime settings, presets,
routes, and model policy; it does not carry role-profile truth and must not be
silently repurposed. Claude Code and Cursor adapters need one reviewed neutral
contract before implementation can begin.

Outcome

Approve a versioned host-neutral projection specification that maps every
canonical role-profile field to a neutral representation, explicit unsupported
result, or deterministic error. The specification defines identity,
canonicalization, capability negotiation, dry-run output, and the no-execution
boundary without implementing an adapter.

Scope

  • Inventory every field of RoleProfileDefinition plus immutable revision
    provenance and classify it as required, optional, host capability, or
    unsupported.
  • Define neutral source identity, schema revision, target host/adapter revision,
    mapped fields, structured unsupported entries, and deterministic error shape.
  • Define canonical ordering, serialization, digest material, repeated-projection
    determinism, and generated-time handling.
  • Define host capability negotiation and fail-closed treatment of policies that
    cannot be represented without weakening them.
  • Define dry-run/diff semantics as an artifact or stdout result with zero
    writes.
  • Define the conformance cases the implementation and every host adapter must
    pass.
  • Record the accepted decisions in a focused design document linked from the
    roadmap/configuration documentation.

Non-goals

  • Rust implementation, CLI/UI, golden fixture files, Claude Code/Cursor
    adapters, or changes to ConfigExport.
  • Process launch, orchestration, credentials, network access, global host-file
    mutation, import side effects, or execution-parity claims.
  • OpenCode, Antigravity, or non-Codex execution.

Acceptance criteria

  • The specification accounts for every current canonical role-profile field
    and revision identity exactly once.
  • Every field is mapped, explicitly unsupported with a structured reason, or
    rejected; silent loss is impossible.
  • Canonical bytes, digest inputs, ordering, target adapter identity, and
    generated-time behavior are unambiguous.
  • Unsupported security/tool/filesystem/network/test policy cannot degrade to
    a weaker host setting.
  • Dry-run and conformance requirements guarantee no process, credential,
    network, SQLite, or global-config side effect.
  • Claude Code and Cursor can consume the same contract without redefining
    Needle profile truth.
  • Compatibility and security owners approve the contract before
    implementation starts.

Starting points

Validation

Review the field inventory directly against RoleProfileDefinition on current
main and run git diff --check. This design issue requires no Cargo build,
host process, credential, or configuration write.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: adaptersExternal host configuration adaptersconfig-onlyConfiguration export only; no execution integrationdocumentationImprovements or additions to documentationenhancementNew feature or requestneeds-designDesign contract required before implementation

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions