repo-harness 0.19.4 → 0.20.0

package/AGENTS.md

@@ -1,120 +1,57 @@
-# repo-harness AGENTS.md
-
-This repository self-hosts the `repo-harness` contract; the former `repo-harness-skill` and `project-initializer` names have been fully removed and are no longer recognized by any tooling. Claude and Codex should follow the same repo-local workflow surface.
-
-## Canonical Workflow Files
-
-- `tasks/current.md` for the ignored local current-status read model 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
-- `.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
-- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
-- `plans/` for timestamped plans, with `plans/archive/` for history
-- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
-- `.ai/harness/policy.json` for the machine-readable workflow contract
-- `.ai/context/context-map.json` for progressive context loading
-- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
-- `docs/reference-configs/agentic-development-flow.md` for parent-agent/Waza routing and P1/P2/P3 rules
-
-## Operating Rules
-
-- Sync `tasks/` whenever substantive repo changes are made.
-- 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 `.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/`.
-- Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
-- Treat `.ai/harness/checks/*.latest.{json,md}` and `.ai/harness/runs/` as ignored runtime evidence cache; commit durable conclusions in `tasks/reviews/`, `tasks/contracts/`, `tasks/notes/`, or `docs/researches/` instead.
-- Treat architecture/spec/research docs as the human reading entrypoint. Before closing a workflow, promote durable conclusions into `docs/architecture/`, `docs/researches/`, `docs/spec.md`, or `tasks/lessons.md`; then archive fulfilled plan/contract/review/notes/todo artifacts so root workflow surfaces represent active work only. When a brain root is configured, a durable conclusion worth reusing across projects may additionally be projected into the vault through an explicit `obsidian-memory` persist call; the vault layer is optional and never a prerequisite for closing a workflow. `.rgignore` hides archived workflow artifacts and runtime evidence from default `rg` searches; use explicit paths or `rg -uu` for audits.
-- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
-- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files, and env examples; follow `.ai/harness/policy.json#operations.deploy_sql` for configured SQL roots and naming modes, otherwise keep SQL directly under `deploy/sql/` with 4-digit ascending prefixes.
-- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
-- Treat contract-level task execution as worktree-first: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
-- Treat the EXECUTION_BOUNDARY anti-extras clause as mandatory exactly once in each delegated runner's final rendered task packet: absent requirements are forbidden design space, not permission to improve, and unrequested extras fail closed. Each runner path names one injection owner and no other surface on that path may carry the clause — the Codex native-child path is owned by `SubagentStart.context` (contract- and writability-aware; generated personas and the delegation advisor carry none), the standalone contract worker path by its worker prompt, and the MCP path by the `codex-goal` document. Composed-path tests verify the count.
-- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
-- Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
-- If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
-- Route product discovery and complex/design planning to the parent agent: use `geju` for pre-contract framing, complete P1/P2/P3 with the parent agent's own capabilities, and freeze the accepted direction into the plan and contract. Route daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`. Route a proactive multi-direction visual/UX choice mid-task to the design-options convention (`repo-harness docs show design-options`).
-- Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `mermaid` from `~/.codex/skills`.
-- Keep durable repo knowledge in `docs/researches/`, `tasks/lessons.md`, and the canonical workflow artifacts.
-- Treat `.ai/harness/brain-manifest.json` and `repo-harness run sync-brain-docs` as explicit operator-invoked export surfaces only; hooks and workflow checks must not read, write, or gate on external brain-vault state.
-- Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. The managed skills are `think`, `hunt`, `check`, and `health`; stage upstream Waza, copy their complete skill directories and shared rules into Codex, and verify with `diff`/`cmp` as described in `docs/reference-configs/external-tooling.md`.
-- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
-- When changing adoption planner or transaction code, verify `repo-harness init --repo . --dry-run` and a fixture apply use the same TS operation model.
-- Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
+# repo-harness
+
+## Workflow
+- For non-trivial work, follow the global Progressive Due Diligence rule (P1 map, P2 trace, P3 decision) before design decisions or code edits.
+- Keep root CLAUDE.md and AGENTS.md as standalone regular files; repeat shared rules in both and keep host-specific guidance separate.
+- Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome.
+- Write output text (docs, PR descriptions, commit messages, reports) in ASD-STE100 Simplified Technical English: short sentences, one idea per sentence, active voice, approved-dictionary words; write Chinese output the same way, with short sentences and one idea per sentence.
+- Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No mandatory plan/contract/review/notes chain; notes are only for non-obvious decisions.
+- Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
+- Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Tag authorized publication and record `git revert <squash-commit>` plus the daily report.
+- Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
+- Use gatekeeper/cross-model review for large changes, security/permissions, or unresolved model uncertainty; ordinary steps record diagnostics without approval loops.
+- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/external-tooling.md#herdr-dispatch).
+- GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
+- When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
+- `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
+- Preserve `agents/fleet/`, release checklists and downstream `assets/templates` / `assets/partials*`. Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` aligned.
+- `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
 ## Code Optimization Principles
-
-- Reason from first principles: identify observable conditions, controllable inputs, the invariant, and the actual pressure point before changing structure.
-- Keep one source of truth for each datum; every other representation must be a deterministic projection with a drift check.
-- Do not add steady-state compatibility code, dual authority, semantic fallbacks, aliases, or shadow parsers. Explicit one-shot migrations must fail closed and remove the retired path in the same work-package.
-- Create shared components only for observed reuse or a cross-module invariant. Prefer an existing monorepo workspace only when independently meaningful consumers need the shared package; do not convert this single-package repo without that boundary.
-
-## Required Checks
-
-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
-bash scripts/check-task-workflow.sh --strict
-bun scripts/inspect-project-state.ts --repo . --format text
-bun src/cli/index.ts init --repo . --dry-run
-```
-
-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
-
-- Functional block: `src/effects/automation`
-- Capability ID: `runtime-harness-automation-budget`
-- Matched prefix: `src/effects/automation`
-- Architecture domain: `runtime-harness`
-- Architecture capability: `automation-budget`
-- Architecture module: `docs/architecture/modules/runtime-harness/automation-budget.md`
-- Last architecture event: 2026-09-08T05:10:12+0800
-- Last changed path: `src/effects/automation/campaign-capability-registry.ts`
-- Severity: low
-- Change type: source-change
-- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `src/effects/automation`
-- 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: `src/effects/automation`
-- LSP/tooling profile: `typescript-lsp`
-- 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: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/automation-budget`.
-- `tasks/current.md` is the ignored local derived status read model; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
-<!-- END ARCHITECTURE CONTRACT -->
+- Identify observable conditions, controllable inputs, the invariant and the actual pressure point before changing structure.
+- Keep one source of truth for each datum; other representations are deterministic projections with drift checks.
+- Do not add steady-state compatibility code, dual authority, semantic fallbacks, aliases or shadow parsers; one-shot migrations fail closed and remove the retired path.
+- Share components only for observed reuse or a cross-module invariant. Use an existing workspace only for independently meaningful consumers; do not convert this single-package repo without that boundary.
+- Prefer platform/standard-library features, then installed dependencies, and the smallest direct implementation; shrink obsolete code before adding layers.
+- Never satisfy a requirement with a substitute that only looks compliant (mocks, hard-coded values, images posing as the real thing); say what cannot be done and flag the deviation in the PR.
+- Self-review before committing: remove dead code, empty branches and debug leftovers, and split functions by responsibility instead of one large block.
+
+## Testing
+- Run `bun run check:type` plus tests covering the changed behavior once after the implementation is stable.
+- Use `bun run test:files <affected tests> --timeout 60000 --max-concurrency 1`; extend existing coverage before creating a new test file.
+- Select tests by observable risk and owning runtime boundary, including error/recovery paths when affected.
+- Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting.
+- Reviewers consume the recorded command, result, revision and environment; they do not rerun passing checks to claim ownership.
+- Changed inputs or a new uncovered failure justify affected delta checks; an old pass is only historical evidence for its old subject.
+- Run the full suite daily; a failure opens an automatic repair task and appears in the daily report.
+- Isolate mutable HOME, repositories and process state; use real synchronization signals and preserve complete failure output.
+- Report failed, timed-out, incomplete or omitted coverage explicitly; do not manufacture receipts, waiver files or pre-fix logs.
+- Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description.
+
+## Handoff
+- Create a checkpoint only when context/session rollover or unresolved work needs it; ordinary completion stays in the PR description.
+- Read files named in the current request before recovery context.
+- Record the goal, branch/worktree/HEAD, decisions, touched files, verification results, blockers and one exact next command.
+- Keep temporary checkpoints under ignored `.ai/harness/handoff/`; historical snapshots are not current execution authority.
+- Include evidence paths and actual command outcomes; distinguish observed state from inference.
+- Never include secrets, tokens or real environment files in handoff text.
+- On resume, verify the live checkout and source artifacts before reusing a result; `tasks/current.md` is an optional local read model.
+- Preserve dirty work and other workers' edits; hand back an ownership conflict instead of discarding their changes.
+
+## Codex
+- Own backend implementation and testing; Claude owns frontend implementation and interaction, and the parent coordinates scope and integration.
+- User-level `~/.codex/hooks.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Repo-local hook adapters are retired; `.ai/hooks/lib/workflow-state.sh` is an operator helper.
+- Use `~/.codex/skills` as the runtime skill source; `~/.agents/skills` is staging/cache only. Keep `think`, `hunt`, `check` and `health` updates verified before runtime use.
+- The Codex automation profile requires runtime-provided `health`, `check` and `mermaid`; do not vendor their bodies.
+- Treat auto-compact as a fallback; prepare ignored `.ai/harness/handoff/current.md` and `resume.md` when long-task rollover is needed.
+- Keep this file short; load [development flow](docs/reference-configs/agentic-development-flow.md) and [external tooling](docs/reference-configs/external-tooling.md) only when needed.

package/CLAUDE.md

@@ -1,120 +1,56 @@
-# repo-harness AGENTS.md
-
-This repository self-hosts the `repo-harness` contract; the former `repo-harness-skill` and `project-initializer` names have been fully removed and are no longer recognized by any tooling. Claude and Codex should follow the same repo-local workflow surface.
-
-## Canonical Workflow Files
-
-- `tasks/current.md` for the ignored local current-status read model 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
-- `.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
-- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
-- `plans/` for timestamped plans, with `plans/archive/` for history
-- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
-- `.ai/harness/policy.json` for the machine-readable workflow contract
-- `.ai/context/context-map.json` for progressive context loading
-- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
-- `docs/reference-configs/agentic-development-flow.md` for parent-agent/Waza routing and P1/P2/P3 rules
-
-## Operating Rules
-
-- Sync `tasks/` whenever substantive repo changes are made.
-- 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 `.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/`.
-- Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
-- Treat `.ai/harness/checks/*.latest.{json,md}` and `.ai/harness/runs/` as ignored runtime evidence cache; commit durable conclusions in `tasks/reviews/`, `tasks/contracts/`, `tasks/notes/`, or `docs/researches/` instead.
-- Treat architecture/spec/research docs as the human reading entrypoint. Before closing a workflow, promote durable conclusions into `docs/architecture/`, `docs/researches/`, `docs/spec.md`, or `tasks/lessons.md`; then archive fulfilled plan/contract/review/notes/todo artifacts so root workflow surfaces represent active work only. When a brain root is configured, a durable conclusion worth reusing across projects may additionally be projected into the vault through an explicit `obsidian-memory` persist call; the vault layer is optional and never a prerequisite for closing a workflow. `.rgignore` hides archived workflow artifacts and runtime evidence from default `rg` searches; use explicit paths or `rg -uu` for audits.
-- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
-- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files, and env examples; follow `.ai/harness/policy.json#operations.deploy_sql` for configured SQL roots and naming modes, otherwise keep SQL directly under `deploy/sql/` with 4-digit ascending prefixes.
-- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
-- Treat contract-level task execution as worktree-first: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
-- Treat the EXECUTION_BOUNDARY anti-extras clause as mandatory exactly once in each delegated runner's final rendered task packet: absent requirements are forbidden design space, not permission to improve, and unrequested extras fail closed. Each runner path names one injection owner and no other surface on that path may carry the clause — the Codex native-child path is owned by `SubagentStart.context` (contract- and writability-aware; generated personas and the delegation advisor carry none), the standalone contract worker path by its worker prompt, and the MCP path by the `codex-goal` document. Composed-path tests verify the count.
-- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
-- Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
-- If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
-- Route product discovery and complex/design planning to the parent agent: use `geju` for pre-contract framing, complete P1/P2/P3 with the parent agent's own capabilities, and freeze the accepted direction into the plan and contract. Route daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`. Route a proactive multi-direction visual/UX choice mid-task to the design-options convention (`repo-harness docs show design-options`).
-- Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `mermaid` from `~/.codex/skills`.
-- Keep durable repo knowledge in `docs/researches/`, `tasks/lessons.md`, and the canonical workflow artifacts.
-- Treat `.ai/harness/brain-manifest.json` and `repo-harness run sync-brain-docs` as explicit operator-invoked export surfaces only; hooks and workflow checks must not read, write, or gate on external brain-vault state.
-- Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. The managed skills are `think`, `hunt`, `check`, and `health`; stage upstream Waza, copy their complete skill directories and shared rules into Codex, and verify with `diff`/`cmp` as described in `docs/reference-configs/external-tooling.md`.
-- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
-- When changing adoption planner or transaction code, verify `repo-harness init --repo . --dry-run` and a fixture apply use the same TS operation model.
-- Treat repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.
+# repo-harness
+
+## Workflow
+- For non-trivial work, follow the global Progressive Due Diligence rule (P1 map, P2 trace, P3 decision) before design decisions or code edits.
+- Keep root CLAUDE.md and AGENTS.md as standalone regular files; repeat shared rules in both and keep host-specific guidance separate.
+- Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome.
+- Write output text (docs, PR descriptions, commit messages, reports) in ASD-STE100 Simplified Technical English: short sentences, one idea per sentence, active voice, approved-dictionary words; write Chinese output the same way, with short sentences and one idea per sentence.
+- Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No mandatory plan/contract/review/notes chain; notes are only for non-obvious decisions.
+- Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
+- Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Tag authorized publication and record `git revert <squash-commit>` plus the daily report.
+- Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
+- Use gatekeeper/cross-model review for large changes, security/permissions, or unresolved model uncertainty; ordinary steps record diagnostics without approval loops.
+- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/external-tooling.md#herdr-dispatch).
+- GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
+- When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
+- `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
+- Preserve `agents/fleet/`, release checklists and downstream `assets/templates` / `assets/partials*`. Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` aligned.
+- `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
 ## Code Optimization Principles
-
-- Reason from first principles: identify observable conditions, controllable inputs, the invariant, and the actual pressure point before changing structure.
-- Keep one source of truth for each datum; every other representation must be a deterministic projection with a drift check.
-- Do not add steady-state compatibility code, dual authority, semantic fallbacks, aliases, or shadow parsers. Explicit one-shot migrations must fail closed and remove the retired path in the same work-package.
-- Create shared components only for observed reuse or a cross-module invariant. Prefer an existing monorepo workspace only when independently meaningful consumers need the shared package; do not convert this single-package repo without that boundary.
-
-## Required Checks
-
-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
-bash scripts/check-task-workflow.sh --strict
-bun scripts/inspect-project-state.ts --repo . --format text
-bun src/cli/index.ts init --repo . --dry-run
-```
-
-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
-
-- Functional block: `src/effects/automation`
-- Capability ID: `runtime-harness-automation-budget`
-- Matched prefix: `src/effects/automation`
-- Architecture domain: `runtime-harness`
-- Architecture capability: `automation-budget`
-- Architecture module: `docs/architecture/modules/runtime-harness/automation-budget.md`
-- Last architecture event: 2026-09-08T05:10:12+0800
-- Last changed path: `src/effects/automation/campaign-capability-registry.ts`
-- Severity: low
-- Change type: source-change
-- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `src/effects/automation`
-- 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: `src/effects/automation`
-- LSP/tooling profile: `typescript-lsp`
-- 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: `(none)`
-
-## Active Workstreams
-
-- (none yet)
-
-## Current Session Projection
-
-- Durable progress lives under `tasks/workstreams/runtime-harness/automation-budget`.
-- `tasks/current.md` is the ignored local derived status read model; it is not a live lock or task source.
-- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
-<!-- END ARCHITECTURE CONTRACT -->
+- Identify observable conditions, controllable inputs, the invariant and the actual pressure point before changing structure.
+- Keep one source of truth for each datum; other representations are deterministic projections with drift checks.
+- Do not add steady-state compatibility code, dual authority, semantic fallbacks, aliases or shadow parsers; one-shot migrations fail closed and remove the retired path.
+- Share components only for observed reuse or a cross-module invariant. Use an existing workspace only for independently meaningful consumers; do not convert this single-package repo without that boundary.
+- Prefer platform/standard-library features, then installed dependencies, and the smallest direct implementation; shrink obsolete code before adding layers.
+- Never satisfy a requirement with a substitute that only looks compliant (mocks, hard-coded values, images posing as the real thing); say what cannot be done and flag the deviation in the PR.
+- Self-review before committing: remove dead code, empty branches and debug leftovers, and split functions by responsibility instead of one large block.
+
+## Testing
+- Run `bun run check:type` plus tests covering the changed behavior once after the implementation is stable.
+- Use `bun run test:files <affected tests> --timeout 60000 --max-concurrency 1`; extend existing coverage before creating a new test file.
+- Select tests by observable risk and owning runtime boundary, including error/recovery paths when affected.
+- Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting.
+- Reviewers consume the recorded command, result, revision and environment; they do not rerun passing checks to claim ownership.
+- Changed inputs or a new uncovered failure justify affected delta checks; an old pass is only historical evidence for its old subject.
+- Run the full suite daily; a failure opens an automatic repair task and appears in the daily report.
+- Isolate mutable HOME, repositories and process state; use real synchronization signals and preserve complete failure output.
+- Report failed, timed-out, incomplete or omitted coverage explicitly; do not manufacture receipts, waiver files or pre-fix logs.
+- Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description.
+
+## Handoff
+- Create a checkpoint only when context/session rollover or unresolved work needs it; ordinary completion stays in the PR description.
+- Read files named in the current request before recovery context.
+- Record the goal, branch/worktree/HEAD, decisions, touched files, verification results, blockers and one exact next command.
+- Keep temporary checkpoints under ignored `.ai/harness/handoff/`; historical snapshots are not current execution authority.
+- Include evidence paths and actual command outcomes; distinguish observed state from inference.
+- Never include secrets, tokens or real environment files in handoff text.
+- On resume, verify the live checkout and source artifacts before reusing a result; `tasks/current.md` is an optional local read model.
+- Preserve dirty work and other workers' edits; hand back an ownership conflict instead of discarding their changes.
+
+## Claude Code
+- Own frontend implementation and interaction; Codex owns backend implementation and testing, and the parent coordinates scope and integration.
+- Use Claude Code's available tools within granted permissions; changes to tool grants, hooks or confirmation bypass require approval of the exact change.
+- User-level `~/.claude/settings.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Repo-local hook adapters are retired; `.ai/hooks/lib/workflow-state.sh` is an operator helper.
+- Write comments, commits and PR text from the final diff; comments explain non-obvious reasons, and PRs describe final behavior and material rationale.
+- Keep this file short; load [development flow](docs/reference-configs/agentic-development-flow.md) and [external tooling](docs/reference-configs/external-tooling.md) only when needed.