repo-harness 0.13.2 → 0.14.0

package/AGENTS.md

@@ -7,7 +7,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
 - `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `repo-harness run sprint-backlog`; task contracts stay the execution slices
-- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
+- `.archcontext/model/nodes/*.yaml` for the capability nodes and longest-prefix context boundaries, selected by `.ai/harness/policy.json#context.capability_source`
 - `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules
 - `docs/researches/` for deep repo knowledge
@@ -25,7 +25,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat hook execution as typed and user-level: `~/.claude/settings.json` and `~/.codex/hooks.json` invoke `repo-harness-hook`, whose route registry selects exactly one in-process handler. `.ai/hooks/lib/workflow-state.sh` is an operator-helper library, never a host-event dispatcher.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
-- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are initialization inputs only, never runtime resolver authority.
+- Treat `.archcontext/model/nodes/*.yaml` as the source of truth for capability prefixes under `capability_source: "archcontext"`; `agent-context-blocks.txt` and nested agent files are initialization inputs only, never runtime resolver authority.
 - Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.

package/CLAUDE.md

@@ -7,7 +7,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
 - `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `repo-harness run sprint-backlog`; task contracts stay the execution slices
-- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
+- `.archcontext/model/nodes/*.yaml` for the capability nodes and longest-prefix context boundaries, selected by `.ai/harness/policy.json#context.capability_source`
 - `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules
 - `docs/researches/` for deep repo knowledge
@@ -25,7 +25,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat hook execution as typed and user-level: `~/.claude/settings.json` and `~/.codex/hooks.json` invoke `repo-harness-hook`, whose route registry selects exactly one in-process handler. `.ai/hooks/lib/workflow-state.sh` is an operator-helper library, never a host-event dispatcher.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
-- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are initialization inputs only, never runtime resolver authority.
+- Treat `.archcontext/model/nodes/*.yaml` as the source of truth for capability prefixes under `capability_source: "archcontext"`; `agent-context-blocks.txt` and nested agent files are initialization inputs only, never runtime resolver authority.
 - Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.

package/README.es.md

@@ -466,8 +466,8 @@ repositorio adopte la misma política.
 
 ## Versión actual
 
-- Paquete npm: `repo-harness@0.13.2`
-- Sello de workflow generado: `repo-harness@0.13.2+template@0.13.2`
+- Paquete npm: `repo-harness@0.14.0`
+- Sello de workflow generado: `repo-harness@0.14.0+template@0.14.0`
 - Repositorio de GitHub: `Ancienttwo/repo-harness`
 - Notas de versión e historial: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -461,8 +461,8 @@ adopte la même policy.
 
 ## Release actuelle
 
-- Package npm : `repo-harness@0.13.2`
-- Generated workflow stamp : `repo-harness@0.13.2+template@0.13.2`
+- Package npm : `repo-harness@0.14.0`
+- Generated workflow stamp : `repo-harness@0.14.0+template@0.14.0`
 - Dépôt GitHub : `Ancienttwo/repo-harness`
 - Notes et historique de release : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -469,8 +469,8 @@ commit script や hooks に組み込まないでください。
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.13.2`
-- Generated workflow stamp：`repo-harness@0.13.2+template@0.13.2`
+- npm package：`repo-harness@0.14.0`
+- Generated workflow stamp：`repo-harness@0.14.0+template@0.14.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes and history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -441,8 +441,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.13.2`
-- Generated workflow stamp: `repo-harness@0.13.2+template@0.13.2`
+- npm package: `repo-harness@0.14.0`
+- Generated workflow stamp: `repo-harness@0.14.0+template@0.14.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -448,8 +448,8 @@ policy。
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.13.2`
-- Generated workflow stamp：`repo-harness@0.13.2+template@0.13.2`
+- npm package：`repo-harness@0.14.0`
+- Generated workflow stamp：`repo-harness@0.14.0+template@0.14.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes 和 history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/AGENTS.md

@@ -14,7 +14,7 @@ Keep this file focused on the local contract for this primary functional block.
 
 ## Positioning
 
-Owns the workflow-engine-contract-assets capability boundary declared in .ai/context/capabilities.json.
+Owns the workflow-engine-contract-assets capability boundary declared in .archcontext/model/nodes.
 
 ## Source Map
 

package/assets/CLAUDE.md

@@ -14,7 +14,7 @@ Keep this file focused on the local contract for this primary functional block.
 
 ## Positioning
 
-Owns the workflow-engine-contract-assets capability boundary declared in .ai/context/capabilities.json.
+Owns the workflow-engine-contract-assets capability boundary declared in .archcontext/model/nodes.
 
 ## Source Map
 

package/assets/hooks/AGENTS.md

@@ -26,7 +26,7 @@ Keep this file focused on the local contract for this primary functional block.
 
 ## Positioning
 
-Owns the runtime-harness-hook-adapters capability boundary declared in .ai/context/capabilities.json.
+Owns the runtime-harness-hook-adapters capability boundary declared in .archcontext/model/nodes.
 
 ## Source Map
 

package/assets/hooks/CLAUDE.md

@@ -26,7 +26,7 @@ Keep this file focused on the local contract for this primary functional block.
 
 ## Positioning
 
-Owns the runtime-harness-hook-adapters capability boundary declared in .ai/context/capabilities.json.
+Owns the runtime-harness-hook-adapters capability boundary declared in .archcontext/model/nodes.
 
 ## Source Map
 

package/assets/reference-configs/external-tooling.md

@@ -687,6 +687,157 @@ managed files by hand:
 ~/.codex/agents/harness-evaluator.toml
 ```
 
+## ArchContext Capability Source
+
+`.ai/harness/policy.json#context.capability_source` selects the single capability
+authority for a repo:
+
+| Value | Authority | Read path |
+|---|---|---|
+| `registry` (default) | `.ai/context/capabilities.json` | JSON capability registry |
+| `archcontext` | `.archcontext/model/nodes/*.yaml` | `archcontext.node/v2` capability nodes |
+
+Exactly one source is read. There is no dual-read, no merge, and no fallback in
+either direction: under `archcontext` a missing model directory fails instead of
+falling back to the JSON registry, and under `registry` a present model
+directory is never consulted. Under `archcontext` the JSON registry is not
+writable, so `repo-harness run capability-config add` refuses and points at the
+node files.
+
+Capability authority does not require the `archctx` CLI: node files are read
+directly with Bun's native YAML parser, so selecting `capability_source` never
+spawns a daemon or external process. Bun older than 1.3 has no `Bun.YAML`; that
+fails closed with upgrade guidance and only when `capability_source` is
+`archcontext`.
+
+Architecture projection is a separate authority. When
+`architecture.projection_provider=archctx`, repo-harness resolves the exact
+version from the consumer dependency tree, executes only that package's declared
+`bin.archctx`, performs a JSON capability handshake, and rejects PATH-only,
+escaping, or mismatched installations. The advisory
+global-tool detector below does not satisfy projection readiness; use
+`repo-harness architecture-projection status --json`. The provider remains
+disabled by default until the release pin is cut over.
+
+When enabled, PostEdit writes only `change_observed` v2 journal records. Stop
+coalesces all eligible records into one durable projection job, excludes
+ArchContext-owned `docs/architecture/**` and declared agent-context targets,
+and acknowledges the source records only after a typed projection receipt is
+durable. Process, timeout, stale-snapshot, invalid-result, and refresh failures
+remain pending for three attempts before an explicit dead-letter transition.
+Preflight failures are jobs too. Each pending journal slot has a stable source
+key while its delivery event id rotates on every coalesced edit; a dead letter
+blocks aggregate jobs containing that source key, so later edits cannot reset
+its attempt budget. Store transitions and queue/dead-letter read models share
+one repository lock. One repository has at most one claimed provider process.
+If the Stop owner disappears, its running claim remains quarantined for 150
+seconds—longer than the 120-second provider bound—before recovery can start a
+new attempt; an abandoned third attempt then transitions directly to dead-letter.
+Before a retry is claimed, the job refreshes delivery ids for its existing
+stable source keys, so edits incorporated before the new snapshot can be
+acknowledged while edits arriving during projection remain pending.
+`ArchitectureRefreshSignalV1` is the only major-change refresh authority; the
+consumer does not infer impact from path names, diff size, or queue-helper
+stdout. A typed refresh-required signal runs the canonical architecture,
+context-contract, and capability-context writers even when the legacy queue
+helper creates no drift card. SessionStart and
+`repo-harness architecture-projection drain --json` expose queue state.
+Each successful canonical refresh action is checkpointed by action key before
+the next action runs, so a partial failure resumes without replaying completed
+writers. Missing or stale CLI authority remains a typed refresh failure; it is
+not silently skipped.
+
+Projection delivery failures use the independent
+`architecture.projection_failure_gate` (`advisory` by default); the existing
+`architecture.freshness_gate` retains its merge/drift meaning. A strict
+projection failure can be recovered without deleting runtime evidence via
+`repo-harness architecture-projection retry-dead-letter --job-id <job> --json`.
+An unreadable policy with no active projection queue remains an advisory
+configuration error; it cannot silently promote the default gate to strict.
+The runtime snapshot excludes `.ai/harness/**`, so concurrent harness receipts
+and traces cannot invalidate a provider snapshot.
+
+Managed host adapters give only `Stop.default` 150 seconds so the configured
+120-second provider bound has control-plane margin. Every other managed route
+remains at 30 seconds, and installer refresh replaces only repo-harness-owned
+entries while preserving sibling user hooks.
+
+Before rolling back to a runtime that only understands journal v1, disable the
+projection provider with the current runtime, run
+`repo-harness architecture-projection drain --json`, and verify the pending
+journal count reported as `sourceJournalPending` is zero. The manual drain owns
+the same selective source acknowledgement as Stop. Downgrading with v2
+observations still pending is not a supported rollback state.
+
+### `source.include` grammar
+
+Upstream matches an include glob against the whole repo-relative path, so a
+wildcard-free literal addresses one file, not a directory subtree. To keep the
+two authorities from disagreeing about what a boundary covers, only two shapes
+are accepted:
+
+| Include | Capability prefix |
+|---|---|
+| `src/core/adoption/**` | `src/core/adoption` |
+| `AGENTS.md` (wildcard-free, not an existing directory) | `AGENTS.md` |
+
+Everything else fails closed. A wildcard-free literal that names an existing
+directory is rejected as ambiguous with guidance to write `<dir>/**`.
+`source.exclude` is not supported, because capability prefixes have no exclusion
+form. Include order is preserved as prefix order.
+
+### Required node fields
+
+| Capability field | Node source | Rule |
+|---|---|---|
+| `domain` / `name` | `id` segments 2 and 3 | `id` must be exactly `capability.<domain>.<name>`, with no `namespace::` prefix |
+| display `name` | `name` | required non-empty node/v2 field; validated but not translated into registry identity |
+| `summary` | `summary` | required non-empty node/v2 field; validated but not translated into registry semantics |
+| `responsibilities` | `responsibilities` | required non-empty string array; validated but not translated into registry semantics |
+| `id` | derived | `<domain>-<name>` |
+| `architecture_module` | derived | `docs/architecture/modules/<domain>/<name>.md` |
+| `workstream_dir` | derived | `tasks/workstreams/<domain>/<name>` |
+| `prefixes` | `source.include` | include grammar above |
+| `contract_files` | `extensions.contractFiles.agents` / `.claude` | declared, never derived: root-facing capabilities deliberately do not follow their prefix |
+| `lsp_profile` | `extensions.lspProfile` | required |
+| `verification_hints` | `extensions.verification` | required array; explicit `[]` is allowed |
+
+Nodes whose `kind` is not `capability`, or whose `status` is not `active`, are
+skipped and claim no prefixes. Required node/v2 descriptive fields are validated
+even when they are not translated. Optional fields this bridge does not consume —
+`source.entrypoints`, `ownership`, `interfaces`,
+`criticality`, `riskDomains`, `notes`, `parent` — are ignored rather than
+translated into local semantics.
+
+### Fail-closed conditions
+
+Source-selection failures exit `2`:
+
+| Condition | Behavior |
+|---|---|
+| unknown `capability_source` value | error naming the policy key and legal values |
+| unreadable `.ai/harness/policy.json` | error naming the policy file |
+| missing `.archcontext/model/nodes` under `archcontext` | error; never falls back to the JSON registry |
+| subdirectory or non-`.yaml`/`.yml` entry in the model directory | error naming the entry |
+| unparseable node YAML | error naming the node file |
+| `Bun.YAML` unavailable | error with the Bun upgrade path |
+
+Node-shape failures surface as `ARCHCONTEXT_*` registry diagnostics and make
+`capability-resolver validate` exit `1` with no stdout; missing/empty node/v2
+`name`, `summary`, or `responsibilities` is a structural error and never yields a
+partial registry. Derived registries then go through the same
+validation as the JSON registry, so duplicate ids, duplicate prefixes, and
+invalid paths keep their existing diagnostic codes.
+
+### Node/v2 export round-trip
+
+`repo-harness run capability-resolver export --format archcontext-nodes-v2`
+emits complete `archcontext.node/v2` capability nodes. Existing directory
+prefixes become explicit `<dir>/**` selectors, while file prefixes remain exact.
+The exported `extensions.contractFiles`, `lspProfile`, and `verification` fields
+round-trip through the canonical node/v2 reader without deriving missing
+semantics. The retired `archcontext-boundaries-v1` format is rejected.
+
 ## Manual Brain Vault Export
 
 Long-lived external knowledge may be exported to a brain file vault only through

package/assets/reference-configs/harness-overview.md

@@ -201,6 +201,7 @@ rather than inferring those values from turns, tool names, or timestamps.
 - Use `repo-harness capability-context status|request|sync` to keep paired local context files aligned with the registry. The command writes only the controlled `CAPABILITY CONTEXT` block and preserves hand-authored content plus the separate architecture contract block.
 - `.ai/context/capability-source-map.json` is the optional human-edited source-map manifest for capability positioning and source pointers. Missing entries fall back to registry/architecture/workstream metadata; `--auto-fill-positioning` writes deterministic draft entries explicitly, not from hooks.
 - `.ai/harness/capability-context/` is ignored runtime queue state. Post-edit hooks may enqueue requests, and `SessionStart` only reminds the current agent to run `repo-harness capability-context sync --pending --apply`.
+- `.ai/harness/architecture-projection/` is ignored durable projection runtime state. It owns one running provider job per repository, pending jobs, typed receipts, refresh receipts, and dead letters; source observations are acknowledged only after a terminal receipt. SessionStart exposes the exact oldest dead-letter id for the explicit `architecture-projection retry-dead-letter` recovery command.
 - `SessionStart` also summarizes pending architecture request cards so a resumed agent can see drift debt before claiming finish.
 
 ## Initializer and Runtime Model

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.13.2",
-  "templateVersion": "0.13.2",
+  "version": "0.14.0",
+  "templateVersion": "0.14.0",
   "skillName": "repo-harness",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {

package/assets/skills/repo-harness-cross-review/references/claude-mode.md

@@ -1,18 +1,24 @@
 # Claude provider mode
 
 Runs the Claude Code CLI (`claude -p`) as a read-only reviewer. Claude is
-given only `Read,Grep,Glob` (no `Bash`/`Edit`/`Write`), so it cannot edit
-your code; the review scope's diff text is embedded directly in the prompt
-since Claude has no Bash access to inspect the repo itself.
+started with `--safe-mode` so host hooks, plugins, MCP servers, and repository
+instructions cannot mutate or block the review process while the normal OAuth
+credential remains available. It is given only `Read,Grep,Glob` (no `Bash`/`Edit`/`Write`),
+so it cannot edit your code; the review scope's diff text is embedded directly
+in the prompt since Claude has no Bash access to inspect the repo itself.
 
 ## Model and timeout
 
 - Pinned to the `fable` alias so the external opinion does not silently
   follow the host's default model.
-- If the fable route fails (nonzero exit, no output, and it was not a
-  timeout), retries exactly once on `opus` -- one fallback step, never a
-  loop, and never a fallback to a different provider.
-- Default budget: 330 seconds.
+- If the fable route emits its explicit capacity-limit signal, retries exactly once on `opus`
+  -- one fallback step, never a loop, and never a fallback to a
+  different provider. Other nonzero exits remain failures even if they wrote
+  stdout.
+- Per-attempt default budget: 330 seconds; the bounded two-attempt capacity
+  route therefore has a 660-second worst-case budget.
+- Claude Code must support `--safe-mode`; an older CLI fails closed instead of
+  loading host hooks or silently dropping isolation.
 
 ## Transcript recovery
 

package/assets/templates/helpers/capability-config.ts

@@ -3,7 +3,13 @@ import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { basename, dirname, resolve } from "path";
 import { spawnSync } from "child_process";
 import { fileURLToPath } from "url";
-import { readRegistry as readCapabilityRegistry, type Capability, type CapabilityRegistry } from "./capability-resolver";
+import {
+  CapabilitySourceError,
+  capabilitySourceMode,
+  readRegistry as readCapabilityRegistry,
+  type Capability,
+  type CapabilityRegistry,
+} from "./capability-resolver";
 
 type Registry = CapabilityRegistry;
 
@@ -339,6 +345,14 @@ function createWorkstream(repo: string, capability: Capability): void {
 function main(): void {
   const args = parseArgs(process.argv.slice(2));
   const repo = repoRoot(args.repo);
+  // The JSON registry is a projection target, not an authority, once archcontext
+  // owns capabilities; writing here would create a second authority.
+  if (capabilitySourceMode(repo) === "archcontext") {
+    throw new CapabilitySourceError(
+      `capability source is "archcontext"; ${REGISTRY_PATH} is not writable. ` +
+        "Declare the capability as an archcontext node under .archcontext/model/nodes instead"
+    );
+  }
   const requestedCapability = buildCapability(args, repo);
   const prefixPath = resolve(repo, requestedCapability.prefixes[0]);
   const registry = readRegistry(repo);
@@ -381,5 +395,5 @@ try {
   main();
 } catch (error) {
   console.error(`capability-config: ${(error as Error).message}`);
-  process.exit(1);
+  process.exit((error as { exitCode?: number }).exitCode ?? 1);
 }