Skip to content

Add agent-context projection, path resolve, and ADR-0043 capability contract#85

Merged
Ancienttwo merged 1 commit into
mainfrom
codex/agent-context-provider
Jul 5, 2026
Merged

Add agent-context projection, path resolve, and ADR-0043 capability contract#85
Ancienttwo merged 1 commit into
mainfrom
codex/agent-context-provider

Conversation

@Ancienttwo

Copy link
Copy Markdown
Owner

What / Why

Makes ArchContext the capability-context provider for agentic runtimes. Today repo-harness maintains its own capability filing (.ai/context/capabilities.json plus seven consumers); this slice moves the cross-product contract into ArchContext so every product reads path-ownership and agent-context conventions from one provider instead of reinventing them.

ADR-0043 fixes the cross-product contract:

  • stableId doubles as the capability ID (capability.<domain>.<name>) when kind is capability — no schema change, the existing id pattern already fits.
  • source.include globs are the source of truth for path ownership, resolved by a single-point tie-break: source.exclude disqualifies first, then the most-specific (longest literal-prefix) matching include wins, and an equal-specificity tie is rejected as ambiguous. A node with no source (or an empty include) owns nothing.
  • Non-schema conventions live under extensions (extensions.lspProfile: string, extensions.verification: string[]), per the additive schema-upgrade rule — no schemaVersion bump.
  • agent-context projection semantics: a marker-owned region (BEGIN/END ARCHCONTEXT AGENT CONTEXT, distinct from the ARCHCONTEXT:generated family) in each capability's own CLAUDE.md/AGENTS.md; human-authored content is preserved, only the marker region is replaced.

Implementation:

  • agent-context ProjectionTarget targetType wired across the three hardcoded sites: schema enum (schemas/runtime/projection-target.schema.json), the projection-engine target builder, and the default projection manifest (model-store-yaml).
  • archctx resolve --path <p> CLI: reads the model, applies the ADR-0043 tie-break (implemented exactly once in resolveArchitectureOwnerForPath, which the CLI delegates to), emits a JSON envelope, and sets exit codes 0 = matched, 1 = no-match, 2 = ambiguous. Future adapters call this command rather than re-deriving glob semantics, so the two products cannot drift apart on what "ambiguous" means.
  • The projection-engine's ad hoc flat YAML reader was replaced with the repo's existing parseJsonOrStableYaml (the flat parser could not read nested source.include/extensions, which resolve and agent-context rendering both require). Existing renderer behavior is unchanged.

Verification

Check Result
bun run typecheck pass (exit 0, no errors)
bun test 904 pass / 0 fail (135 files)
bun run test:contracts 147 pass / 0 fail
node scripts/package-boundary-audit.mjs pass (5 workspaces)
Renderer regression (YAML-parser swap) 6 pass / 0 fail
New projection-engine tests (agent-context + resolve) 16 pass / 0 fail
CLI resolve subprocess spot probe exit 0 (match) / 2 (ambiguous) / 1 (no-match)

Tests cover four groups: schema enum acceptance, agent-context target construction + marker rendering, resolve tie-break behaviors (match / exclude / most-specific-wins / ambiguous / no-match / no-source / empty-include), and CLI end-to-end exit codes.

Follow-ups (out of scope — separate next contracts)

  • Widen packages/contracts/src/ledger.ts ProjectionTargetType to include "agent-context" (kept out of this slice's allowed_paths; the runtime validation source of truth is the JSON Schema, which is updated here — the projection-engine uses a structurally identical locally-scoped type in the meantime).
  • Add an ADR-0043 index entry to docs/adr/README.md (out of allowed_paths).
  • Wire agent-context into an actual disk-write path (a docs apply-style command through ChangeSet); renderAgentContextProjection is a pure function today with no CLI-triggered write.

@Ancienttwo
Ancienttwo force-pushed the codex/agent-context-provider branch from d3c473e to 2bbec0c Compare July 5, 2026 20:57
@Ancienttwo
Ancienttwo merged commit fb55303 into main Jul 5, 2026
5 of 8 checks passed
@Ancienttwo
Ancienttwo deleted the codex/agent-context-provider branch July 5, 2026 20:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant