repo-harness 0.19.0 → 0.19.2

package/AGENTS.md

@@ -58,16 +58,19 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 ## Required Checks
 
-Verification is risk-scoped. The active task contract's JSON `Verification Plan`
-owns executable checks; `exit_criteria` owns artifact requirements. Run focused
-tests for every changed behavior. The following repository-integrity checks are required for
-substantive repository changes; `check:hooks` and `check:helpers` catch a
-projection edited without its authoring source in `scripts/`, so that drift fails
-here instead of only in `scripts/check-ci.sh governance`:
+Follow [Testing Policy and Artifact Standards](docs/reference-configs/sprint-contracts.md#testing-policy-and-artifact-standards)
+for test selection, new test/file admission, full-suite justification, evidence
+reuse and test-document creation. The contract's JSON `Verification Plan` is
+its sole executable authority; `exit_criteria` owns artifact requirements.
+
+The following repository-integrity checks remain required for substantive
+repository changes. Projection checks protect the authoring sources in
+`scripts/`, `assets/hooks/` and `assets/reference-configs/`:
 
 ```bash
 bun run check:hooks
 bun run check:helpers
+bun run check:reference-configs
 bash scripts/check-deploy-sql-order.sh
 bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
@@ -76,37 +79,10 @@ bun scripts/inspect-project-state.ts --repo . --format text
 bun src/cli/index.ts init --repo . --dry-run
 ```
 
-Use focused regression tests and the repository-integrity checks above by
-default, including small code and test changes. Run the full
-`bun test --timeout 60000` suite only when the active contract or release gate
-explicitly requires it, or observed cross-module impact cannot be covered by
-named focused checks. A code/test path, diff size, review depth, or changed
-verification script alone is not sufficient justification. Before an expensive
-run, state the uncovered risk, why narrower checks are insufficient, and the
-expected cost. When authoring a contract, apply these same conditions before
-adding a full-suite criterion; copying an unconditional command is not a risk
-assessment.
-
-Freeze the implementation before final acceptance. Execute required expensive
-criteria through `verify-sprint --prepare-acceptance`; declare each executable
-check once in the JSON `Verification Plan`, including phase, cost, evidence
-policy, necessity, and environment inputs. Unchanged retries consume recorded
-execution evidence. Expensive input drift requires an explicit new plan or
-rerun reason; a cache miss never grants permission to rerun. Reviewers consume that evidence rather than
-independently rerunning the suite. Do not list the same test coverage twice in
-the final contract; focused development runs are separate from final acceptance.
-Record changed paths, checks run or reused, and why that coverage is sufficient.
-CI and explicit release gates retain their required checks.
-
-After a passing full suite, a subsequent bounded change does not automatically
-require another full run. Retain the baseline run identity, inspect the actual
-delta, and run its regression/affected checks. The parent updates the contract's
-final criteria to that delta coverage when the full-suite trigger no longer
-applies, recording the baseline and coverage rationale in Acceptance Notes.
-Do not waive an explicit user/release requirement. An old full-suite pass remains
-baseline evidence for its original subject, never a full-suite pass for the new
-subject. Repeat the full suite only for an uncovered integration risk or an
-explicit requirement for that new subject; a cache miss alone is not a trigger.
+Run focused coverage for changed behavior. Existing CI/release gates retain
+their checks. Apply the linked policy before declaring an expensive/full run
+or a new test document; reviewers consume canonical evidence rather than
+independently repeating it.
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
@@ -130,7 +106,7 @@ explicit requirement for that new subject; a cache miss alone is not a trigger.
 - 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/automation-budget.md`
-- Pending architecture request: `docs/architecture/requests/runtime-harness-automation-budget.md`
+- Pending architecture request: `(none)`
 
 ## Active Workstreams
 

package/CLAUDE.md

@@ -58,16 +58,19 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 ## Required Checks
 
-Verification is risk-scoped. The active task contract's JSON `Verification Plan`
-owns executable checks; `exit_criteria` owns artifact requirements. Run focused
-tests for every changed behavior. The following repository-integrity checks are required for
-substantive repository changes; `check:hooks` and `check:helpers` catch a
-projection edited without its authoring source in `scripts/`, so that drift fails
-here instead of only in `scripts/check-ci.sh governance`:
+Follow [Testing Policy and Artifact Standards](docs/reference-configs/sprint-contracts.md#testing-policy-and-artifact-standards)
+for test selection, new test/file admission, full-suite justification, evidence
+reuse and test-document creation. The contract's JSON `Verification Plan` is
+its sole executable authority; `exit_criteria` owns artifact requirements.
+
+The following repository-integrity checks remain required for substantive
+repository changes. Projection checks protect the authoring sources in
+`scripts/`, `assets/hooks/` and `assets/reference-configs/`:
 
 ```bash
 bun run check:hooks
 bun run check:helpers
+bun run check:reference-configs
 bash scripts/check-deploy-sql-order.sh
 bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
@@ -76,37 +79,10 @@ bun scripts/inspect-project-state.ts --repo . --format text
 bun src/cli/index.ts init --repo . --dry-run
 ```
 
-Use focused regression tests and the repository-integrity checks above by
-default, including small code and test changes. Run the full
-`bun test --timeout 60000` suite only when the active contract or release gate
-explicitly requires it, or observed cross-module impact cannot be covered by
-named focused checks. A code/test path, diff size, review depth, or changed
-verification script alone is not sufficient justification. Before an expensive
-run, state the uncovered risk, why narrower checks are insufficient, and the
-expected cost. When authoring a contract, apply these same conditions before
-adding a full-suite criterion; copying an unconditional command is not a risk
-assessment.
-
-Freeze the implementation before final acceptance. Execute required expensive
-criteria through `verify-sprint --prepare-acceptance`; declare each executable
-check once in the JSON `Verification Plan`, including phase, cost, evidence
-policy, necessity, and environment inputs. Unchanged retries consume recorded
-execution evidence. Expensive input drift requires an explicit new plan or
-rerun reason; a cache miss never grants permission to rerun. Reviewers consume that evidence rather than
-independently rerunning the suite. Do not list the same test coverage twice in
-the final contract; focused development runs are separate from final acceptance.
-Record changed paths, checks run or reused, and why that coverage is sufficient.
-CI and explicit release gates retain their required checks.
-
-After a passing full suite, a subsequent bounded change does not automatically
-require another full run. Retain the baseline run identity, inspect the actual
-delta, and run its regression/affected checks. The parent updates the contract's
-final criteria to that delta coverage when the full-suite trigger no longer
-applies, recording the baseline and coverage rationale in Acceptance Notes.
-Do not waive an explicit user/release requirement. An old full-suite pass remains
-baseline evidence for its original subject, never a full-suite pass for the new
-subject. Repeat the full suite only for an uncovered integration risk or an
-explicit requirement for that new subject; a cache miss alone is not a trigger.
+Run focused coverage for changed behavior. Existing CI/release gates retain
+their checks. Apply the linked policy before declaring an expensive/full run
+or a new test document; reviewers consume canonical evidence rather than
+independently repeating it.
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
@@ -130,7 +106,7 @@ explicit requirement for that new subject; a cache miss alone is not a trigger.
 - 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/automation-budget.md`
-- Pending architecture request: `docs/architecture/requests/runtime-harness-automation-budget.md`
+- Pending architecture request: `(none)`
 
 ## Active Workstreams
 

package/README.es.md

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

package/README.fr.md

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

package/README.ja.md

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

package/README.md

@@ -120,6 +120,11 @@ bun test
 
 ### Success looks like this
 
+Successful init enables automatic architecture document projection and proactive
+Stop-hook refactor recommendations when those preferences are unset. Explicit
+disabled choices are preserved. Suggestions present evidence for a user decision;
+they do not authorize a refactor. Dry-run does not write these preferences.
+
 Apply ends with `=== Migration Report ===`, naming where generated hook behavior
 comes from, the user-level `~/.claude/settings.json` and `~/.codex/hooks.json`
 adapter target, the repo-local surfaces created or refreshed, the
@@ -660,8 +665,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.19.0`
-- Generated workflow stamp: `repo-harness@0.19.0+template@0.19.0`
+- npm package: `repo-harness@0.19.2`
+- Generated workflow stamp: `repo-harness@0.19.2+template@0.19.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -630,8 +630,8 @@ commit script 或 hook，除非目标仓库采用同样的 policy。
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.19.0`
-- Generated workflow stamp：`repo-harness@0.19.0+template@0.19.0`
+- npm package：`repo-harness@0.19.2`
+- Generated workflow stamp：`repo-harness@0.19.2+template@0.19.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes 和 history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/agents/fleet/gatekeeper.md

@@ -1,6 +1,6 @@
 ---
 name: gatekeeper
-description: Read-only acceptance and ship gate on Opus at high effort. Use after execution workers deliver work: it reviews the diff against the goal, runs the project's real verification, and returns PASS/FAIL/BLOCKED with evidence and a ship recommendation. It never edits, commits, pushes, opens or merges PRs, or decides to ship; fixes and terminal actions stay with the orchestrator.
+description: Read-only acceptance and ship gate on Opus at high effort. Use after execution workers deliver work: it reviews the diff against the goal, validates the project's verification evidence, and returns PASS/FAIL/BLOCKED with evidence and a ship recommendation. It never edits, commits, pushes, opens or merges PRs, or decides to ship; fixes and terminal actions stay with the orchestrator.
 tools: ["Read", "Grep", "Glob", "Bash"]
 model: opus
 effort: high
@@ -10,8 +10,8 @@ You are the read-only acceptance and ship gate. Execution workers deliver work;
 
 - **Verdict first.** Your opening line is exactly one of `VERDICT: PASS`, `VERDICT: FAIL`, `VERDICT: BLOCKED`. PASS means every gate is clean and you state the recommended next action without performing it. FAIL means blocking findings and nothing touched. BLOCKED means a precondition prevents judgment, such as no verification command, auth failure, merge conflict, moved HEAD, or missing goal manifest.
 - **Worktree safety.** Start with `git status --short --branch -uall` and record `git rev-parse HEAD`. Modified, staged, and untracked files are user work. Never switch branch, stash, reset, clean, discard, stage, or commit them. If HEAD moves or unknown commits appear during review, stop and return BLOCKED.
-- **Acceptance gates.** Scope: every changed file traces to the stated goal. Verification: run the project's real commands and report their actual output. Hard stops include unknown identifiers, version skew, stale generated output, surprise dependencies, hardcoded secrets, sleeps standing in for a completion signal, near-duplicates of an existing canonical helper, special-case branches or one-off mode flags bolted into shared flows the goal does not cover, and pass-through wrappers or `any`/cast churn that obscure an existing contract without the goal requiring it.
+- **Acceptance gates.** Scope: every changed file traces to the stated goal. Verification: follow the repository's testing policy. For contract acceptance, validate canonical subject-bound execution evidence and report check IDs, dispositions and run references; do not rerun checks already covered by valid evidence. Return missing, stale or failed evidence to the execution owner, and uncovered risk to the parent for revised coverage. For review without canonical contract evidence, use the project's scoped verification commands and report actual results. Hard stops include unknown identifiers, version skew, stale generated output, surprise dependencies, hardcoded secrets, sleeps standing in for a completion signal, near-duplicates of an existing canonical helper, special-case branches or one-off mode flags bolted into shared flows the goal does not cover, and pass-through wrappers or `any`/cast churn that obscure an existing contract without the goal requiring it.
 - **Decomposition is recommendation only.** Given a goal manifest, map changes to goals and propose file-granular commit or PR groups. A file entangling goals is a FAIL finding. Unmapped changes are user work and remain untouched. The orchestrator performs any approved split or ship action.
-- **Evidence before claim.** A test, CI result, or ship state counts only if checked in this turn. Before recommending merge, re-read PR and CI status; before recommending push, check local versus remote sync. Never recommend merge on red or stale evidence.
+- **Evidence before claim.** A test, CI result, or ship state counts only if its evidence and applicability are checked in this turn; checking evidence does not require rerunning its producer. Before recommending merge, re-read PR and CI status; before recommending push, check local versus remote sync. Never recommend merge on red or stale evidence.
 - **FAIL returns findings, not fixes.** Each finding is `[CRITICAL|HIGH|MEDIUM] file:line — problem — concrete fix instruction — class(safe_auto|gated_auto|manual)`. You do not edit or patch through any tool.
 - **Sign-off.** Report files changed, scope fit, hard stops, verification command and result, then the recommendation. Lead with the verdict and keep it compact.

package/assets/AGENTS.md

@@ -31,21 +31,21 @@ Owns the workflow-engine-contract-assets capability boundary declared in .archco
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `assets/templates`
+- Functional block: `.ai/harness/policy.json`
 - Capability ID: `workflow-engine-contract-assets`
-- Matched prefix: `assets/templates`
+- Matched prefix: `.ai/harness/policy.json`
 - Architecture domain: `workflow-engine`
 - Architecture capability: `contract-assets`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Last architecture event: 2026-08-05T00:46:13+0800
-- Last changed path: `tasks/workstreams/workflow-engine/contract-assets/github-issues-158-159.md`
-- Severity: medium
-- Change type: workstream-sync
+- Last architecture event: 2026-09-12T11:46:22+0800
+- Last changed path: `.ai/harness/policy.json`
+- Severity: high
+- Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `assets/templates`
+- Entrypoints: `.ai/harness/policy.json`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
 - Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
-- Runtime path: `assets/templates`
+- Runtime path: `.ai/harness/policy.json`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`

package/assets/CLAUDE.md

@@ -31,21 +31,21 @@ Owns the workflow-engine-contract-assets capability boundary declared in .archco
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `assets/templates`
+- Functional block: `.ai/harness/policy.json`
 - Capability ID: `workflow-engine-contract-assets`
-- Matched prefix: `assets/templates`
+- Matched prefix: `.ai/harness/policy.json`
 - Architecture domain: `workflow-engine`
 - Architecture capability: `contract-assets`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Last architecture event: 2026-08-05T00:46:13+0800
-- Last changed path: `tasks/workstreams/workflow-engine/contract-assets/github-issues-158-159.md`
-- Severity: medium
-- Change type: workstream-sync
+- Last architecture event: 2026-09-12T11:46:22+0800
+- Last changed path: `.ai/harness/policy.json`
+- Severity: high
+- Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `assets/templates`
+- Entrypoints: `.ai/harness/policy.json`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
 - Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
-- Runtime path: `assets/templates`
+- Runtime path: `.ai/harness/policy.json`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`

package/assets/hooks/lib/workflow-state.sh

@@ -1352,8 +1352,11 @@ workflow_write_run_summary() {
     return 0
   fi
 
+  # Same field set as the jq branch above: run-summary retention identifies this
+  # record by its shape, so a short fallback would make every jq-less host's
+  # summaries permanently unreclaimable.
   cat > "$output_file" <<EOF_RUN
-{"generated_at":"$(workflow_json_escape "$(date '+%Y-%m-%dT%H:%M:%S%z')")","run_id":"$(workflow_json_escape "$run_id")","reason":"$(workflow_json_escape "$reason")","checks_file":"$(workflow_json_escape "$(workflow_checks_file)")","handoff_file":"$(workflow_json_escape "$(workflow_handoff_file)")"}
+{"generated_at":"$(workflow_json_escape "$(date '+%Y-%m-%dT%H:%M:%S%z')")","run_id":"$(workflow_json_escape "$run_id")","reason":"$(workflow_json_escape "$reason")","active_plan":"$(workflow_json_escape "${active_plan:-}")","active_contract":"$(workflow_json_escape "${active_contract:-}")","active_review":"$(workflow_json_escape "${active_review:-}")","active_notes":"$(workflow_json_escape "${active_notes:-}")","checks_file":"$(workflow_json_escape "$(workflow_checks_file)")","handoff_file":"$(workflow_json_escape "$(workflow_handoff_file)")","policy_file":"$(workflow_json_escape "$(workflow_policy_file)")","context_map_file":"$(workflow_json_escape "$(workflow_context_map_file)")"}
 EOF_RUN
 }
 

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

@@ -53,6 +53,7 @@ cross-review/merge-gate rows.
 | Check deploy and ops config | `repo-harness-check` (deploy-readiness reference) | Read-only deploy/_ops readiness check without publishing |
 | Fix broken current harness behavior | `repo-harness-setup` (repair mode) | Task sync, hook routing, handoff, context, policy, or helper drift |
 | Verify readiness | `repo-harness-check` | Workflow gates, task sync, inspector, migration dry-run, and readiness yellow flags |
+| Write, run, refactor, or document repo-harness source tests | `repo-harness-test` | Routing plus repo-specific technique only; `sprint-contracts.md` keeps the testing policy, and no mode runs a test or writes acceptance evidence |
 | Independent outside review | `repo-harness-cross-review` | Claude host uses direct Codex; Codex host uses OpenAI's official `codex@openai-codex` plugin app-server mode; installed on both hosts for full; never produces a merge-gate receipt |
 | Generate an upper-layer PRD | `repo-harness-product` (PRD mode) | `$geju` direction pass, Claude-first `claude -p --model opus` drafting, Codex fallback only when needed, PRD in `plans/prds/*.prd.md`; geju thesis/falsifier are pre-contract only and freeze into a delegated contract's `## Why`/`## Falsifier` |
 | Plan and run a program-level sprint | `repo-harness-product` (Sprint mode) | Upper-layer PRD in `plans/prds/`, sprint backlog in `plans/sprints/`; each row expands through `$think` before plan -> contract -> worktree |

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

@@ -930,17 +930,51 @@ 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
+Architecture projection execution is user-level configuration in
+`~/.repo-harness/config.json#architecture`. `repo-harness install` and
+`repo-harness update` initialize it once with `projection_provider: "archctx"`,
+`projection_apply: "automatic"`, `projection_failure_gate: "advisory"`, and
+`projection_timeout_ms: 120000`. Repeated setup preserves an explicit global
+choice, including disabled. Malformed or partial settings fail closed without
+rewriting the file; unrelated user settings are preserved. The exact provider
+version is owned by the packaged release contract, not a configurable repo pin.
+
+`repo-harness init` remains a repository-only transaction. Standard/self-host adoption
+removes retired `architecture.projection_*` execution keys from repo policy and
+reports global provider readiness, without writing user configuration or
+inventing the project's model. Minimal adoption does not author a policy.
+Runtime does not read or merge retired repo execution settings. Capability
+identity, model files, documentation ownership and project freshness gates
+remain repository-local. Missing model/adoption evidence still blocks apply;
+global automatic mode does not authorize ownership adoption or semantic acceptance.
+
+Use `repo-harness architecture-projection policy --json` to inspect the global
+source path, initialization state and effective execution settings without a
+provider process. `repo-harness architecture-projection status --json` adds the
+exact package capability handshake and project apply readiness. The running
+repo-harness package owns the `archctx` executable and exact dependency version;
+its dependency tree is refreshed by the global update transaction. A target
+repository's `node_modules/archctx` never overrides that runtime dependency.
+Source-checkout execution uses that checkout's repo-harness dependencies, and
+candidate verification may explicitly select the candidate package root.
+Missing or mismatching runtime dependencies still fail closed with no target-repo
+fallback. Project model, ownership and snapshot checks remain repository-local.
+
+SessionStart also gives the Agent read-only model coverage guidance under this
+global provider setting; no per-repo execution toggle is needed. It observes empty
+capability models, missing declared module documents, and tracked package roots
+with no capability match or a shared ancestor capability. These are bounded
+inspection prompts, not inferred semantic nodes. The Agent uses the
+`repo-harness-architecture` skill to inspect source evidence and decide boundaries
+within the authorized task, then creates nodes through archctx ChangeSets and
+runs the existing projection. An intentional umbrella is valid. Hooks do not
+write model YAML, and unrelated coverage findings remain advice. The manifest
+inventory is limited to Git-tracked `package.json` paths; this is not a complete
+semantic coverage audit for every language or untracked source tree. Inspection
+errors become SessionStart provider diagnostics instead of invented model facts.
+
+When enabled, Stop observes the Git changed set and coalesces eligible paths
+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
@@ -1125,3 +1159,37 @@ repo-harness run check-brain-manifest
 repo-harness run sync-brain-docs --all
 repo-harness run sync-brain-docs --check
 ```
+
+
+## Proactive refactor recommendations
+
+`~/.repo-harness/config.json#refactor_recommendations` contains `{ "enabled": true }`
+by default. Global install/update initializes the setting once and preserves an
+explicit disabled choice. Repositories do not need another enable switch.
+
+At normal Stop, repo-harness observes ArchContext structural candidates when a
+project model is present. It uses the packaged exact provider contract and
+existing lifecycle readback; it does not require or change execution activation.
+Only complete, non-truncated code facts with unambiguous ownership produce a
+recommendation. The observer never creates an index or model on the user's behalf.
+
+The Agent receives at most three candidates and is instructed to explain the
+measured evidence, inferred benefit and risk, then ask the user whether to
+proceed, defer or decline. No author, recommendation record/acceptance,
+Work Package, program or code edit is triggered by observation. User approval
+uses the normal approved-plan workflow and its existing execution gates.
+
+Observation gets at most ten seconds within Stop's existing twenty-second
+shared work budget, with a five-minute scan cooldown. A delivery ledger retains up to 4096
+recommendation identity/fingerprint pairs without eviction. At capacity, automatic
+delivery pauses with an explicit diagnostic; existing identities remain suppressed.
+The explicit CLI still permits observation without consuming delivery history. The one-shot
+Stop continuation ends after presenting the choice; waiting for an answer does
+not hold Stop in a loop. State and the last observation are stored in the ignored
+`.ai/harness/runs/refactor-recommendations.json`; they are delivery evidence,
+not user approval or upstream recommendation status.
+
+`repo-harness refactor recommendations --repo <root> --json` explicitly reads
+current opportunities through the same observer, without consuming Stop's
+delivery history or requiring `refactor discover`'s author activation. It returns
+readiness/error status when evidence is unavailable; it never invents a candidate.

package/assets/reference-configs/hook-operations.md

@@ -129,6 +129,52 @@ contains the generated operator-helper projection. Keep the two declared asset
 manifests aligned with `bun run sync:hooks`, and validate the typed route
 registry with `bun test` and `repo-harness init --repo . --dry-run`.
 
+## Evidence Retention
+
+`.ai/harness/runs/` holds four record shapes from five writers, and only one of
+them is disposable history:
+
+| File | Writer | Retention owner |
+| --- | --- | --- |
+| `${runId}.json` carrying the four resolved projection paths | Stop (`stop-handler.ts`) and `workflow_write_run_summary` in `assets/hooks/lib/workflow-state.sh` | `run-summary-retention.ts`, at the end of every Stop: newest `RUN_SUMMARY_RETENTION_COUNT` |
+| `${runId}-${contractSlug}.json` (`schema: repo-harness-run-trace.v1`) | `verify-sprint.sh` | none; a checks projection reads it back at acceptance finalization |
+| `verification-${executionId}.json` / `.log` | `verification-execution.ts` | none; immutable, bound by sha256 in the evidence ledger |
+| `hook-events.jsonl` | hook telemetry | `hook-event-log.ts`, on rotation: 8 MB segments, 256 MB or 32 archived segments |
+| ad-hoc `*.json` reports | operator scripts | none; each report owns its own file |
+
+Evidence checkpoints under `.ai/harness/evidence/checkpoints/` are owned by
+`checkpoint-store.ts`, which keeps only the checkpoint the published marker
+names and prunes inside every successful publish.
+
+The three unowned rows are not leaks. Operator reports own their own files; the
+other two are durable evidence. A frozen acceptance
+snapshot shares Stop's `run-` prefix, and a missing verification record makes
+`readValidRunResult` report an absent baseline, which fails a
+`baseline_with_delta` criterion permanently because a rerun only mints a new
+execution id. Retention therefore never reasons about what to keep: it deletes
+only records with Stop's own run-summary shape -- a `run_id` plus
+`checks_file`, `handoff_file`, `policy_file`, and `context_map_file`, every one
+a pointer the next Stop recomputes -- and leaves every other shape to its owner.
+The shape, not `reason`: that field is free-form operator text.
+
+Checkpoint retention was added in 0.19.0. A repository upgraded from an earlier
+version carries a checkpoint per Stop, each one a whole-ledger snapshot -- on a
+long-running repository that reaches multiple gigabytes. The next successful Stop
+after the upgrade prunes the entire backlog on its own, so no action is normally
+required.
+
+Run `repo-harness run evidence-gc` when that Stop will not come:
+
+```bash
+repo-harness run evidence-gc --repo . --dry-run   # report reclaimable bytes
+repo-harness run evidence-gc --repo .             # apply the same policies now
+```
+
+It applies the two policies above and never defines its own. Use it for a
+repository whose ledger was reset (publication skips quietly with no ledger), one
+that no longer runs the harness, or when the space is needed before the next
+Stop. It exits non-zero and names every entry it could not reclaim.
+
 ## Verification Checklist
 
 After handler or workflow-contract changes, run:

package/assets/reference-configs/release-deploy.md

@@ -12,6 +12,13 @@ This repo keeps deployment contract surfaces under `deploy/` and private runtime
 state under ignored `_ops/`. Detailed release patterns, Cloudflare examples, and
 rollback playbooks belong in the external runbook.
 
+Tests whose cost is a real package install or a real external program are gated
+behind `REPO_HARNESS_TEST_EXPENSIVE` and are therefore not part of the hosted
+`scripts/check-ci.sh functional` lane. The release gate is the lane that owns
+them: `bun run check:release` (and a bare local `bash scripts/check-ci.sh`) runs
+the `all` lane, which exports that variable before the suite, while
+`prepublishOnly` stays a fast pre-publish check that never runs tests.
+
 ## Webapp Release Shape
 
 - For a SaaS webapp with public SEO/SSR plus authenticated workspace, prefer one