@deftai/directive-content 0.92.0 → 0.94.0

package/.agents/skills/deft-directive-xbrief/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: deft-directive-xbrief
+description: >-
+  Create and verify dense xBRIEF artifacts (json|md|both) at an explicit --out
+  path. On-demand pack templates for scope/playbook/mission/project styles.
+  Use when compressing SoT into xBRIEF or running xbrief:create /
+  xbrief:verify. Do NOT trigger on scope lifecycle
+  (promote/activate/complete).
+---
+
+Read and follow: skills/deft-directive-xbrief/SKILL.md

package/Taskfile.yml

@@ -84,12 +84,16 @@ includes:
   deployments:
     taskfile: ./tasks/deployments.yml
     optional: true
+  # check-graph namespaces (#3070): must NOT be optional. CONSUMER_CHECK_GATES /
+  # check:consumer depend on these includes; optional silent omit yields opaque
+  # go-task "Task does not exist" (exit 200/201). Fail loud when the file is
+  # missing so operators get a clear deposit-repair signal (`deft update`).
   toolchain:
     taskfile: ./tasks/toolchain.yml
-    optional: true
+    optional: false
   verify:
     taskfile: ./tasks/verify.yml
-    optional: true
+    optional: false
   coverage:
     taskfile: ./tasks/coverage.yml
     optional: true
@@ -134,9 +138,10 @@ includes:
   migrate:
     taskfile: ./tasks/migrate.yml
     optional: true
+  # check-graph namespace (#3070): vbrief:validate is on CONSUMER_CHECK_GATES.
   vbrief:
     taskfile: ./tasks/vbrief.yml
-    optional: true
+    optional: false
   xbrief:
     taskfile: ./tasks/xbrief.yml
     optional: true

package/UPGRADING.md

@@ -8,6 +8,20 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 <!-- xbrief-backcompat-2111 -->
 
+## Multi-host native slash commands (#55 / #3054 / #3055)
+
+- **Applies when:** you upgrade to a release that ships multi-host slash deposit (#3052–#3054) and want host autocomplete for `/deft…` on Claude / Cursor / Grok / Codex in a shared repo.
+- **Safe to auto-run:** Yes for `directive update` / `directive init` deposit. Policy edits to `plan.policy.hostSlashCommands` are optional.
+- **Restart required:** Start a **new agent session** (and re-open the host) after deposit so command pickers reload project files.
+- **Commands:**
+  - `directive update` (or `directive init` on first adopt)
+  - `deft policy:show --field=hostSlashCommands`
+  - Dogfood and git prefer-commit guidance: [docs/slash-multi-host.md](./docs/slash-multi-host.md)
+  - Prose namespaces remain in [commands.md](./commands.md) § Slash Command Namespaces
+- **Notes:** Default enables every host with a real emitter (not single-host-only). Prefer committing managed product command/prompt paths. Skill discovery (#75) is a separate residual.
+
+---
+
 ### xBRIEF rename (#2034 / #2110 / #2907)
 
 > **Single authoritative rename/history note.** Public product voice uses **xBRIEF** / `xbrief/` only. **vBRIEF** is **legacy**.

package/ci-cd/README.md

@@ -0,0 +1,57 @@
+# CI/CD Layer
+
+Provider-specific guidance for continuous integration runners and CI migration
+(Blacksmith, and later GitHub-hosted, Buildjet, Depot, self-hosted, and similar).
+
+## Purpose
+
+- ! Provide **optional** CI/CD modules that a project can apply when it migrates runners
+- ~ Keep runner and pipeline guidance separate from core Deft rules and from `deployments/`
+- ~ Enable drop-in agent prompts so a migration is repeatable across repos
+- ⊗ Expand always-on `AGENTS.md` with full CI provider bulk — load this layer only when you migrate CI
+
+## Relation to deployments
+
+| Layer | Focus |
+|-------|--------|
+| [`deployments/`](../deployments/README.md) | Where and how you **deploy** runtime apps (cloud platforms, CD paths) |
+| **`ci-cd/`** (this layer) | How you **run CI jobs** (runner labels, sizing, workflow migration) |
+
+Deploy docs may mention GitHub Actions for ship steps. They do not replace runner-tier guidance here.
+
+## Module Structure
+
+Create a directory per CI provider:
+
+```
+ci-cd/
+  README.md                     # purpose + module structure (this file)
+  <provider>/
+    README.md
+    overview.md
+    runner-tiers.md             # when present: sizing decision rules
+    migration-prompt.md         # when present: agent drop-in prompt
+    examples/                   # before/after workflow snippets
+```
+
+Guidelines:
+
+- ! Use hyphens in filenames
+- ! Keep modules optional and isolated
+- ~ Include a clear README with attribution when derived from a reference repo
+- ~ Prefer short decision tables over long narrative for tier selection
+- ⊗ Make any single provider the default for the Directive framework repo itself
+  unless a separate product decision ships that change
+
+## Current modules
+
+| Module | Load when |
+|--------|-----------|
+| [blacksmith/](./blacksmith/README.md) | Migrating GitHub Actions jobs to [Blacksmith](https://blacksmith.sh) runners with tiered vCPU sizing |
+
+## Lazy loading
+
+1. Scan this README for the right provider.
+2. Open that provider's `README.md`, then `overview.md` / `runner-tiers.md` as needed.
+3. Paste or adapt `migration-prompt.md` into the agent session that edits `.github/workflows/`.
+4. Do not pin full provider text into always-on agent context.

package/ci-cd/blacksmith/README.md

@@ -0,0 +1,32 @@
+# Blacksmith CI Module
+
+Optional Deft guidance for migrating GitHub Actions workflows to
+[Blacksmith](https://blacksmith.sh) runners using **tiered vCPU sizing**.
+
+## Status
+
+- ! Optional module — not required for Directive install or `task check`
+- ! Lazy-load only when a repo migrates (or plans to migrate) to Blacksmith
+- ⊗ Treat Blacksmith as the default Directive framework CI runner from these docs alone
+
+## Files
+
+| File | Role |
+|------|------|
+| [overview.md](./overview.md) | What Blacksmith is, drop-in `runs-on` swap, scope and non-goals |
+| [runner-tiers.md](./runner-tiers.md) | Decision rules for 4 / 8 / 32 vCPU tags |
+| [migration-prompt.md](./migration-prompt.md) | Drop-in agent prompt for workflow migration |
+| [examples/lint-vs-test-split.md](./examples/lint-vs-test-split.md) | Before/after: split monolithic lint+test onto small vs large runners |
+
+## Quick start
+
+1. Install the Blacksmith GitHub App on every repo that will use `runs-on: blacksmith-*`.
+2. Read [runner-tiers.md](./runner-tiers.md) and map each job to a tier.
+3. Run [migration-prompt.md](./migration-prompt.md) (or apply the rules by hand).
+4. Prefer splitting `test-and-lint` jobs into small lint and large test jobs.
+
+## Attribution
+
+Tier practice and the migration prompt shape come from `deftai/evolution`
+Blacksmith usage (Slack capture for issue [#448](https://github.com/deftai/directive/issues/448)).
+Runner tag names follow [Blacksmith runner docs](https://docs.blacksmith.sh/blacksmith-runners/overview).

package/ci-cd/blacksmith/examples/lint-vs-test-split.md

@@ -0,0 +1,98 @@
+# Example: split lint vs test (before / after)
+
+Monolithic `test-and-lint` jobs force a large machine for single-threaded lint,
+or starve tests on a small machine. Split them.
+
+## Before (GitHub-hosted, combined)
+
+```yaml
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  test-and-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec biome check .
+      - run: pnpm exec tsc -b --pretty false
+      - run: pnpm exec vitest run --coverage
+```
+
+Problems:
+
+- Lint and typecheck barely use 32 cores
+- Tests with coverage want many cores
+- One failure mode mixes style and correctness
+
+## After (Blacksmith tiers + split)
+
+```yaml
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  lint:
+    # Formatters, linters, typecheckers only — small tier.
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec biome check .
+      - run: pnpm exec tsc -b --pretty false
+
+  test:
+    # Full unit suite with coverage — large tier.
+    runs-on: blacksmith-32vcpu-ubuntu-2404
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec vitest run --coverage
+```
+
+## Medium tier snippet (scanner)
+
+```yaml
+  semgrep:
+    # Container scanner with real CPU work — medium tier.
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    container:
+      image: semgrep/semgrep:latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: semgrep scan --config=auto
+```
+
+## Mapping checklist
+
+| Job kind | Tier | Tag |
+|----------|------|-----|
+| biome / eslint / ruff / tsc only | Small | `blacksmith-4vcpu-ubuntu-2404` |
+| matrix emit / label / dispatch | Small | `blacksmith-4vcpu-ubuntu-2404` |
+| gosec / trivy fs / npm audit | Small | `blacksmith-4vcpu-ubuntu-2404` |
+| semgrep / heavy image scan | Medium | `blacksmith-8vcpu-ubuntu-2404` |
+| vitest/jest/go test + coverage | Large | `blacksmith-32vcpu-ubuntu-2404` |
+| full `task check` | Large | `blacksmith-32vcpu-ubuntu-2404` |
+
+Full rules: [../runner-tiers.md](../runner-tiers.md).

package/ci-cd/blacksmith/migration-prompt.md

@@ -0,0 +1,80 @@
+# Blacksmith migration prompt (agent drop-in)
+
+Copy the prompt below into an agent session that may edit `.github/workflows/`.
+Point the agent at this file (or paste the body). Pair with
+[runner-tiers.md](./runner-tiers.md).
+
+---
+
+## Prompt
+
+```text
+Migrate this repository's GitHub Actions workflows to Blacksmith runners using
+tiered vCPU sizing. Follow these rules exactly.
+
+## Goal
+Replace GitHub-hosted Ubuntu runners with Blacksmith tags so heavy parallel jobs
+get large machines and single-threaded / coordination jobs stay small.
+
+## Runner tags (Ubuntu x64)
+- blacksmith-4vcpu-ubuntu-2404  — SMALL (default)
+- blacksmith-8vcpu-ubuntu-2404  — MEDIUM
+- blacksmith-32vcpu-ubuntu-2404 — LARGE
+
+## Decision rules
+
+### LARGE (32 vCPU) if the job does any of:
+- Test suite with coverage across many files/packages
+- go test ./..., jest, vitest, pytest -n auto, cargo test (or equivalent)
+- Multi-package monorepo builds (turbo run build, nx run-many, etc.)
+- LLM/agent actions that spawn heavy subprocesses
+- Full task check / make ci chaining many of the above
+
+### MEDIUM (8 vCPU) if the job:
+- Runs inside a container: for a security/analysis scanner doing real CPU work
+  (semgrep, codeql-community, trivy image scans, sonar-scanner)
+- Does moderate parallel compression/packaging but is not a full test matrix
+
+### SMALL (4 vCPU) if the job:
+- Only runs formatters / linters / typecheckers
+- Is a coordination job (mostly gh calls, $GITHUB_OUTPUT, matrix JSON, labels,
+  dispatching workflows)
+- Runs a fast single-binary scanner (gosec, trivy fs, npm audit)
+- Uploads artifacts, publishes releases, or does IO-bound deploy steps
+
+If a job is one monolithic test-and-lint step, SPLIT it into a small-tier lint
+job and a large-tier test job.
+
+## Migration steps
+1. Find every workflow under .github/workflows/.
+2. Replace ubuntu-latest / ubuntu-22.04 / ubuntu-24.04 with the appropriate
+   blacksmith-{N}vcpu-ubuntu-2404 tier per the rules above.
+3. Leave macos-*, windows-*, and self-hosted / custom-labeled runners alone.
+4. Add a one-line comment above each runs-on: explaining why that tier was
+   chosen. Example:
+
+   # Coordination-only: emits a JSON task list. Keep on the small runner.
+   runs-on: blacksmith-4vcpu-ubuntu-2404
+
+5. Do not change job logic except for lint/test splits required by the rules.
+6. Summarize: list each job, old runs-on, new runs-on, and the tier reason.
+
+## Non-goals
+- Do not make Blacksmith the org-wide default outside this repo's workflows.
+- Do not invent multi-provider CI abstractions.
+- Do not rewrite deploy platform docs; only workflows and related CI config.
+```
+
+---
+
+## After the agent finishes
+
+- Confirm the Blacksmith GitHub App is installed on this repository
+- Open a PR that only touches workflow sizing (plus any intentional lint/test splits)
+- Watch a green run on the new tags before relying on the migration
+
+## See also
+
+- [overview.md](./overview.md)
+- [runner-tiers.md](./runner-tiers.md)
+- [examples/lint-vs-test-split.md](./examples/lint-vs-test-split.md)

package/ci-cd/blacksmith/overview.md

@@ -0,0 +1,58 @@
+# Blacksmith overview
+
+[Blacksmith](https://blacksmith.sh) provides drop-in GitHub Actions runners.
+You keep workflow YAML; you change `runs-on` labels (and often split heavy jobs).
+
+## Why use this module
+
+GitHub-hosted `ubuntu-latest` is one size for every job. Blacksmith exposes
+explicit vCPU tags so you can:
+
+- Give full test/coverage and monorepo builds a **large** runner
+- Keep format, lint, typecheck, and coordination jobs on a **small** runner
+- Put CPU-heavy container scanners on a **medium** runner
+
+That split cuts wall-clock time on the critical path and avoids overpaying for
+idle cores on single-threaded work.
+
+## Drop-in shape
+
+Minimal change (labels only):
+
+```yaml
+jobs:
+  build:
+    # Full monorepo test suite with coverage — large tier.
+    runs-on: blacksmith-32vcpu-ubuntu-2404
+```
+
+Common Ubuntu x64 tags used in this guide:
+
+| Tag | Tier in this guide |
+|-----|--------------------|
+| `blacksmith-4vcpu-ubuntu-2404` | Small (default) |
+| `blacksmith-8vcpu-ubuntu-2404` | Medium |
+| `blacksmith-32vcpu-ubuntu-2404` | Large |
+
+Blacksmith also publishes other sizes (for example 2 vCPU). This module standardizes
+on **4 / 8 / 32** as the Deft consumer decision set. See
+[runner-tiers.md](./runner-tiers.md).
+
+## Prerequisites
+
+- Blacksmith GitHub App installed on **each** repository that uses `runs-on: blacksmith-*`
+- Jobs that must stay on macOS, Windows, or custom self-hosted labels stay on those runners
+
+## Non-goals (this module)
+
+- ⊗ Changing the Directive monorepo's own workflows as a prerequisite for shipping these docs
+- ⊗ Declaring Blacksmith the default CI for every Deft consumer
+- ⊗ A multi-provider CI product surface before provider guides land under `ci-cd/`
+
+## Related
+
+- [runner-tiers.md](./runner-tiers.md) — when to pick 4, 8, or 32 vCPU
+- [migration-prompt.md](./migration-prompt.md) — agent-ready migration steps
+- [examples/lint-vs-test-split.md](./examples/lint-vs-test-split.md) — split lint vs test
+- Parent layer: [ci-cd/README.md](../README.md)
+- Deploy platforms (different concern): [deployments/README.md](../../deployments/README.md)

package/ci-cd/blacksmith/runner-tiers.md

@@ -0,0 +1,80 @@
+# Blacksmith runner tiers (4 / 8 / 32 vCPU)
+
+Opinionated sizing for GitHub Actions jobs on Blacksmith Ubuntu x64 runners.
+Use one tag per job. Put a one-line comment above each `runs-on:` that states why.
+
+## Tier table
+
+| Tier | `runs-on` | Use for |
+|------|-----------|---------|
+| **Large (32 vCPU)** | `blacksmith-32vcpu-ubuntu-2404` | Full test/coverage, monorepo builds, full `task check`, heavy agent jobs |
+| **Medium (8 vCPU)** | `blacksmith-8vcpu-ubuntu-2404` | Container scanners with real CPU (semgrep and similar) |
+| **Small (4 vCPU)** | `blacksmith-4vcpu-ubuntu-2404` | Lint/format/typecheck, coordination, fast single-binary scanners, IO-bound work |
+
+Default when unsure: **4 vCPU**. Move up only when the job spends real CPU on parallel work.
+
+## 32 vCPU — large
+
+Choose large if the job does any of:
+
+- Test suite with coverage across many files or packages
+- Language suite runners such as `go test ./...`, `jest`, `vitest`, `pytest -n auto`, `cargo test`
+- Multi-package monorepo builds (`turbo run build`, `nx run-many`, and similar)
+- LLM/agent actions that spawn heavy subprocesses (for example Oz, Claude Code in CI)
+- Full `task check` / `make ci` that chains many of the above
+
+```yaml
+# Full test suite with coverage across packages — large tier.
+runs-on: blacksmith-32vcpu-ubuntu-2404
+```
+
+## 8 vCPU — medium
+
+Choose medium if the job:
+
+- Runs inside a `container:` for a security or analysis scanner that does real CPU work
+  (semgrep, CodeQL community runners, Trivy **image** scans, sonar-scanner)
+- Does moderate parallel compression or packaging but is not a full test matrix
+
+```yaml
+# Semgrep in container with real CPU scan work — medium tier.
+runs-on: blacksmith-8vcpu-ubuntu-2404
+```
+
+## 4 vCPU — small (default)
+
+Choose small if the job:
+
+- Only runs formatters, linters, or typecheckers
+- Is a coordination job (mostly `gh` calls, `$GITHUB_OUTPUT`, matrix JSON, labels, dispatch)
+- Runs a fast single-binary scanner (gosec, Trivy **fs**, npm audit)
+- Uploads artifacts, publishes releases, or runs IO-bound deploy steps
+
+```yaml
+# Coordination-only: emits a JSON task list. Keep on the small runner.
+runs-on: blacksmith-4vcpu-ubuntu-2404
+```
+
+## Split monolithic lint + test
+
+If a job today is one `test-and-lint` (or similar) step:
+
+1. ! Split into a **small-tier** `*-lint` job and a **large-tier** `*-test` job
+2. ! Share checkout/setup steps only as needed; prefer independent jobs so lint
+   fails fast on a cheap runner
+3. ~ Wire `needs:` only when order truly matters
+
+See [examples/lint-vs-test-split.md](./examples/lint-vs-test-split.md).
+
+## Leave alone
+
+Do **not** rewrite these `runs-on` values to Blacksmith Ubuntu tags:
+
+- `macos-*`
+- `windows-*`
+- Self-hosted or custom-labeled runners the repo already owns
+
+## Comment style
+
+! Add a one-line comment above each Blacksmith `runs-on:` that states the tier reason.
+Mirror the style in the examples and migration prompt.

package/coding/coding.md

@@ -21,6 +21,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 **Documentation:**
 - ! All *.md in `docs/` directory (except README.md, AGENTS.md, WARP.md)
 - ! Prior tasks/plans in `history/`
+- ! When code changes user-visible behavior, update matching user-facing docs in the same PR — see [docs.md](docs.md) (#447; lazy-load, not AGENTS always-on)
 
 **Filenames:**
 - ~ Use hyphens not underscores (unless language idiom)
@@ -107,6 +108,11 @@ See [../scm/git.md](../scm/git.md) for:
 - ! Apply baseline security standards to every project from day one
 - See [../coding/security.md](../coding/security.md) for input validation, authn/authz, secrets, dependency, TOCTOU / mutable-external-resource rules (#1938), and agent-specific threats (#661)
 
+**Review process (#1471 / #212):**
+- ! Apply tool-agnostic review-cycle principles on every PR review response
+- See [review.md](review.md) for read-all-findings, severity P0/P1/P2, single batch commit, cross-file grep, no mid-review push, exit on no P0/P1, and post-merge closing-keyword verification
+- Greptile/GitHub adapter: [../skills/deft-directive-review-cycle/SKILL.md](../skills/deft-directive-review-cycle/SKILL.md)
+
 **Codebase Hygiene:**
 - See [hygiene.md](hygiene.md) for: dead code removal, circular dependency detection, error hiding patterns, legacy/deprecated code cleanup
 
@@ -138,7 +144,7 @@ This rule is the OPERATIONAL complement to the EPISTEMIC honesty rules elsewhere
 
 The rule applies to agent completion claims during task execution. It applies equally to claims to the user, claims in commit messages, claims in PR bodies, claims in CHANGELOG entries, and claims in status messages to a parent agent. A short, honest "the migration completed; I did not verify the per-record count" is strictly preferred over a confident "migration completed successfully" that hides the gap.
 
-**Cross-references:** strategies discuss/probe Graduation dual-path locks (#2899); `## Quality Standards` above (`⊗ Claim checks passed without running them` -- the sibling rule that this expands from process to outcome); `hygiene.md` `## Error Handling: No Hiding` (the same hiding pattern at the code-write level, not the claim level); `skills/deft-directive-pre-pr/SKILL.md` (pre-PR verification claims); `skills/deft-directive-build/SKILL.md` Step 4 Quality Gates (task-completion claims); `skills/deft-directive-review-cycle/SKILL.md` (the review-cycle skill explicitly checks for hidden incompleteness in fix-batch completion claims).
+**Cross-references:** strategies discuss/probe Graduation dual-path locks (#2899); `## Quality Standards` above (`⊗ Claim checks passed without running them` -- the sibling rule that this expands from process to outcome); `hygiene.md` `## Error Handling: No Hiding` (the same hiding pattern at the code-write level, not the claim level); `skills/deft-directive-pre-pr/SKILL.md` (pre-PR verification claims); `skills/deft-directive-build/SKILL.md` Step 4 Quality Gates (task-completion claims); `skills/deft-directive-review-cycle/SKILL.md` (Greptile adapter; universal review principles in [review.md](review.md); the adapter explicitly checks for hidden incompleteness in fix-batch completion claims).
 
 ## Calling LLM APIs (#481)
 

package/coding/docs.md

@@ -0,0 +1,44 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Documentation with Code Changes (#447)
+
+Keep user-facing documentation current when code changes. Full rules live here so they are **not** always-loaded into AGENTS.md (consumer token cost).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also** (load only when needed):
+- [coding.md](coding.md) — general coding standards
+- [../skills/deft-directive-pre-pr/SKILL.md](../skills/deft-directive-pre-pr/SKILL.md) — pre-PR checklist (operational)
+- [../docs/good-agents-md.md](../docs/good-agents-md.md) — AGENTS.md structure
+
+## When docs are required
+
+- ! If the change alters **user-visible behavior**, update the matching user-facing surface in the **same PR** (or same commit batch before PR)
+- ! User-facing surfaces include, as applicable:
+  - CHANGELOG.md under `[Unreleased]` (when the change is user- or operator-visible)
+  - CLI help / `commands.md` (or equivalent) when adding or changing a user-invoked command or flag
+  - Getting-started / README pointers when install or first-run behavior changes
+  - Skill or strategy "When to use" / trigger text when workflow entry points change
+- ~ Prefer updating the **canonical source** (xBRIEF, content pack, policy) and re-rendering generated views — do not hand-edit generated markdown as the sole fix
+- ⊗ Claim "docs updated" or "documented" without the documentation files appearing in the diff
+
+## When docs are optional
+
+- ? Invent documentation for pure internal refactors with no user-visible behavior change
+- ~ Internal-only comments and maintainer notes MAY ship without user-facing doc updates
+- ⊗ Expand always-loaded AGENTS.md with long documentation-discipline essays — keep this file lazy-loaded
+
+## Honesty
+
+- ! Documentation claims obey fail-loud / outcome verification (coding.md § Fail Loud): no completion claims that hide missing doc surfaces
+- ~ If a required surface is skipped, say so explicitly and why (same standard as "checks not run")
+
+## Anti-Patterns
+
+- ⊗ Shipping a new public task/CLI verb with no help or commands entry
+- ⊗ Leaving CHANGELOG stale after a user-visible fix
+- ⊗ Orphan docs (new md not reachable from AGENTS/README/reference chain — see pre-pr #644 / #647)

package/coding/review.md

@@ -0,0 +1,50 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Review Cycle Principles
+
+Tool-agnostic principles for responding to code review findings on a PR. Adapters
+(Greptile, CodeRabbit, Codacy, host babysit loops, …) implement these with
+tool-specific mechanics. This file is the single source of truth for the
+universal process so consumers without a given adapter skill still get the
+review discipline (#1471 / #212).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also:** [coding.md](coding.md) (quality chain) · [testing.md](testing.md) ·
+[skills/deft-directive-review-cycle/SKILL.md](../skills/deft-directive-review-cycle/SKILL.md)
+(Greptile + GitHub adapter)
+
+## Universal Requirements
+
+- ! ALL review findings MUST be read before any fixes begin
+- ! Findings MUST be classified by severity: **P0** (critical/blocking), **P1** (real defect), **P2** (style / non-blocking). P0 and P1 are merge-blocking; P2 is not
+- ! Findings MUST be fixed in a single batch commit — never incrementally per finding
+- ! Changed values, terms, or fields MUST be grepped across all PR files for cross-file consistency in the same batch
+- ~ Structured data files (JSON / YAML / TOML) SHOULD be validated locally before commit (e.g. `python3 -m json.tool`, YAML lint) — do not rely on the reviewer alone to catch syntax errors
+- ! Do not push additional commits while a review is in progress on the current head
+- ! Exit condition: no P0 or P1 remaining = ready to merge; P2 does not block merge
+- ! Post-merge: verify that closing keywords (`Closes #N`, `Fixes #N`) actually closed the referenced issues (squash-merge pitfall; #167)
+
+## Severity and merge gate
+
+| Severity | Meaning | Blocks merge? |
+| --- | --- | --- |
+| P0 | Critical / correctness / security / data-loss | Yes |
+| P1 | Real defect or incomplete acceptance | Yes |
+| P2 | Style, nits, non-blocking suggestion | No |
+
+- ! Agents MUST NOT claim merge-ready while any P0 or P1 from the current review remains open
+- ⊗ Elevate P2-only findings into a merge block without operator agreement
+
+## Anti-Patterns
+
+- ⊗ Start fixing individual findings as you encounter them — read and plan the full batch first
+- ⊗ Push one commit per finding
+- ⊗ Push while a bot or human review of the current head is still in flight
+- ⊗ Treat P2-only findings as merge-blocking by default
+- ⊗ Assume squash merge auto-closed referenced issues — always verify issue state after merge (#167)
+- ⊗ Skip cross-file grep when a fix renames or retargets a shared term/value/field