repo-harness 0.1.0 → 0.1.2

package/AGENTS.md

@@ -1,12 +1,13 @@
-# agentic-dev AGENTS.md
+# repo-harness AGENTS.md
 
-This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
+This repository self-hosts the `repo-harness` contract, formerly `repo-harness-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
 
 ## Canonical Workflow Files
 
-- `tasks/todo.md` for the current execution checklist and verification notes
+- `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
+- `tasks/todo.md` for deferred medium/long-term goals, not active execution checklists
 - `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
-- `tasks/workstreams/` for capability long-running workstreams that project the current slice into `tasks/todo.md`
+- `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules
 - `tasks/research.md` for deep repo knowledge
 - `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
@@ -21,7 +22,7 @@ This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-ski
 
 - Sync `tasks/` whenever substantive repo changes are made.
 - Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
-- Treat `.ai/hooks/` as the shared hook implementation, `.claude/settings.json` as the Claude adapter, and `.codex/hooks.json` as the Codex adapter.
+- Treat `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.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 compatibility inputs only.
 - Keep architecture drift handling split: `architecture-drift.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.
@@ -32,7 +33,7 @@ This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-ski
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - 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: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
-- After Codex Plan mode, Waza `/think`, or `agentic-dev-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --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` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --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` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
 - 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 to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
@@ -41,7 +42,7 @@ This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-ski
 - Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
 - 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 `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
-- Treat `.codex/hooks.json` as a product hook adapter; do not treat generated backup files or other `.codex/*` runtime residue as product deliverables.
+- 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.
 
 ## Required Checks
 
@@ -57,26 +58,27 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `assets/hooks`
+- Functional block: `.ai/hooks`
 - Capability ID: `runtime-harness-hook-adapters`
-- Matched prefix: `assets/hooks`
+- Matched prefix: `.ai/hooks`
 - Architecture domain: `runtime-harness`
 - Architecture capability: `hook-adapters`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Last architecture event: 2026-05-28T15:48:16+0800
-- Last changed path: `assets/hooks/hook-input.sh`
+- Last architecture event: 2026-05-29T09:44:46+0800
+- Last changed path: `.ai/hooks/session-start-context.sh`
 - Severity: high
 - Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `assets/hooks`
+- Entrypoints: `.ai/hooks`
 - 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/hooks`
+- Runtime path: `.ai/hooks`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
-- Latest diagram: `(none yet)`
-- Pending architecture request: `docs/architecture/requests/20260528-154816-assets-hooks-assets-hooks-hook-input-sh.md`
+- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md`
 
 ## Active Workstreams
 
@@ -85,5 +87,6 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 ## Current Session Projection
 
 - Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
 - `tasks/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/CLAUDE.md

@@ -1,12 +1,13 @@
-# agentic-dev AGENTS.md
+# repo-harness AGENTS.md
 
-This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
+This repository self-hosts the `repo-harness` contract, formerly `repo-harness-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
 
 ## Canonical Workflow Files
 
-- `tasks/todo.md` for the current execution checklist and verification notes
+- `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
+- `tasks/todo.md` for deferred medium/long-term goals, not active execution checklists
 - `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
-- `tasks/workstreams/` for capability long-running workstreams that project the current slice into `tasks/todo.md`
+- `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules
 - `tasks/research.md` for deep repo knowledge
 - `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
@@ -21,7 +22,7 @@ This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-ski
 
 - Sync `tasks/` whenever substantive repo changes are made.
 - Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
-- Treat `.ai/hooks/` as the shared hook implementation, `.claude/settings.json` as the Claude adapter, and `.codex/hooks.json` as the Codex adapter.
+- Treat `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.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 compatibility inputs only.
 - Keep architecture drift handling split: `architecture-drift.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.
@@ -32,7 +33,7 @@ This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-ski
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - 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: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
-- After Codex Plan mode, Waza `/think`, or `agentic-dev-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --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` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --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` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
 - 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 to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
@@ -41,7 +42,7 @@ This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-ski
 - Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
 - 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 `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
-- Treat `.codex/hooks.json` as a product hook adapter; do not treat generated backup files or other `.codex/*` runtime residue as product deliverables.
+- 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.
 
 ## Required Checks
 
@@ -57,26 +58,27 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `assets/hooks`
+- Functional block: `.ai/hooks`
 - Capability ID: `runtime-harness-hook-adapters`
-- Matched prefix: `assets/hooks`
+- Matched prefix: `.ai/hooks`
 - Architecture domain: `runtime-harness`
 - Architecture capability: `hook-adapters`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Last architecture event: 2026-05-28T15:48:16+0800
-- Last changed path: `assets/hooks/hook-input.sh`
+- Last architecture event: 2026-05-29T09:44:46+0800
+- Last changed path: `.ai/hooks/session-start-context.sh`
 - Severity: high
 - Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `assets/hooks`
+- Entrypoints: `.ai/hooks`
 - 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/hooks`
+- Runtime path: `.ai/hooks`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
-- Latest diagram: `(none yet)`
-- Pending architecture request: `docs/architecture/requests/20260528-154816-assets-hooks-assets-hooks-hook-input-sh.md`
+- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md`
 
 ## Active Workstreams
 
@@ -85,5 +87,6 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 ## Current Session Projection
 
 - Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
 - `tasks/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/README.md

@@ -1,16 +1,104 @@
-# agentic-dev
+# repo-harness
 
-Repo-local agentic development harness skill for Claude/Codex workflows.
-Formerly `agentic-dev-skill` and `project-initializer`; `agentic-dev-skill`
-remains a compatibility alias, while `project-initializer` install paths are
-retired and removed by installed-copy sync.
-Repository: `https://github.com/Ancienttwo/agentic-dev`
+Repo-local agentic development harness CLI and skill runtime for Claude/Codex
+workflows. The npm package and primary command are now `repo-harness`.
+`repo-harness-skill` remains a compatibility alias, while `project-initializer`
+install paths are retired and removed by installed-copy sync.
+Repository: `https://github.com/Ancienttwo/repo-harness`
+
+[English](README.md) | [简体中文](README.zh-CN.md)
 
 This repository now dogfoods its own tasks-first contract. It is both:
 
-- the source repo for the `agentic-dev` skill
+- the source repo for the `repo-harness` CLI and `repo-harness` skill runtime
 - a self-hosted example of the repo-local workflow it generates for other projects
 
+## What repo-harness Does
+
+`repo-harness` turns AI-assisted development from chat-memory coordination into
+repo-local workflow state. It installs a small, file-backed contract into a
+target repository so Claude, Codex, and humans can agree on:
+
+- what product intent is stable
+- which plan is approved for execution
+- what the current sprint contract allows
+- which checks and review evidence prove the work is done
+- how hooks should warn, block, trace, and hand off work across sessions
+
+It is not an agent gateway, product runtime, database service, or MCP server.
+The product boundary is deliberately boring: inspect a repo, install or refresh
+workflow files, route host events through repo-local hooks, and verify that the
+workflow surfaces stay consistent.
+
+## How It Works
+
+The design has three layers:
+
+1. **Source package**: this repository owns the CLI, command skill facades,
+   templates, hook assets, workflow contract, tests, and release gate.
+2. **Target repo contract**: `repo-harness init` or migration writes repo-local
+   files such as `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`,
+   `.ai/harness/`, helper scripts, and `.ai/hooks/`.
+3. **Host adapters**: user-level `~/.claude/settings.json` and
+   `~/.codex/hooks.json` route Claude/Codex events into `repo-harness-hook`.
+   The hook entrypoint exits silently for non-opt-in repos and dispatches into
+   the current repo's `.ai/hooks/*` scripts only when
+   `.ai/harness/workflow-contract.json` exists.
+
+The core invariant is that durable truth lives in the repo, not in a chat
+thread. Hooks are accelerators and guardrails; the authority remains the
+file-backed plan, contract, review, checks, and handoff artifacts.
+
+## Task Workflow: Plan to Closeout
+
+The diagram below assumes the harness is already installed in the repo. It shows
+the normal task lifecycle: plan, project into a sprint contract, check out the
+contract worktree when policy requires it, implement under hooks, verify, review,
+and close out.
+
+```mermaid
+flowchart TD
+  UserTask["User task or planning prompt"] --> Discovery["Due diligence<br/>P1 map, P2 trace, P3 decision"]
+  Discovery --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
+  PlanDraft --> PlanReview{"Plan ready for execution?"}
+  PlanReview -->|no| Refine["Refine plan, scope, evidence contract"]
+  Refine --> PlanDraft
+  PlanReview -->|yes| Approve["Approved plan<br/>Status: Approved"]
+
+  Approve --> Project["Project plan into execution<br/>capture-plan.sh --execute<br/>or plan-to-todo.sh --plan"]
+  Project --> Active["Active markers<br/>.ai/harness/active-plan<br/>.ai/harness/active-worktree"]
+  Project --> Contract["Sprint contract<br/>tasks/contracts/task-slug.contract.md"]
+  Project --> ReviewFile["Review file<br/>tasks/reviews/task-slug.review.md"]
+  Project --> Notes["Task notes<br/>tasks/notes/task-slug.notes.md"]
+
+  Contract --> WorktreePolicy{"Contract worktree required?"}
+  WorktreePolicy -->|yes| Checkout["Checkout isolated worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
+  WorktreePolicy -->|no| CurrentTree["Use current worktree<br/>small or explicitly allowed slice"]
+  Checkout --> Implement
+  CurrentTree --> Implement
+
+  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
+  PreHooks -->|blocked| ScopeFix["Fix plan, contract, worktree, or scope"]
+  ScopeFix --> Implement
+  PreHooks -->|allowed| Changes["Code, docs, tests, or config changes"]
+  Changes --> PostHooks["Post-edit and post-bash hooks<br/>trace, drift request, handoff, check evidence"]
+  PostHooks --> Verify["Run verification<br/>tests plus repo workflow checks"]
+
+  Verify --> Checks["Structured evidence<br/>.ai/harness/checks/latest.json<br/>.ai/harness/runs/*.json"]
+  Checks --> CheckReview["Evaluator review<br/>Waza /check -> review file"]
+  CheckReview --> External["External acceptance advice<br/>or explicit manual override"]
+  External --> DoneGate{"Contract, checks, review, and acceptance pass?"}
+  DoneGate -->|no| Repair["Repair failing evidence or implementation"]
+  Repair --> Implement
+  DoneGate -->|yes| Closeout["Closeout<br/>scripts/contract-worktree.sh finish"]
+
+  Closeout --> Commit["Commit contract branch"]
+  Commit --> Merge["Fast-forward target branch"]
+  Merge --> Archive["Archive plan/todo and refresh handoff"]
+  Archive --> Cleanup["Cleanup merged worktree<br/>contract-worktree.sh cleanup"]
+  Cleanup --> Done["Reviewable completed task"]
+```
+
 ## First 5 Minutes
 
 This is the fastest path for an AI tooling owner evaluating whether the workflow is
@@ -22,26 +110,29 @@ safe to adopt in a real repo.
 npx -y repo-harness init
 ```
 
-The npm package name and primary installed command are `repo-harness`.
-`agentic-dev` remains a compatibility command alias. When working from a source
-checkout instead of npm, run:
+The npm package release line is `0.1.x`; generated workflow compatibility is
+tracked separately as the `5.x` model line. The `0.1.2` package publishes the
+renamed `repo-harness` CLI, user-level Claude/Codex hook adapter bootstrap,
+Waza runtime skill sync, `diagram-design` sync, and the release gate used by
+maintainers before npm publish. When working from a source checkout instead of
+npm, run:
 
 ```bash
-git clone https://github.com/Ancienttwo/agentic-dev.git ~/Projects/agentic-dev
-cd ~/Projects/agentic-dev
+git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
+cd ~/Projects/repo-harness
 bun src/cli/index.ts init
 ```
 
 Local path model:
 
-- Source repo: `~/Projects/agentic-dev`
-- Claude skill aliases: `~/.claude/skills/agentic-dev`, `~/.claude/skills/agentic-dev-skill`
-- Codex discoverable skill alias: `~/.codex/skills/agentic-dev`
-- Codex compatibility fallback alias: `~/.codex/skills/agentic-dev-skill`
+- Source repo: `~/Projects/repo-harness`
+- Claude skill aliases: `~/.claude/skills/repo-harness`, `~/.claude/skills/repo-harness-skill`
+- Codex discoverable skill alias: `~/.codex/skills/repo-harness`
+- Codex compatibility fallback alias: `~/.codex/skills/repo-harness-skill`
 
-The `~/Projects/agentic-dev` repo is the only editable source of truth. Local
+The `~/Projects/repo-harness` repo is the only editable source of truth. Local
 Claude/Codex paths are symlink-backed runtime entrypoints. Only
-`~/.codex/skills/agentic-dev` should expose `SKILL.md` and
+`~/.codex/skills/repo-harness` should expose `SKILL.md` and
 `assets/skill-commands/`; compatibility directories exist only so renamed
 repos can still resolve upstream assets without duplicate command discovery.
 The retired `project-initializer` directories under `~/.codex/skills` and
@@ -68,8 +159,8 @@ Apply only after the dry-run report looks correct:
 npx -y repo-harness init
 ```
 
-For a new project or module, use the `agentic-dev-scaffold` command skill. For
-an existing repo, use `agentic-dev-init`; it installs or refreshes the harness
+For a new project or module, use the `repo-harness-scaffold` command skill. For
+an existing repo, use `repo-harness-init`; it installs or refreshes the harness
 without creating an application stack.
 
 ### Success looks like this
@@ -77,9 +168,8 @@ without creating an application stack.
 The command should end with `=== Migration Report ===` and summarize:
 
 - `Project hooks synced from:` to show where generated hook behavior comes from
-- `Claude hook config target: .claude/settings.json` to show the Claude adapter entry
-- `Codex hook config target: .codex/hooks.json` to show the Codex adapter entry
-- `Codex hook trust required:` to remind the user to trust the repo hook in Codex Settings
+- `Host hook config target: user-level ~/.claude/settings.json and ~/.codex/hooks.json` to show the adapter layer
+- `Host hook adapters are user-level:` to remind the user to install global adapters and trust `~/.codex/hooks.json`
 - `Workflow migration:` to show the repo-local harness surfaces it will create or refresh
 - `Helper scripts:` to show the operational toolchain you get after apply
 - `--- External Tooling ---` to show default gstack/Waza/gbrain routing plus advisory install/update hints
@@ -98,10 +188,11 @@ before applying anything.
 ## Hook Authority Map
 
 - `.ai/hooks/` is the only shared hook implementation you should edit first.
-- `.claude/settings.json` is the Claude adapter that dispatches into `.ai/hooks/run-hook.sh`.
-- `.codex/hooks.json` is the Codex adapter that dispatches into the same runner.
-- Codex must mark this repo hook as trusted in Codex Settings before those hooks run.
-- Debug in this order: adapter config -> `run-hook.sh` -> `.ai/hooks/*`.
+- `~/.claude/settings.json` is the user-level Claude adapter that dispatches into opted-in repos.
+- `~/.codex/hooks.json` is the user-level Codex adapter that dispatches into the same runner.
+- Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are legacy project-level config and should be retired during migration.
+- Codex must mark `~/.codex/hooks.json` as trusted in Codex Settings before those hooks run.
+- Debug in this order: user-level adapter config -> `repo-harness-hook` (or fallback `repo-harness hook`) -> route registry -> `.ai/hooks/*`.
 
 ## Hook Failure Playbook
 
@@ -123,13 +214,19 @@ Most common guards:
 
 - Root routing docs: `CLAUDE.md`, `AGENTS.md`
 - Shared hook layer: `.ai/hooks/`
-- Claude adapter layer: `.claude/settings.json`
-- Codex adapter layer: `.codex/hooks.json`
+- User-level adapter layer: `~/.claude/settings.json`, `~/.codex/hooks.json`
 - Active execution surface: `tasks/`
 - Plan source of truth: `plans/`
 - Durable progress: `tasks/workstreams/`
 - Release history: `docs/CHANGELOG.md`
 
+## Current Release
+
+- npm package: `repo-harness@0.1.2`
+- Generated workflow compatibility: `5.2.3`
+- GitHub repository: `Ancienttwo/repo-harness`
+- Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
+
 ## Current Model (5.2.3)
 
 - Question flow uses **12 grouped decision points** with harness defaults inferred first.
@@ -156,9 +253,9 @@ Most common guards:
   - `complex -> gstack`
   - `simple -> Waza` with Codex-first runtime copies in `~/.codex/skills`
   - `knowledge -> gbrain`
-- `agentic-dev init` bootstraps the Codex/Claude runtime pieces needed for the
+- `repo-harness init` bootstraps the Codex/Claude runtime pieces needed for the
   default workflow:
-  - refreshes `agentic-dev` skill aliases
+  - refreshes `repo-harness` skill aliases
   - installs global Codex/Claude hook adapters
   - installs Waza skills (`check`, `design`, `health`, `hunt`, `learn`, `read`, `think`, `write`) through the skills CLI
   - syncs `diagram-design` into Codex/Claude skill roots when a source copy exists
@@ -179,27 +276,27 @@ Source-owned command skill facades live in `assets/skill-commands/`. They keep
 the public surface action-style while sharing the same router, contract, scripts,
 and tests:
 
-- Planning and review: `agentic-dev-plan`, `agentic-dev-review`, `agentic-dev-autoplan`
-- Repo workflow actions: `agentic-dev-init`, `agentic-dev-migrate`, `agentic-dev-upgrade`, `agentic-dev-capability`, `agentic-dev-architecture`, `agentic-dev-handoff`, `agentic-dev-deploy`, `agentic-dev-repair`, `agentic-dev-check`
-- Project creation: `agentic-dev-scaffold`
+- Planning and review: `repo-harness-plan`, `repo-harness-review`, `repo-harness-autoplan`
+- Repo workflow actions: `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
+- Project creation: `repo-harness-scaffold`
 
-`agentic-dev-init` is for an existing repo; `agentic-dev-scaffold` creates a new
+`repo-harness-init` is for an existing repo; `repo-harness-scaffold` creates a new
 project or module scaffold. `hooks-init`, `docs-init`, and `create-project-dirs`
 are internal steps, not public commands.
 
-Use `agentic-dev-capability` when the harness already exists and only selected
+Use `repo-harness-capability` when the harness already exists and only selected
 capability boundaries should be added. It updates `.ai/context/capabilities.json`,
 syncs the requested local `AGENTS.md` / `CLAUDE.md` contract files, and validates
 the registry without running a full init, migrate, or upgrade pass.
 
-Use `agentic-dev-architecture`, `agentic-dev-handoff`, and `agentic-dev-deploy`
+Use `repo-harness-architecture`, `repo-harness-handoff`, and `repo-harness-deploy`
 for focused architecture documentation, rollover, and deploy/ops readiness
 passes. These commands call existing repo-local helpers and keep their scope
 narrow instead of refreshing the full harness.
 
-Codex installed-copy rule: only `~/.codex/skills/agentic-dev` exposes the root
-skill and `agentic-dev-*` command facades. The compatibility directory
-`~/.codex/skills/agentic-dev-skill` is a runtime fallback bundle only; it must
+Codex installed-copy rule: only `~/.codex/skills/repo-harness` exposes the root
+skill and `repo-harness-*` command facades. The compatibility directory
+`~/.codex/skills/repo-harness-skill` is a runtime fallback bundle only; it must
 not contain `SKILL.md` files or `assets/skill-commands/`. The retired
 `~/.codex/skills/project-initializer` and `~/.claude/skills/project-initializer`
 directories are removed during sync.