The-Running-Dev · The-Running-Dev · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026
diff --git a/.claude/COMPANIONS.md b/.claude/COMPANIONS.md
@@ -9,6 +9,13 @@ This file is the mechanism. It is kit-owned and installed into every target, and
 single home for the category vocabulary, the never-list, and the absence rule. A core command
 file names *which categories* apply to it; it does not restate any of what is below.
 
+## The block is a declared region
+
+A core's fenced companion block is a **declared** marked region, id `companion` — `AGENTS.md`
+(*Marked regions*) owns what declared means and what the marker looks like, and neither is
+restated here. In short: hand-authored, never written by a generator, checked for presence and
+well-formedness the same as any other marked region.
+
 ## Why the split exists
 
 `/install`, `INSTALL.md` and `/kit-sync` used to spend real effort reconciling a target's local

diff --git a/.claude/commands/brief-check.md b/.claude/commands/brief-check.md
@@ -2,12 +2,12 @@
 description: Interrogate the concept brief before any design work
 ---
 
-<!-- companion:start -->
+<!-- companion:declared:start -->
 **Per-repo companion:** `.claude/commands/brief-check-local.md`. Read it now, if it exists — an absent,
 empty, or frontmatter-only file is no companion, and this file then stands alone.
 It may override: `vocabulary`, `document-map`. It may never override anything in
 [`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
-<!-- companion:end -->
+<!-- companion:declared:end -->
 
 Read `design/00-brief.md`.
 

diff --git a/.claude/commands/contract.md b/.claude/commands/contract.md
@@ -2,12 +2,12 @@
 description: Derive the interface contract from the design doc
 ---
 
-<!-- companion:start -->
+<!-- companion:declared:start -->
 **Per-repo companion:** `.claude/commands/contract-local.md`. Read it now, if it exists — an absent,
 empty, or frontmatter-only file is no companion, and this file then stands alone.
 It may override: `vocabulary`, `document-map`, `extra-steps`. It may never override anything in
 [`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
-<!-- companion:end -->
+<!-- companion:declared:end -->
 
 ## Stop if `design/` is frozen
 
@@ -46,12 +46,16 @@ Rules:
 - If the design doc does not determine a signature, do not invent it. List it under `## Unresolved` and stop.
 - **Do not restate a declaration the tree already carries.** Point at it and state what it cannot say.
 - No implementation. No comments explaining intent — the design doc carries intent. File paths are permitted **only** as the pointers this section requires.
-- Anything you add here that was not implied by the design doc gets a decision-log entry.
+- Anything you add here that was not implied by the design doc gets a decision-log entry. Where this repository's own `design/state/` exists, writing it also follows the record-writing sequence in `design/10-design.md` § *Record* — not restated here.
 
 ## Re-run
 
-Rewrites `design/20-contract.md` in full from the current `design/10-design.md` — there is no
-partial regeneration. A scaffold already replaced by a pointer to a materialised declaration
+`design/20-contract.md` is **repository-scoped**: a landed path's standing contract — the
+invariants and surface for work already shipped — stands as written and is never rewritten
+away because a later run covers a different path. A re-run regenerates the section(s) that
+correspond to the `design/10-design.md` pass that invoked it, and leaves every other landed
+path's content untouched — there is no whole-document rewrite that starts from a blank
+document. A scaffold already replaced by a pointer to a materialised declaration
 (*Semantics, not shape*, above) must stay a pointer; a re-run never turns it back into a
-scaffold. `## Unresolved` only ever shrinks between runs, as signatures get resolved — an
-entry a previous run resolved must never reappear.
+scaffold, landed path or not. `## Unresolved` only ever shrinks between runs, as signatures
+get resolved — an entry a previous run resolved must never reappear.
diff --git a/.claude/commands/design.md b/.claude/commands/design.md
@@ -2,12 +2,12 @@
 description: Produce or revise the design doc from the brief
 ---
 
-<!-- companion:start -->
+<!-- companion:declared:start -->
 **Per-repo companion:** `.claude/commands/design-local.md`. Read it now, if it exists — an absent,
 empty, or frontmatter-only file is no companion, and this file then stands alone.
 It may override: `vocabulary`, `document-map`, `extra-steps`. It may never override anything in
 [`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
-<!-- companion:end -->
+<!-- companion:declared:end -->
 
 ## Stop if `design/` is frozen
 
@@ -42,7 +42,7 @@ Things that cannot be resolved without information I have not given you. Ask the
 
 Rules:
 - No code. No file layouts. No package names beyond what a decision required.
-- Every decision that survives goes into `design/90-decisions.md` in the logged format.
+- Every decision that survives goes into `design/90-decisions.md` in the logged format. Where this repository's own `design/state/` exists, writing it also follows the record-writing sequence in `design/10-design.md` § *Record* — not restated here.
 - If the brief is too thin to design against, stop and say what is missing rather than inventing requirements.
 
 ## Re-run

diff --git a/.claude/commands/done.md b/.claude/commands/done.md
@@ -2,12 +2,12 @@
 description: Switch back to the default branch, delete local branches already merged into it, and prune stale remote-tracking refs
 ---
 
-<!-- companion:start -->
+<!-- companion:declared:start -->
 **Per-repo companion:** `.claude/commands/done-local.md`. Read it now, if it exists — an absent,
 empty, or frontmatter-only file is no companion, and this file then stands alone.
 It may override: `extra-steps`, `tightened-authorization`. It may never override anything in
 [`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
-<!-- companion:end -->
+<!-- companion:declared:end -->
 
 Housekeeping for the end of a piece of work: get back to the default branch, remove the local branches that are done, and drop remote-tracking refs for branches deleted on the remote.
 

diff --git a/.claude/commands/fix.md b/.claude/commands/fix.md
@@ -3,12 +3,12 @@ description: Reproduce and fix a defect that has no slice — from a bug issue n
 argument-hint: [issue number, a description, or leave blank to auto-pick the highest-value open bug]
 ---
 
-<!-- companion:start -->
+<!-- companion:declared:start -->
 **Per-repo companion:** `.claude/commands/fix-local.md`. Read it now, if it exists — an absent,
 empty, or frontmatter-only file is no companion, and this file then stands alone.
 It may override: `vocabulary`, `document-map`, `extra-steps`, `gate-commands`, `tightened-authorization`. It may never override anything in
 [`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
-<!-- companion:end -->
+<!-- companion:declared:end -->
 
 Fix the defect named by **$1** — an issue number, a description, a failing test already in this session's context, or (with no argument and none of those) the highest-value open bug issue, picked automatically. `/slice` needs a slice id and a contract signature; a bug has neither, which is why this command exists as its own front door rather than an extension of `/slice`.
 
@@ -28,6 +28,10 @@ Before filing anything, branching, or editing: **reproduce the defect.** Write o
 
 Filing happens **after** reproducing, never before — filing first would put an unreproduced report into the tracker as a bug.
 
+## Orienting on the code you're fixing
+
+**Where this repository's own `design/state/` exists**, establishing what is currently true about the command or script the defect lives in reads that unit's closure (`design/10-design.md` § *Orient*) rather than the corpus, and `design/90-decisions.md` is not opened to establish it. Reading a closure is not writing to `design/`, so this does not relax the *Never* list below (I6). **Where `design/state/` is absent**, behaviour is today's: read the source directly (I27).
+
 ## Branch
 
 Derive `fix/<issue>-<slug>` from the issue number and title, **after the issue exists** — never before, since the branch name needs a real number.
@@ -38,7 +42,7 @@ Derive `fix/<issue>-<slug>` from the issue number and title, **after the issue e
 
 Implement against the issue's agent block. When it is satisfied:
 
-- **Push, then open the pull request. Never as a draft.** Carved out of the authorization rule the same as pushing the branch (`AGENTS.md`, *Git and delivery*).
+- **Push, then open the pull request. Never as a draft.** Carved out of the authorization rule the same as pushing the branch (`AGENTS.md`, *Git and delivery*). **Write the real description as you open it**, in the shape `.claude/commands/pr.md` § *Phase 1* fixes; a body deferring to a later `/pr` run leaves a reviewer who arrives first with nothing to read. `Verified` is the one section that says the gates have not run yet, and `/pr` replaces it verbatim.
 - **`/pr`** — same session. Writes the real description, runs this repository's gates and writes their three lists into the `Verified` section verbatim, and works the review threads once review lands. Fixing and resolving are delegated there — no ask required.
 
 This command does not carry a second copy of `/pr`'s rules, or of the gate and thread procedures it delegates to — it references them by name and hands off.

diff --git a/.claude/commands/freeze.md b/.claude/commands/freeze.md
@@ -2,12 +2,12 @@
 description: Create design/FROZEN.md so design/ stops drifting while implementation is the bottleneck
 ---
 
-<!-- companion:start -->
+<!-- companion:declared:start -->
 **Per-repo companion:** `.claude/commands/freeze-local.md`. Read it now, if it exists — an absent,
 empty, or frontmatter-only file is no companion, and this file then stands alone.
 It may override: `vocabulary`, `document-map`. It may never override anything in
 [`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
-<!-- companion:end -->
+<!-- companion:declared:end -->
 
 Write `design/FROZEN.md`. Its existence is the whole mechanism — the rule, what it gates, and the marker's format are owned by `AGENTS.md`, *The design freeze*; this command only produces the file correctly and does not restate the rule.
 

diff --git a/.claude/commands/install-all.md b/.claude/commands/install-all.md
@@ -3,12 +3,12 @@ description: Reconcile the kit into every SubZeroDev.* repository, unattended. U
 argument-hint: [repo name[,repo name...]]
 ---
 
-<!-- companion:start -->
+<!-- companion:declared:start -->
 **Per-repo companion:** `.claude/commands/install-all-local.md`. Read it now, if it exists — an absent,
 empty, or frontmatter-only file is no companion, and this file then stands alone.
 It may override: `extra-steps`, `tightened-authorization`. It may never override anything in
 [`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
-<!-- companion:end -->
+<!-- companion:declared:end -->
 
 Run `INSTALL.md`'s reconciliation against every sibling repository, in one unattended pass. **$1**, if given, is an explicit ordered list of repo names (comma-separated) — only those run, in that order. Bare, it discovers every `SubZeroDev.*` sibling of this kit and runs them alphabetically.
 
@@ -17,12 +17,19 @@ This command does not replace `/install`; it orchestrates it. Discovery, orderin
 ## Phase 0 — Discover
 
 ```powershell
-Get-ChildItem (Split-Path <kit-root> -Parent) -Directory -Filter 'SubZeroDev.*'
+$kitRoot = git rev-parse --show-toplevel
+Get-ChildItem (Split-Path $kitRoot -Parent) -Directory -Filter 'SubZeroDev.*'
 ```
 
+Run this from the repository that holds the installed kit; `$kitRoot` is that repository's
+resolved Git root.
+
 - Drop the kit itself.
 - **Resolve every candidate's real root** with `git -C <candidate> rev-parse --show-toplevel` before adding it to the list. Two paths resolving to the same root — a junction, a symlink, a Dropbox-synced duplicate — are one repository; keep the first, report the rest as skipped duplicates. A stray `SubZeroDev.Platform;C` sitting next to `SubZeroDev.Platform` is exactly this case: check before assuming two candidates differ.
-- **Not a git repository** — report and skip it. Do not stop the run for one bad candidate.
+- **Not a git repository** — report and skip it. Do not stop the run for one bad candidate, and **do not
+  initialize one here.** `INSTALL.md` phase 4 creates an absent repository under a sign-off this command
+  never collects; unattended, across a directory of candidates, that turns a stray or mistyped sibling into
+  a repository holding a copy of the kit. Attended `/install` is where an absent repository is created.
 - Order: the explicit list in `$1` if given, else alphabetical.
 
 ## Phase 1 — Per target, run `INSTALL.md` phases 0 through 2 unmodified
@@ -61,9 +68,9 @@ This is the mechanical backstop for everything above — the phase-2 rules say w
 
 ## Phase 3 — What must not happen, in any target
 
-Same list as `INSTALL.md`'s, and unattended does not relax it — if anything it matters more, since nothing here waits for a human to notice a mistake before it repeats across the next repository:
+`INSTALL.md`'s list, and unattended does not relax it — if anything it matters more, since nothing here waits for a human to notice a mistake before it repeats across the next repository. **One entry is tightened rather than inherited**, and it is the first:
 
-- No commit, no push, no pull request, in any target.
+- **No commit, no push, no pull request, in any target** — this is stricter than `INSTALL.md` phase 4 step 8, which delivers on a feature branch. Attended, one target, that branch is reviewable before anything else happens to it. Unattended, across every sibling repository, it is a pull request per repo that nobody asked for, opened faster than anyone can read them, on repositories whose forks this pass has already declined to answer. The write surface below is the whole of what an unattended pass leaves behind, and it stops at the working tree.
 - No `git add -A`, `git add .`, or bare-directory add — this command does not stage anything at all.
 - No deletion without approval, including proposed `agent.md` prunes — leave those unpruned and listed, not silently applied.
 - No write to a target's `settings.json`, `settings.local.json`, or `launch.json` beyond the (skipped, per phase 2) `SessionEnd` and `UserPromptSubmit` hooks.

diff --git a/.claude/commands/install-code-review-agent.md b/.claude/commands/install-code-review-agent.md
@@ -0,0 +1,71 @@
+---
+description: Install Anthropic's Claude Code GitHub Action into a repository so pull requests get automated Claude review. Usage - /install-code-review-agent, or /install-code-review-agent D:\Projects\Some.Repo
+argument-hint: [target repo path]
+---
+
+<!-- companion:declared:start -->
+**Per-repo companion:** `.claude/commands/install-code-review-agent-local.md`. Read it now, if it exists — an absent,
+empty, or frontmatter-only file is no companion, and this file then stands alone.
+It may override: `extra-steps`, `tightened-authorization`. It may never override anything in
+[`.claude/COMPANIONS.md`](../COMPANIONS.md) § *Never*, which is also where these categories are defined.
+<!-- companion:declared:end -->
+
+Install Anthropic's official `claude-code-action` into a GitHub repository, so pull requests get an automated Claude review. **$1** is the target repository path; default to the current repository if not given.
+
+This installs three things, and only one of them is this command's to do:
+
+1. **The workflow file** — `.github/workflows/claude-code-review.yml`. This command writes it.
+2. **The GitHub App** (`https://github.com/apps/claude`) — grants Claude's GitHub identity access to the target repository. This is a browser consent flow on the user's GitHub account; it cannot be scripted or driven headlessly, and this command does not attempt it (`AGENTS.md`, top-level: *bypassing or completing CAPTCHAs or other bot-detection* and *granting OAuth/SSO permissions* are never automated).
+3. **The `ANTHROPIC_API_KEY` repository secret** (or `CLAUDE_CODE_OAUTH_TOKEN` for a Claude Pro/Max/Team subscription, via `claude setup-token`) — this command never enters the value itself, under any circumstance, even if it is pasted into chat. Entering an API key into a field is a prohibited action at the top level of this session, and no per-repo authorization changes that.
+
+## Resolve the target
+
+`$1` if given, else the current repository. Confirm it is a GitHub repository (`gh repo view` succeeds) before doing anything else.
+
+## Check prerequisites
+
+```powershell
+gh auth status
+```
+
+Not authenticated, or `gh` missing entirely — stop and report. This command does not attempt to install or authenticate `gh` on the user's behalf.
+
+## Classify the workflow file
+
+```powershell
+Test-Path <target>/.github/workflows/claude-code-review.yml
+```
+
+- **Absent** — proceed to *Choose a mode*.
+- **Present** — read it. If its `uses:` line already pins `anthropics/claude-code-action`, report **Identical** (or note a version difference) and stop; re-running this command is not how an existing installation is upgraded. If it is a different workflow that happens to occupy this filename, this is **Occupied** — stop and ask, the same as `INSTALL.md` phase 1 treats any other occupied artifact. Never overwrite a workflow file this command did not write.
+
+## Choose a mode
+
+Ask which mode, recommending automatic review first:
+
+- **Automatic review (recommended)** — triggers on `pull_request` (`opened`, `synchronize`, `ready_for_review`, `reopened`) and runs `/code-review:code-review --comment` against the PR, posting findings as inline comments. This is what "install the code review agent" means in the common case.
+- **Mention-only** — triggers on `issue_comment` and `pull_request_review_comment` containing `@claude`, and only acts when someone asks.
+
+Both need `contents: write`, `pull-requests: write`, `issues: write`, `id-token: write`, `actions: read` permissions on the job, and an `actions/checkout` step ahead of the `anthropics/claude-code-action@v1` step.
+
+## Write the workflow file
+
+Write `<target>/.github/workflows/claude-code-review.yml` with the chosen trigger and `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}` (or `claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}` if the user said they use a subscription token instead of an API key — ask which, do not guess).
+
+## Report — and stop
+
+- Whether the workflow file was created, and its path
+- Whether the GitHub App is already installed on the target (`gh api /repos/{owner}/{repo}/installation` if reachable; otherwise say it could not be checked) — if not, give the user the install URL and ask them to do it and confirm back
+- Whether `ANTHROPIC_API_KEY` (or `CLAUDE_CODE_OAUTH_TOKEN`) already exists as a repository secret (`gh secret list` — this shows names only, never values, so checking existence is safe) — if not, give the user the exact `gh secret set <NAME>` command to run **themselves**, in their own terminal
+- **Do not commit, push, or open a pull request.** This command stops at the report for sign-off. `/install` and `/kit-sync` no longer do (`INSTALL.md` phase 4 step 8) and this one still does, on its own reason rather than theirs: a workflow file that grants CI a repository secret is not something to land before the user has confirmed the App install and the secret exist.
+
+## Never
+
+- Enter, echo, or infer an API key or OAuth token value, in any field, under any authorization.
+- Attempt to drive the GitHub App installation's browser consent screen.
+- Overwrite a workflow file this command did not write.
+- Commit, push, or open a pull request. That is the user's call once the report is reviewed.
+
+## Re-run
+
+Re-running against a target that already has the workflow file reports **Identical** and stops rather than rewriting it — upgrading the action version or changing the mode is a manual edit to the workflow file, not this command's job.