repo-harness 0.13.2 → 0.14.1

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/`.
@@ -90,7 +90,6 @@ bun src/cli/index.ts init --repo . --dry-run
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/verification/evals-checks.md`
-- Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams

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/`.
@@ -90,7 +90,6 @@ bun src/cli/index.ts init --repo . --dry-run
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/verification/evals-checks.md`
-- Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams

package/README.es.md

@@ -446,7 +446,7 @@ son dependencias empaquetadas ordinarias.
 | --- | --- | --- |
 | [Hylarucoder](https://x.com/hylarucoder) / Geju | El método de due diligence P1/P2/P3 y la práctica Geju que dieron forma a la disciplina de planning, tracing y decision-rationale de este workflow | Contribución metodológica y agradecimiento; no es una dependencia empaquetada |
 | Waza de [TW93](https://x.com/HiTw93), incluyendo `think`, `hunt`, `check` y `health` | Planning diario, bug hunts, verificación, health checks y sync de skill Codex-first | Instalado a través del skills CLI en los host skill roots |
-| `mermaid` | Diagramas de architecture y system-flow legibles por humanos cuando Mermaid no alcanza | Skill runtime-referenced, no vendored en los repos generados |
+| `mermaid` | Soporte de authoring y review para bloques Mermaid fenced dentro de la documentación de arquitectura | Skill externo runtime-referenced, no vendored en los repos generados y sin generar HTML standalone |
 | CodeGraph (`@colbymchenry/codegraph`) | Navegación symbol-aware, impact tracing y readiness checks para este repo self-host | Dev dependency en este repo; los repos generados se mantienen global-MCP-first salvo que la policy haga opt-in |
 | [Oracle](https://github.com/steipete/oracle) de [Peter Steinberger](https://x.com/steipete) (`@steipete/oracle`, MIT) | Motor de consulta de navegador GPT Pro / ChatGPT Web por defecto, al que el Oracle provider `chatgpt-browser` invoca externamente (shell out) para las consultas `gptpro` | Binario resuelto externamente (`--oracle-bin`, `REPO_HARNESS_ORACLE_BIN`, `node_modules/.bin`, o `PATH`); nunca se descarga automáticamente, y un binario ausente es un fallo duro de `ORACLE_NOT_INSTALLED` |
 | OpenAI Codex | Agente de ejecución primario para implementación repo-local, verificación y GitHub contributor attribution cuando un commit incluye materialmente trabajo escrito por Codex | Un runtime de agente externo; la atribución es un trailer de commit explícito, no automatización oculta de hooks |
@@ -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.1`
+- Sello de workflow generado: `repo-harness@0.14.1+template@0.14.1`
 - Repositorio de GitHub: `Ancienttwo/repo-harness`
 - Notas de versión e historial: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -441,7 +441,7 @@ pas des dépendances embarquées ordinaires.
 | --- | --- | --- |
 | [Hylarucoder](https://x.com/hylarucoder) / Geju | Méthode de due-diligence P1/P2/P3 et pratique Geju qui ont façonné la discipline de planning, de trace et de decision-rationale dans ce workflow | Contribution méthodologique et remerciement ; pas une dépendance embarquée |
 | Waza par [TW93](https://x.com/HiTw93), incluant `think`, `hunt`, `check` et `health` | Planning quotidien, bug hunts, vérification, health checks et skill sync Codex-first | Installé via le skills CLI dans les host skill roots |
-| `mermaid` | Diagrammes d'architecture et de system-flow lisibles par un humain quand Mermaid seul ne suffit pas | Skill référencé au runtime, non vendored dans les dépôts générés |
+| `mermaid` | Support d'authoring et de review pour les blocs Mermaid fenced dans la documentation d'architecture | Skill externe référencé au runtime, non vendored dans les dépôts générés et ne générant pas de HTML standalone |
 | CodeGraph (`@colbymchenry/codegraph`) | Navigation symbol-aware, impact tracing et readiness checks pour ce dépôt self-host | Dev dependency dans ce dépôt ; les dépôts générés restent global-MCP-first sauf opt-in de la policy |
 | [Oracle](https://github.com/steipete/oracle) par [Peter Steinberger](https://x.com/steipete) (`@steipete/oracle`, MIT) | Moteur par défaut de consult navigateur GPT Pro / ChatGPT Web, que le provider Oracle `chatgpt-browser` invoque en shell out pour les consults `gptpro` | Binaire résolu en externe (`--oracle-bin`, `REPO_HARNESS_ORACLE_BIN`, `node_modules/.bin`, ou `PATH`) ; jamais téléchargé automatiquement, et un binaire manquant est une erreur franche `ORACLE_NOT_INSTALLED` |
 | OpenAI Codex | Agent d'exécution principal pour l'implémentation repo-local, la vérification, et l'attribution de contributeur GitHub quand un commit inclut matériellement du travail écrit par Codex | Agent runtime externe ; l'attribution est un commit trailer explicite, pas une automatisation cachée par hook |
@@ -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.1`
+- Generated workflow stamp : `repo-harness@0.14.1+template@0.14.1`
 - Dépôt GitHub : `Ancienttwo/repo-harness`
 - Notes et historique de release : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -449,7 +449,7 @@ agent runtime を中心に構築されています。これらは通常の bundl
 | --- | --- | --- |
 | [Hylarucoder](https://x.com/hylarucoder) / Geju | この workflow における planning、tracing、decision-rationale の規律を形作った P1/P2/P3 due-diligence method と Geju の実践 | Methodology への貢献と謝辞であり、bundled dependency ではありません |
 | Waza by [TW93](https://x.com/HiTw93)(`think`、`hunt`、`check`、`health` を含む) | 日々の planning、bug hunt、verification、health check、Codex-first な skill sync | skills CLI を通じて host の skill root にインストールされます |
-| `mermaid` | Mermaid だけでは足りないときの、人間が読める architecture / system-flow diagram | Runtime で参照される skill であり、生成されたリポジトリには vendor されません |
+| `mermaid` | architecture 文書内の Mermaid fenced block に対する authoring / review 支援 | Runtime で参照される外部 skill であり、生成されたリポジトリには vendor されず、standalone HTML も生成しません |
 | CodeGraph(`@colbymchenry/codegraph`) | この self-host リポジトリのための symbol-aware navigation、impact tracing、readiness check | 本リポジトリでは dev dependency。生成されたリポジトリは、policy が opt-in しない限り global-MCP-first のままです |
 | [Oracle](https://github.com/steipete/oracle) by [Peter Steinberger](https://x.com/steipete)(`@steipete/oracle`、MIT) | `chatgpt-browser` の Oracle provider が `gptpro` consult のために shell out する、既定の GPT Pro / ChatGPT Web browser consult engine | 外部で解決される binary(`--oracle-bin`、`REPO_HARNESS_ORACLE_BIN`、`node_modules/.bin`、または `PATH`)。自動ダウンロードはされず、binary が見つからない場合は hard な `ORACLE_NOT_INSTALLED` failure になります |
 | OpenAI Codex | commit が実質的に Codex 作成の作業を含むときの、repo-local な実装・verification・GitHub contributor attribution を担う primary execution agent | 外部 agent runtime。attribution は隠れた hook automation ではなく、明示的な commit trailer です |
@@ -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.1`
+- Generated workflow stamp：`repo-harness@0.14.1+template@0.14.1`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes and history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -422,7 +422,7 @@ dependencies.
 | --- | --- | --- |
 | [Hylarucoder](https://x.com/hylarucoder) / Geju | P1/P2/P3 due-diligence method and Geju practice that shaped the planning, tracing, and decision-rationale discipline in this workflow | Methodology contribution and acknowledgement; not a bundled dependency |
 | Waza by [TW93](https://x.com/HiTw93), including `think`, `hunt`, `check`, and `health` | Daily planning, bug hunts, verification, health checks, and Codex-first skill sync | Installed through the skills CLI into host skill roots |
-| `mermaid` | Human-readable architecture and system-flow diagrams when Mermaid is not enough | Runtime-referenced skill, not vendored into generated repos |
+| `mermaid` | Authoring and readability review for Mermaid architecture and system-flow source | Runtime-referenced review skill, not vendored into generated repos and never an HTML artifact generator |
 | CodeGraph (`@colbymchenry/codegraph`) | Symbol-aware navigation, impact tracing, and readiness checks for this self-host repo | Dev dependency in this repo; generated repos stay global-MCP-first unless policy opts in |
 | [Oracle](https://github.com/steipete/oracle) by [Peter Steinberger](https://x.com/steipete) (`@steipete/oracle`, MIT) | Default GPT Pro / ChatGPT Web browser consult engine that the `chatgpt-browser` Oracle provider shells out to for `gptpro` consults | Externally-resolved binary (`--oracle-bin`, `REPO_HARNESS_ORACLE_BIN`, `node_modules/.bin`, or `PATH`); never auto-downloaded, and a missing binary is a hard `ORACLE_NOT_INSTALLED` failure |
 | OpenAI Codex | Primary execution agent for repo-local implementation, verification, and GitHub contributor attribution when a commit materially includes Codex-authored work | External agent runtime; attribution is an explicit commit trailer, not hidden hook automation |
@@ -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.1`
+- Generated workflow stamp: `repo-harness@0.14.1+template@0.14.1`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -428,7 +428,7 @@ dependency。
 | --- | --- | --- |
 | [Hylarucoder](https://x.com/hylarucoder) / Geju | P1/P2/P3 due-diligence 方法和 Geju 实践，塑造了这套 workflow 里 planning、tracing 和 decision-rationale 的纪律 | 方法论贡献和致谢；不是 bundled dependency |
 | [TW93](https://x.com/HiTw93) 的 Waza，包括 `think`、`hunt`、`check` 和 `health` | 日常 planning、bug hunt、verification、health check，以及 Codex-first 的 skill sync | 通过 skills CLI 安装进 host skill root |
-| `mermaid` | 当 Mermaid 不够用时，提供人类可读的 architecture 和 system-flow 图 | Runtime-referenced 的 skill，不会 vendor 进生成的仓库 |
+| `mermaid` | 为架构文档中的 Mermaid fenced blocks 提供 authoring 和 review 支持 | Runtime-referenced 的外部 skill，不会 vendor 进生成的仓库，也不会生成 standalone HTML |
 | CodeGraph（`@colbymchenry/codegraph`） | 为这个 self-host 仓库提供 symbol-aware 导航、impact tracing 和 readiness check | 本仓库的 dev dependency；生成的仓库默认保持 global-MCP-first，除非 policy 显式开启 |
 | [Peter Steinberger](https://x.com/steipete) 的 [Oracle](https://github.com/steipete/oracle)（`@steipete/oracle`，MIT） | `chatgpt-browser` 的 Oracle provider 为 `gptpro` consult 默认 shell 出去调用的 GPT Pro / ChatGPT Web 浏览器 consult 引擎 | 外部解析的 binary（`--oracle-bin`、`REPO_HARNESS_ORACLE_BIN`、`node_modules/.bin` 或 `PATH`）；从不自动下载，缺失 binary 会硬失败 `ORACLE_NOT_INSTALLED` |
 | OpenAI Codex | repo-local 实现和验证的主要执行 agent；commit 实质包含 Codex 产出内容时，也承担 GitHub contributor attribution | 外部 agent runtime；attribution 是显式的 commit trailer，不是隐藏的 hook automation |
@@ -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.1`
+- Generated workflow stamp：`repo-harness@0.14.1+template@0.14.1`
 - 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
 
@@ -50,7 +50,6 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams

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
 
@@ -50,7 +50,6 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams

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
 
@@ -62,7 +62,6 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams

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
 
@@ -62,7 +62,6 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams

package/assets/partials/05-workflow.partial.md

@@ -40,7 +40,7 @@ PLAN_LOOP:
 - Small or medium feature plans -> Waza `/think`.
 - Bugs, regressions, crashes, errors, or failing tests -> Waza `/hunt`.
 - Implemented diffs, pre-merge checks, or release follow-through -> Waza `/check`.
-- Architecture diagrams or system-flow diagrams -> Markdown Mermaid first, `mermaid` for optional human HTML.
+- Architecture diagrams or system-flow diagrams -> Markdown Mermaid only; use `mermaid` for authoring and review, never standalone HTML output.
 - Use P1/P2/P3 as the shared due-diligence protocol; report it explicitly for complex engineering or architecture planning, `/hunt`, risky refactors, deployments, auth/payment/data work, and shared contracts.
 - Hooks may emit advisory Waza `/check` and `/health` route hints, but must not auto-run skills or vendor skill bodies.
 

package/assets/reference-configs/agentic-development-flow.md

@@ -15,7 +15,7 @@ root prompt concise; this file owns the detailed routing.
 | Small or medium feature/fix plan | Waza `/think` | Concise approved plan, then implementation on request |
 | Bug, regression, error, crash, failing test | Waza `/hunt` | Root cause sentence with evidence before any fix |
 | Implemented diff, pre-merge, release follow-through | Waza `/check` | Review findings, safe fixes, verification, and shipment state |
-| Architecture diagram or system-flow diagram | Markdown Mermaid first, `mermaid` for human HTML | Semantic Mermaid in architecture docs plus optional rendered HTML grounded in repo context |
+| Architecture diagram or system-flow diagram | Markdown Mermaid only; `mermaid` assists authoring and review | Evidence-backed Mermaid fenced blocks in architecture Markdown; no standalone HTML |
 
 ### Parent Agent Planning Ownership
 

package/assets/reference-configs/document-generation.md

@@ -19,7 +19,6 @@ Create these only when the agent has concrete repo evidence or the user asks:
 - `docs/decisions.md`: accepted architecture decisions with trade-offs.
 - `docs/architecture/snapshots/*.md`: current module boundaries and data flow for architecture-sensitive changes.
 - Mermaid fenced blocks in `docs/architecture/modules/**.md` or `docs/architecture/snapshots/*.md`: semantic diagram source for agents and review diffs.
-- `docs/architecture/diagrams/*.html`: optional human-readable `mermaid` renderings produced when a visual is clearer than prose.
 - `docs/packages.md`: package inventory for real multi-package repos.
 - `plans/prds/*.prd.md`: upper-layer PRDs generated through `repo-harness-product`'s PRD mode from `.claude/templates/prd.template.md`; keep Sprint backlogs in `plans/sprints/`.
 
@@ -33,7 +32,7 @@ Create these only when the agent has concrete repo evidence or the user asks:
 - Let capability `CLAUDE.md` and `AGENTS.md` carry local contract projections; root docs stay concise.
 - Keep complete workstream TODOs in `tasks/workstreams/<domain>/<capability>/`; contract blocks should link to them instead of becoming task logs.
 - Keep onboarding docs split by reader: agents read active source artifacts first; humans review the Human Review Card, diff, latest trace, and rollback first.
-- Hooks may create `docs/architecture/requests/*.md`; agents own semantic snapshots, embedded Mermaid, and optional `mermaid` HTML output.
+- Hooks may create `docs/architecture/requests/*.md`; agents own semantic snapshots and embedded Mermaid source.
 - Archive handled architecture requests with `repo-harness run archive-architecture-request`; keep `docs/architecture/requests/` pending-only and preserve handled requests under `docs/architecture/requests/archive/YYYY/`. A `Resolved` request must declare its `Architecture Module` and include that exact existing module as a durable `--artifact`.
-- When both Mermaid and HTML exist, keep the Mermaid in Markdown as the semantic source and make the HTML link back to that Markdown source.
-- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy or inline its assets into generated repos.
+- Treat Markdown Mermaid as the only architecture diagram artifact; do not generate standalone HTML.
+- Treat `mermaid` as an external authoring/review skill at `~/.codex/skills/mermaid`; do not copy or inline its assets into generated repos.

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-commands/repo-harness-architecture/SKILL.md

@@ -19,8 +19,7 @@ architecture documentation, drift-request, or diagram pass.
    - 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
-   - optional human-readable diagram artifact under `docs/architecture/diagrams/`
-5. Use Markdown Mermaid as the semantic diagram source; use `mermaid` only for optional human-readable HTML renderings grounded in observed repo files.
+5. 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.
 6. 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`.
@@ -34,12 +33,12 @@ architecture documentation, drift-request, or diagram pass.
 - If no pending architecture request exists, report `no-change` and do not invent one.
 - 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 rendering fails, keep the Mermaid Markdown source and report the render failure.
+- 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 installed skill for optional human-readable HTML.
+- 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.

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.13.2",
-  "templateVersion": "0.13.2",
+  "version": "0.14.1",
+  "templateVersion": "0.14.1",
   "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/architecture-event.ts

@@ -377,9 +377,8 @@ function renderRequiredFollowUp(event: ArchitectureEvent): string {
     "- If functional block is not `root`, read its local `AGENTS.md` / `CLAUDE.md`.",
     "- Decide whether this change affects module boundaries, entrypoints, dependency rules, runtime paths, or verification commands.",
     "- For substantial changes, write a snapshot under `docs/architecture/snapshots/`.",
-    "- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.",
-    "- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.",
-    "- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.",
+    "- When a visual materially improves the explanation, add an evidence-backed Mermaid fenced block to the architecture module or snapshot Markdown.",
+    "- Mermaid Markdown is the only architecture diagram artifact. Do not generate standalone HTML; use the external `mermaid` skill only for authoring and review.",
     `- If this starts or advances durable execution, run \`repo-harness run workstream-sync ensure --block "${functionalBlock}" --request "${requestFile}"\`.`,
     "- After the snapshot or diagram is produced, run `repo-harness run context-contract-sync sync-latest` so the local architecture contract block links to the latest artifacts.",
   ].join("\n");
@@ -693,7 +692,6 @@ function renderContractBlock(args: Args): string {
   const workstreamDir = requireOption(args, "workstreamDir");
   const blockSlug = safeToken(functionalBlock);
   const latestSnapshot = findLatestMatchingFile("docs/architecture/snapshots", blockSlug, ".md");
-  const latestHumanDiagram = findLatestMatchingFile("docs/architecture/diagrams", blockSlug, ".html");
   const semanticDiagramSource = latestSnapshot === "(none yet)" ? architectureModule : latestSnapshot;
   const eventTs = args.options.eventTs || "unknown";
   const filePath = args.options.filePath || "unknown";
@@ -725,7 +723,6 @@ function renderContractBlock(args: Args): string {
     "- Verification: Use root required checks plus local commands recorded in this capability contract.",
     `- Latest snapshot: \`${latestSnapshot}\``,
     `- Semantic diagram source: \`${semanticDiagramSource}\``,
-    `- Latest human diagram: \`${latestHumanDiagram}\``,
     `- Pending architecture request: \`${requestFile}\``,
     "",
     "## Active Workstreams",

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);
 }