repo-harness-architecture

Use this command when the harness already exists and the user wants a focused architecture documentation, drift-request, or diagram pass.

Protocol

1. Confirm the target repo path and architecture scope.
2. Inspect docs/architecture/index.md, .archcontext/model/nodes/, and pending files under docs/architecture/requests/. For architecture model guidance or a registration scope, follow the coverage procedure below even when no drift request exists.
3. When the scope maps to repo code or config, resolve the capability with:

• repo-harness run capability-resolver match --repo <repo> --path <path> --format json

1. Update the smallest relevant architecture artifact:

• umbrella status in docs/architecture/index.md
• module or snapshot docs under docs/architecture/
• Mermaid fenced block in the relevant module or snapshot Markdown when a visual flow materially helps

1. Use Markdown Mermaid as the only architecture diagram artifact. Do not generate standalone HTML; use the external mermaid skill only to review layout and renderability before shipping the Markdown source.
2. Archive handled requests with:

• repo-harness run archive-architecture-request --request <request> --status <resolved|superseded|rejected|no-change> --artifact <path> --note <text>
• For resolved, the live Pending request must declare > **Architecture Module**: and that exact existing module path must be supplied as an --artifact.

1. Verify with:

• repo-harness run check-architecture-sync
• repo-harness run capability-resolver validate --repo <repo> --format text
• repo-harness run check-task-workflow --strict when repo workflow surfaces changed

Coverage and Agent-owned registration

SessionStart automatically supplies read-only coverage observations when the global architecture provider is enabled and the repo selects capability_source: archcontext. An empty model, missing module docs, unmatched tracked package roots, or multiple packages sharing an ancestor capability are reasons to inspect, not proof that a new capability is required. Hooks do not decide responsibilities or write nodes.

1. Read the existing semantic architecture docs and trace the relevant entrypoints,

dependencies, ownership and verification in source. Use CodeGraph when indexed. Compare repo-harness run capability-resolver list --format json and repo-harness run capability-resolver match --path <source-path> --format json. Package layout is inventory evidence; it does not establish semantic boundaries.

1. Give a concrete recommendation: retain an intentional umbrella, create a justified

capability, or restore a missing projection. Include source evidence, responsibility, proposed prefixes, overlap with existing nodes, contract paths and verification. Within already authorized architecture work, the Agent may decide and execute; do not ask for the same approval again. During unrelated work, keep this as advice.

1. For a new capability, author a complete archcontext.node/v2 body with an

id of capability.<domain>.<name>, kind: capability, status: active, name, summary, responsibilities, source.include, and extensions containing contractFiles.agents, contractFiles.claude, lspProfile, and verification. Use the current model schema and source evidence; do not copy an example's semantics.

1. Resolve the owned archctx executable from

repo-harness architecture-projection status --json (projectionProvider.binaryPath). Require ready status and use that binary with its supported Node runtime in the target repo. Do not install a repo-local archctx or select an unrelated PATH copy. The following archctx notation means that resolved executable:

text archctx plan --id <unique-changeset-id> --path .archcontext/model/nodes/capability.<domain>.<name>.yaml --expected-hash missing --body <complete-YAML-as-one-argument> --format json archctx apply --id <same-changeset-id> --approved --expected-worktree-digest <data.draft.base.worktreeDigest-from-plan> --format json

Inspect the plan's full draft and preview before applying. Keep the same daemon and ChangeSet ID; pass body via a structured process argument, not shell interpolation. --approved records the authorized Agent decision; it does not grant extra scope. If the worktree changed, re-plan and re-inspect. In archctx 0.5.10 this public plan route creates one entity only. It is not an update route: when an existing node must change, report the required update and use a supported typed ChangeSet authoring surface if available; do not overwrite YAML or disguise an update as creation.

1. Run archctx validate --format json, verify source matching with capability-resolver,

then repo-harness architecture-projection plan --json --changed-path <node-path> and repo-harness architecture-projection apply --json --changed-path <node-path>. Verify the expected module document exists and run the protocol's architecture checks. Missing docs for an unchanged node need projection, not a duplicate node. Generated module regions belong to archctx; preserve human-owned prose. Resolve any resulting drift request through the normal request protocol.

Failure Modes

• If no pending architecture request exists, do not invent one. Coverage and registration work can proceed independently; report no-change only after inspecting the requested coverage scope.
• If capability resolution is ambiguous, stop at the matching paths and ask for a narrower scope.
• If check-architecture-sync.sh blocks in strict mode, resolve or archive the pending request card for the touched capability before finishing the worktree.
• If diagram validation fails, fix the Mermaid Markdown source or report the validation failure; do not substitute HTML.

Boundaries

• Does not run repo-harness init.
• Does not install or refresh the full harness.
• Does not let hooks rewrite architecture prose; hooks only record drift requests.
• Does not vendor mermaid; it remains an external authoring/review skill and never owns a product artifact.
• Keeps docs/architecture/requests/ pending-only by archiving handled requests.