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.

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