Repository navigation
Description
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
RoleProfileDefinitionplus 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 toConfigExport. - 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
crates/needle-core/src/role_profile.rscrates/needle-runtime/src/store/role_profiles.rsdocs/ROADMAP.mddocs/CONFIGURATION.md- the compatibility policy produced by Define the explicit OS, toolchain, host, API, configuration, and storage support policy #8
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