@deftai/directive-content 0.104.0 → 0.105.0

package/Taskfile.yml

@@ -142,9 +142,12 @@ includes:
   vbrief:
     taskfile: ./tasks/vbrief.yml
     optional: false
+  # Non-optional (#3483): the swarm skill names xbrief:validate / xbrief:activate
+  # / xbrief:preflight at MUST/⊗ level, so a silently-omitted include would
+  # reproduce the opaque exit-200 "task does not exist" failure at cohort close.
   xbrief:
     taskfile: ./tasks/xbrief.yml
-    optional: true
+    optional: false
   prd:
     taskfile: ./tasks/prd.yml
     optional: true
@@ -172,6 +175,9 @@ includes:
   session:
     taskfile: ./tasks/session.yml
     optional: true
+  occupancy:
+    taskfile: ./tasks/occupancy.yml
+    optional: true
   lifecycle:
     taskfile: ./tasks/lifecycle.yml
     optional: true
@@ -1063,10 +1069,10 @@ tasks:
           CLI_ARGS: "{{.CLI_ARGS}}"
 
   # N7 (#1147): slice:record-existing backfill verb. Retrofits a
-  # vbrief/.eval/slices.jsonl entry for hand-filed umbrella cohorts that
-  # D13's writer (#1132) never saw because they were filed via
-  # `gh issue create` / `issue_write` MCP rather than via a slicing
-  # skill. Companion `slice:list` exposes the read surface.
+  # <lifecycle-root>/.triage-cache/slices.jsonl entry for hand-filed
+  # umbrella cohorts that D13's writer (#1132) never saw because they
+  # were filed via `gh issue create` / `issue_write` MCP rather than via
+  # a slicing skill. Companion `slice:list` exposes the read surface.
   slice:record-existing:
     desc: "Retrofit a slices.jsonl entry for a hand-filed cohort (#1147 / N7). -- task slice:record-existing -- --umbrella=N --children=A,B,C [--wave-1=A,B] [--wave-2=C] [--actor=manual:operator] [--expected-close-signal=all-children-merged] [--sliced-at=ISO] [--notes=TEXT] [--dry-run] [--force] [--skip-validation] [--repo OWNER/NAME]"
     cmds:
@@ -1075,7 +1081,7 @@ tasks:
           CLI_ARGS: "{{.CLI_ARGS}}"
 
   slice:list:
-    desc: "List recorded slices in vbrief/.eval/slices.jsonl (#1147 / N7). -- task slice:list [-- --json]"
+    desc: "List recorded slices in <lifecycle-root>/.triage-cache/slices.jsonl (#1147 / N7). -- task slice:list [-- --json]"
     cmds:
       - task: slice-record:list
         vars:

package/UPGRADING.md

@@ -217,6 +217,8 @@ the configured mirror.
 
    **Prettier / format gate (#2534):** managed `.deft/core/` is outside your consumer Prettier gate. `directive init` and `directive update` idempotently deposit or heal a root `.prettierignore` entry for `.deft/core/` so `prettier --check .` (and `task check` when Prettier is wired) does not fail on the vendored framework payload. You do not need to reformat `.deft/core/` after upgrade.
 
+   **Schema rewrite / format before the upgrade PR (#3395):** `deft update` may rewrite consumer-owned `xbrief/schemas/*`. It does **not** run your repo formatter. When the update summary lists rewritten consumer-owned paths, run `task fmt` (or your formatter) **before** opening the upgrade PR so Prettier / `task check` stay green.
+
    > **`deft update` is the single canonical upgrade verb (#2064).** The older `deft install-upgrade` (and its `task upgrade` maintainer alias) now print a one-line notice and delegate to this exact `deft update` path — they no longer have their own semantics. Previously `install-upgrade` only rewrote the marker/manifest without swapping the payload, so on a stale deposit it reported a false "Project already at X. Nothing to do." Use `deft update`; there is nothing `install-upgrade` does that `deft update` does not.
 
 3. **Stamp npm provenance (one-time, idempotent):**
@@ -282,6 +284,8 @@ A normal framework upgrade is **one PR**, not two stacked PRs. The deposited `de
 
 **Do not** split a routine version bump into “deposit-only” then “pin/GENERATION” PRs — that re-creates engine / deposit / pin skew between merges. **Do** keep product feature work on a separate branch/PR from the framework upgrade. Consumers should **not** hand-roll a forked `deft-core-guard.yml` for normal upgrades — the deposited workflow already enforces pin-only + lock follow-through.
 
+**Format before you open the PR (#3395):** if `deft update` listed rewritten consumer-owned `xbrief/schemas/*` paths, run `task fmt` (or your repo formatter) first. Update does not invoke the consumer formatter.
+
 **Load fix (#3345):** if GitHub Actions shows workflow name as the path string `.github/workflows/deft-core-guard.yml` (not `deft-core-guard`), or historical runs are 0s/0 jobs and the required check `no-mixed-core-and-app` never appears on PRs, the deposited workflow failed to load (invalid YAML from an unindented Python heredoc). Run `deft update` (or re-init deposit) so the fixed workflow is rewritten, then open a normal upgrade PR — classic branch protection that requires `no-mixed-core-and-app` can clear once the job posts.
 
 Refs: [#3127](https://github.com/deftai/directive/issues/3127), [#3193](https://github.com/deftai/directive/issues/3193), [#1430](https://github.com/deftai/directive/issues/1430), [#3117](https://github.com/deftai/directive/issues/3117), [#3345](https://github.com/deftai/directive/issues/3345).

package/coding/coding.md

@@ -47,7 +47,7 @@ See [../scm/git.md](../scm/git.md) for:
 
 **Modularity:**
 - ! One responsibility per file/module
-- ~ Files <300 lines ideal; <500 lines recommended; <1000 lines a review trigger — split when exceeded unless genuinely single-responsibility (size is a smell, not a hard cap; #1488)
+- ~ Keep files small. Ideal, recommended, and review-trigger line counts are FILE_SIZE_IDEAL_LINES, FILE_SIZE_RECOMMENDED_LINES, and FILE_SIZE_REVIEW_TRIGGER_LINES in the file-size-thresholds policy module (packages/core/src/policy/file-size-thresholds.ts). Split when a file exceeds the review trigger unless it is genuinely single-responsibility (size is a smell, not a hard cap; #1488 / #3424)
 - ! Explicit scope in task descriptions
 - ~ DRY: extract shared abstractions when logic is duplicated across 2+ call sites
 - ⊗ Copy-paste logic with minor variations — parameterise instead
@@ -234,7 +234,7 @@ See [debugging.md](debugging.md) for the full four-phase process, evidence disci
 
 - ⊗ Secrets in code or version control
 - ⊗ Claiming checks passed without running them
-- ⊗ Single files mixing multiple responsibilities (large line count, e.g. >1000 lines, is a trigger to check cohesion — not a defect by itself; #1488)
+- ⊗ Single files mixing multiple responsibilities (line count at or above FILE_SIZE_REVIEW_TRIGGER_LINES is a cohesion review trigger — not a defect by itself; #1488 / #3424)
 - ⊗ Skipping quality checks
 - ⊗ Breaking changes without explicit approval
 - ⊗ Using `grep` command when `rg` or Warp grep available

package/commands.md

@@ -158,7 +158,7 @@ task verify:story-ready -- --vbrief-path xbrief/active/<file>.xbrief.json
 deft xbrief:preflight -- xbrief/active/<file>.xbrief.json
 ```
 
-Gate 0 `task verify:story-ready` machine-checks working-tree cleanliness (or `--allow-dirty`), the target xBRIEF in `xbrief/active/` with `plan.status == "running"`, and the dispatch envelope's `## Allocation context` consent token (#1378). A `swarm-cohort` section is ready only when `allocation_plan_id` AND `batching_rationale` are non-null. Complete stories with `task scope:complete -- <active-story-path>`.
+Gate 0 `task verify:story-ready` machine-checks working-tree cleanliness (or `--allow-dirty`), the target xBRIEF in `xbrief/active/` with `plan.status == "running"`, and the dispatch envelope's `## Allocation context` consent token (#1378). A `swarm-cohort` section is ready only when `allocation_plan_id` AND `batching_rationale` are non-null. Both `verify:story-ready` and `xbrief:preflight` also fail closed when an applicable `plan.policy.projectInvariants` ID has no `coverage_map` disposition (list as of check time; completeness only). See `content/docs/project-invariants.md`. Complete stories with `task scope:complete -- <active-story-path>`.
 
 **Story Start Gate (#1378):** Before starting any new implementation story or switching stories, run `git status --short --branch`. If the working tree is dirty, stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the next story — ask the operator to choose: commit existing work, stash existing work, include existing work in the current story, or stop. ⊗ Do not begin a new story while unrelated dirty work is present without explicit operator approval. When invoked as part of a swarm cohort dispatch, the approved Phase 5 allocation plan satisfies batching consent (#954); between stories checkpoint-commit it and proceed — do not pause to ask the operator mid-cohort. Promote/activate via `task scope:promote -- <path>` (or `task scope:promote -- --batch` for multi-scope pins, #3011) / `task scope:activate -- <path>`; preflight with `deft xbrief:preflight -- <active-story-path>`.
 
@@ -189,6 +189,24 @@ flowchart TD
 
 ---
 
+## Default-branch sync (`scm:sync-default`, #3391)
+
+Open dest-targeted sync PRs from typed `baseBranch` to `deliveryBranch`. Consumes the shared detector (#3388) and `syncMaxFiles` (#3390).
+
+```bash
+task scm:sync-default -- --dry-run
+task scm:sync-default -- --max-files 100
+```
+
+- Under the file-count limit: one new PR from source tip to dest.
+- Over the limit: merge-commit cuts; each dest-based leg is a new branch and a new PR. After a leg merges, run the verb again.
+- ⊗ `gh pr edit --base` or close-reopen of an oversized PR. Each leg must be new when the reviewer first sees it.
+- Required checks stay on except the Wave 1 core-guard sync exemption.
+
+Docs: [scm/github.md](./scm/github.md) § Default-branch sync.
+
+---
+
 ## Structured decision log (#1396)
 
 Lightweight intent-debt records for **significant** choices (architecture, product behavior, security, public/private boundary, data model, runtime topology, hard-to-reverse process). Not every trivial scope. Not ADR migration; leave `docs/decisions/ADR-*.md` alone. Split from lessons (#1513).
@@ -273,8 +291,8 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 - `task verify:xbrief-conformance` -- validate xBRIEF conformance surfaces.
 - `task verify:cache-fresh` -- validate cache freshness where required.
 - `task verify:capacity`, `task verify:wip-cap`, and `task verify:judgment-gates` -- policy/capacity gates.
-- `task verify:orphan-active` -- fail closed when active/running xBRIEFs still point at closed issues or merged PRs (#2321).
-- `task verify:completed-tracked` -- fail closed when closed scoped issues lack a tracked `xbrief/completed/` or `xbrief/cancelled/` artifact on the delivery tip (#3264); remediate with `task swarm:finalize-cohort` or a lifecycle PR. Standalone verb (not part of `task check`); use `--tip HEAD` when validating an in-flight land branch.
+- `task verify:orphan-active` -- fail closed when active/running xBRIEFs still point at closed issues or merged PRs (#2321). After merge, `task verify:orphan-active -- --issue N` scans briefs that reference that issue. Confirmed shipped prints `task scope:complete -- <path>`; unresolved lookup prints a retry remediation and still exits 1 (#3429). PR-only briefs stay on the unscoped scan or `task swarm:complete-cohort`.
+- `task verify:completed-tracked` -- fail closed when closed scoped issues lack a tracked `xbrief/completed/` or `xbrief/cancelled/` artifact on the delivery tip (#3264 / #3476); remediate with `task swarm:finalize-cohort` or a lifecycle PR. `task verify:completed-tracked -- --issue N` is the drive-to DONE form (delivery tip `origin/<deliveryBranch>`, not feature HEAD). Standalone verb (not part of `task check`); use `--tip HEAD` when validating an in-flight land branch. An unresolvable delivery tip fails closed (no silent HEAD fallback) -- fetch the delivery branch or pass an explicit `--tip`. Under `--skip-gh`, a named `--issue` with no cached state fails closed; the unscoped corpus scan keeps the offline allowance. Lifecycle-only lands (completed/cancelled xBRIEFs + optional CHANGELOG) use that verb plus finalize-cohort or the lifecycle PR. ⊗ Full `task check` / the TypeScript suite. ⊗ The drive-to story envelope (pre-pr + review-cycle + suite) for a file-copy land.
 - `task verify:ac` -- product-first acceptance gate (#3284). Runs `plan.acceptance.commands` (or #3267 literal ledger) **verbatim** before done; records AC-source rung (`stated`/`derived`/`project_floor`). Empty commands require `none_stated: true`. Empty resolution is not a green run when the project has no suite floor (`soft_empty` + stamp-acceptance remedy, #3334). Primary name used first in `task check` (fail-fast); `--soft-missing-xbrief` for check composition. Rapid ceremony = AC-only; pressure/degraded makes hygiene advisory. `--capture-only` lists resolved commands without executing. Extends #3267 / #973.
 - `task verify:literal-ac` -- #3267 mechanism alias for verbatim stated-command run (same flags/cwd); prefer `verify:ac` for product-first done-gate.
 - `task coverage:hotspots` / `deft coverage:hotspots` -- read the latest coverage report, compare global metrics to the project's vitest thresholds, fail closed below the branch floor or below configured headroom (default 0.3pp), and list lowest modules plus uncovered branch samples for git-diff paths (`--json` for agents). Complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573); does not replace them.
@@ -375,6 +393,7 @@ After CLI/deposit upgrade, disk can show the new generation while a long-lived s
 - ! **USER.md path (#2544):** resolve via `deft session:start` output (`USER.md resolved …`); default platform paths: Windows `%APPDATA%\deft\USER.md`, Unix `~/.config/deft/USER.md`; override `$DEFT_USER_PATH`; workspace `<project>/.deft/USER.md`. ⊗ Invent or search `~/.config/deft` on Windows — AppData Roaming is canonical.
 - ! At mutation boundaries (code-writing, scope lifecycle moves, `start_agent`, commits, pushes, PR-from-local-changes, release work): run the mutable quick tier then gated verifier below before proceeding.
 - ? Explicit read-only alignment only: `deft session:start -- --read-only` (no ritual-state write).
+- ! **Worktree occupancy (#3433):** mutation `session:start` / `session:ready` claim a gitignored `.deft/occupancy.json` lease. A second mutation session on the same tree with a different `DEFT_SESSION_ID` fails closed (occupant id, intent, heartbeat age + remediation). Same-session re-arm heartbeats and keeps that id — it does not mint a new UUID. Steal with `occupancy:steal --confirm --occupant <id>` (or `session:start --steal --confirm --occupant <id>`). Expired heartbeat (20 min) is free. `--read-only` does not claim. Join (`occupancy:request`) is named in the remediation only. `swarm:launch` persists `occupancy_session_id` in a cohort-keyed record; close-out must use that cohort's entry (or `DEFT_SESSION_ID`), never a slot another launch can overwrite and never the live lease file.
 - ~ Operators MAY still explicitly request full `deft session:start`, `deft triage:welcome`, sync, or doctor in read-only sessions.
 
 ### Assist / research posture (#1802)
@@ -402,7 +421,7 @@ Cross-link: spawn three postures and deny recoveries live under § Agent-host di
 
 ### Mutable ritual (mutation posture)
 
-- ! On **mutation** session start, run `deft session:start` (or `task session:start` in framework source) after loading AGENTS.md. Records quick-tier ritual in `.deft/ritual-state.json`: alignment confirmation, branch-policy disclosure, `deft verify:tools` guidance, default-branch sync warnings, and `deft triage:welcome` one-liner. State is worktree- and HEAD-bound; stale after `plan.policy.sessionRitualStalenessHours` hours (default 4).
+- ! On **mutation** session start, run `deft session:start` (or `task session:start` in framework source) after loading AGENTS.md. Records quick-tier ritual in `.deft/ritual-state.json`: alignment confirmation, branch-policy disclosure, `deft verify:tools` guidance, default-branch sync warnings, and `deft triage:welcome` one-liner. State is worktree- and HEAD-bound; stale after `plan.policy.sessionRitualStalenessHours` hours (default 4). Mutation start also claims the worktree occupancy lease (`.deft/occupancy.json`); see Session routing (#3433).
 - ! **Orientation compression Now (#3286):** mutation cold `session:start` composes `doctor` + #3282 toolchain preflight (and deposit-sha fast-paths for `agents:refresh` / `verify:cache-fresh`) as inline sections with per-section status lines — composition of existing steps, not a new monolith. When the deposit fingerprint (payload + templates + engine) is unchanged, refresh surfaces print one-line `unchanged - sha match` no-ops. Opt-in compact output: `deft session:start -- --compact` or `DEFT_SESSION_COMPACT=1` (verbose remains the default). #2176 read-only default is unchanged. Dual-path Later (`deft orient`) stays open until run-summary telemetry shows ritual+gate share ≥ 25% after Now ships (#2899).
 - ! Cold `session:start` does **not** run the live agent-hook probe. Functional readiness belongs to the gated mutation path so cold ceremony retains the #2990/#2991 latency profile.
 - ! **Hot path latency (#2991):** by default, mutation `session:start` does **not** block ritual-state write on optional network. It skips the npm release-availability probe and triage cache empty-hydrate / self-heal (`ensureTriageCacheHydrated` / `maybeSelfHealCache`). Targets (operator-facing, not CI-hard): warm hot path typically under a few seconds once tools are on PATH; cold path dominated by local `verify:tools` and git, usually well under ~30s when optional network is off. Empty-cache GitHub fetch-all and npm `view` previously accounted for multi-minute hangs in the WWYSYDH pilot — those stay off the critical path unless opted in.
@@ -587,9 +606,10 @@ flowchart TD
   - `task pr:check-closing-keywords` -- Layer 0 FP lint (#737) **plus intent mode** (#3015 class D). Default `--mode both`: fails on negation/quote/example/code-block hits **and** on any real `Closes|Fixes|Resolves #N` unless allowlisted via `--allow-close N,M` (CLI only; body trailers are not an authorization path). Offline: `--body-file` / `--commits-file`. Prefer `Tracking: #N` / `Refs #N` until full issue DoD.
 - `task release:*` -- release, publish, rollback, and e2e release rehearsal.
   - Step 3 (`Pre-flight vBRIEF lifecycle sync`) fetches GitHub issue states via REST. On HTTP 403 rate-limit exhaustion it sleeps once (capped at 120s) and retries before failing.
-  - When Step 3 still fails with rate-limit exhaustion, stderr includes a `gh api rate_limit` probe (`core.remaining`, reset time) and recovery guidance. After local `task vbrief:validate` (or `task xbrief:validate`) exits 0, operators may pass `--allow-vbrief-drift` to skip Step 3 for that cut — reserved for transient SCM bucket stalls, not unreviewed lifecycle drift.
+  - When Step 3 still fails with rate-limit exhaustion, stderr includes a `gh api rate_limit` probe (`core.remaining`, reset time) and recovery guidance. After local `task xbrief:validate` exits 0, operators may pass `--allow-vbrief-drift` to skip Step 3 for that cut — reserved for transient SCM bucket stalls, not unreviewed lifecycle drift.
 - `task swarm:*` -- readiness, launch, pre-dispatch deny gate (#3228), review-clean verification, and cohort completion.
-- **Operator follow-up after dual-stop / hard stop (#3273):** when a dual-stop or conf-hold halt report lands, re-authorize one residual pass with phrases *pursue residual* / *follow-up hard-stop* / *same as conf-hold* / *continue dual-stopped PR* — steps in `skills/deft-directive-swarm` and `skills/deft-directive-review-cycle` § Operator follow-up after dual-stop / hard stop (not a separate task verb).
+- **Operator follow-up after dual-stop / hard stop (#3273 / #3448):** one-shot *pursue residual* / *follow-up hard-stop* / *same as conf-hold* / *continue dual-stopped PR* is one pass then re-stop. Standing *until floor or loop* / *until greptile meets policy* / *pursue residuals until told otherwise* keeps class A leftovers on open cohort/plan units moving until the resolved `#3095` floor or the **Same-fingerprint stop** in `skills/deft-directive-review-cycle/SKILL.md` Dual stop (not a separate task verb). Steps in `skills/deft-directive-swarm` and `skills/deft-directive-review-cycle` § Operator follow-up after dual-stop / hard stop.
+
 - `task slice:*` -- feature-slice helpers.
 - `task policy:*` and `task capacity:*` -- policy inspection and allocation helpers.
 

package/docs/directive-lifecycle.md

@@ -65,14 +65,22 @@ framework:
 | **Ship** | PR merge and release — `task pr:*` and [`deft-directive-release`](../skills/deft-directive-release/SKILL.md). |
 | **Issues / Features** | GitHub issues and feature requests mirrored into `.deft-cache/` and surfaced as triage candidates. |
 
-## Delivery integrity vs deploy / UAT (#3041)
+## Delivery integrity vs deploy / UAT (#3041 / #3380)
 
 `scope:complete` and swarm cohort completion mark **lifecycle bookkeeping**, not environment
 green. For **code-bearing** scopes, delivered completion requires durable proof that the
 implementation reached the configured **delivery branch** (`plan.policy.deliveryBranch`,
-defaulting to the repo default branch) — typically: PR `base.ref` equals that branch, and the
-merge commit is an ancestor of the refreshed remote delivery ref. A merge into an intermediate
-feature/integration branch is **not** delivery.
+defaulting to the repo default branch). Ancestry on the refreshed remote delivery ref
+(`origin/<deliveryBranch>`) is delivery. PR `base.ref` / `prBase` is provenance only: a
+develop-targeted scope PR can still complete as delivered when its merge commit is already
+an ancestor of `origin/<deliveryBranch>`. `merged_to_integration` applies only when that
+ancestry fails.
+
+Squash-sync from develop to main can rewrite commits so a develop merge SHA is no longer
+an ancestor of `origin/main`. Wait until the work is reachable on the delivery ref, or
+type `plan.policy.deliveryBranch` to the branch you actually ship from
+(`task policy:show --field=deliveryBranch`). This document does not prescribe a squash-sync
+repair.
 
 Handoff states that Git can assert are distinct: `implemented` → `pr_open` →
 `merged_to_integration` → `delivered`. **Deployed** and **UAT verified** are separate evidence

package/docs/project-invariants.md

@@ -0,0 +1,79 @@
+# Project invariants (`plan.policy.projectInvariants`)
+
+Refs: #3425 · Related: #3238 `coverage_map`, #3241 parent lineage, #516 / #3145 `file_scope`
+
+Authored must-not-break contracts for a shared product. Every running story must
+declare how it treats the invariants that apply to its `file_scope`. Empty or
+absent list is a no-op.
+
+## Authored list
+
+SoT is PROJECT-DEFINITION `plan.policy.projectInvariants`. Inspect with
+`task policy:show --field=projectInvariants`.
+
+Each entry:
+
+- `id` — stable key reused on the scope `coverage_map`
+- `statement` — the contract in operator language
+- contract surface — `paths` and/or `moduleIds` (module ids resolve through
+  `plan.architecture.codeStructure.modules[].pathGlobs`)
+
+## Scope coverage
+
+Reuse the #3238 `coverage_map` shape against **applicable** project IDs:
+
+| Disposition | Required side field |
+| --- | --- |
+| `covered` | none |
+| `deferred` | `provenance.reason` + target |
+| `behavioral_delta` | `delta_id` linked in `behavioral_deltas` |
+| `not_applicable` | `reason` |
+
+`split` is excluded at project level.
+
+Applicability is contract surface × the story's `file_scope`. Empty intersection
+means no disposition is required for that ID.
+
+## Gate
+
+`task xbrief:preflight` and `task verify:story-ready` fail closed when an
+applicable ID has no disposition. The message names the omitted ID. Slice-scoped
+and worktree-scoped stories use the same check.
+
+The check evaluates the list **as of preflight time**. An ID added after a story
+was authored fails that story on its next preflight and names the new ID.
+
+## Honesty limit
+
+The gate verifies **completeness of declarations**, not truth. A scope cannot
+break an *undeclared* applicable contract without failing preflight. A declared
+`covered` is not executed or scored. Truth-checking is review-cycle / follow-up.
+
+This slice does **not** load the list at session-start or in the preamble.
+
+## Authored examples (not framework oracles)
+
+Operators author product entries. Directive never runs Visage or scores
+"module purpose." Two shapes that belong in a consumer PROJECT-DEFINITION, not
+in Directive itself:
+
+```json
+{
+  "plan": {
+    "policy": {
+      "projectInvariants": [
+        {
+          "id": "visage-load-save",
+          "statement": "Launch-prep must not change a project folder so Visage can no longer load it.",
+          "paths": ["src/launch-prep/**"]
+        },
+        {
+          "id": "sibling-purpose",
+          "statement": "Existing modules stay independently useful. Integration with a new module is optional; independence is required.",
+          "moduleIds": ["project-io", "canvas"]
+        }
+      ]
+    }
+  }
+}
+```

package/docs/scope-provenance.md

@@ -58,32 +58,77 @@ Authority comes from the approval record in the **merge base**, not from whether
 
 ## Operator command: `scope:record-approved-scope`
 
-Deposit a human-origin digest (first adoption or renewal):
+Deposit a human-origin digest (first adoption or renewal). Mint on a real TTY, then commit the approval artifacts to the merge base (or a prior PR) before implement.
 
 ```bash
-task scope:record-approved-scope -- xbrief/pending/story.xbrief.json --actor scott
+task scope:record-approved-scope -- xbrief/pending/story.xbrief.json --actor scott --confirm
 # or after expansion review:
-task scope:record-approved-scope -- xbrief/active/story.xbrief.json --actor scott --kind renewed-approval
+task scope:record-approved-scope -- xbrief/active/story.xbrief.json --actor scott --kind renewed-approval --confirm
 ```
 
+`--actor` is **display only**. It never authorizes mint. `--actor Flynn` from an agent or CI shell cannot mint.
+
+Mint uses the shared #3110 human-presence gate (same module as `authz`):
+
+- Interactive TTY (stdin + stdout) and a controlling terminal (`/dev/tty` or `CONIN$`)
+- Explicit `--confirm`
+- Typed phrase `mint` on the controlling TTY
+- Agent/CI env markers (`AUTHZ_AGENT_SHELL_ENV_MARKERS`) refuse fail-closed
+- An active UAT lease refuses mint with no TTY / `--confirm` / phrase escape
+
+No authz grant is written. `verify:scope-provenance` does not read `.deft/authz/grants`.
+
 Flags:
 
 | Flag | Required | Notes |
 | --- | --- | --- |
 | `<xbrief-path>` | yes | pending or active xBRIEF JSON |
-| `--actor` | yes | human operator identity (agent actors refused) |
+| `--actor` | yes | display-only human identity (never authorization) |
+| `--confirm` | yes | required; flag alone never authorizes mint |
 | `--kind` | no | default `operator`; also `human`, `renewed-approval`, … |
 | `--project-root` | no | defaults via Taskfile to consumer CWD |
 | `--xbrief-rel-path` | no | override path binding; default maps `pending/` → `active/` |
+| `--repo` | no | `owner/name` seed for preimage `approvedRepos` (same source as `issue:emit`) |
+
+Commit **both** `.deft/approved-scope/<plan-id>.json` and `<plan-id>.intent.json` on the **merge base** (or a prior PR) before the implementation PR activates or expands the scoped xBRIEF. Read the preimage before you commit — that file is the approved intent.
+
+## Three layers (do not mix)
+
+| Layer | What it is | Who writes it |
+| --- | --- | --- |
+| **Product intent** | What the story asks for — titles, narratives, acceptance, architecture, items, edges, origin refs | Human in the xBRIEF |
+| **Approved derivation** | The extracted preimage + path digest frozen at mint | `scope:record-approved-scope` on a TTY |
+| **Implementation choice** | How the worker codes the story | The implementation PR; must not rewrite pinned intent |
+
+`verify:scope-provenance` compares live extraction to the **base-committed** preimage. It never treats working-tree copies, `xbriefBodyDigest`, or authz grants as authority.
+
+## Wave 2 intent pin (#3385)
+
+Mint writes one record and one preimage as a fail-closed pair under a per-plan lock. Both dests land as `.next` first, then dests copy from that pair. A crash mid-publish is recovered without a remint: finish the flip from `.next`, or restore the bak pair (or neither dest). Dead-owner lock files are reclaimed. A dest-write failure restores the previous pair or leaves neither dest. If restore also fails, leftover dests are cleared and the mint error names both failures. `intentDigest` is a checksum of `.deft/approved-scope/<plan-id>.intent.json` (`intent-extract-v1`).
+
+Extracted: `plan.title`, `plan.narratives.*`, `plan.acceptance`, `plan.architecture`, `plan.items[]` `{id,title,summary,narrative,type}`, `plan.id`, resolved parent id (`planRef` raw path is machine), origin `references[]` (no `TrustLevel`), `plan.edges`, swarm `file_scope` plus free-text swarm notes, and any unknown `plan.*` key (pinned wholesale). `plan.tags` is machine.
+
+Verify:
+
+1. `git show <base>:` for record **and** preimage
+2. Recompute preimage digest vs `intentDigest`
+3. Re-extract the live brief and compare
+4. Same-PR rewrite of record or preimage fails
+5. Duplicate object keys need a real tokenizer (not `JSON.parse`)
+6. `Decisions` and `references[]` are append-only; new github-issue URLs must be in the base `approvedRepos`
+
+First activation with nonempty `file_scope` needs that base-committed pin. Same-PR mint + activate fails.
+
+### Wave 1 records are legacy under Wave 2 (#3384 / #3385)
 
-Commit the written `.deft/approved-scope/<plan-id>.json` on the **merge base** (or a prior PR) before the implementation PR activates or expands the scoped xBRIEF.
+Wave 1 mints write the path record with a human-looking stamp. They do **not** write `xbriefBodyDigest` and they carry **no** `intentDigest`. Under Wave 2 those records are **legacy**: they authorize **paths only**. Intent edits warn this release, then fail; gated remint is the remediation. That is intended, not a bug. No silent backfill.
 
 ## First-adoption flow (single consumer upgrade)
 
 When the first non-empty `file_scope` story and the 0.97+/0.98 gate land together:
 
 1. Author the pending xBRIEF with the intended `file_scope`
-2. Run `task scope:record-approved-scope -- <pending-xbrief> --actor <you>`
+2. Run `task scope:record-approved-scope -- <pending-xbrief> --actor <you> --confirm`
 3. **Commit and merge** the approval record (and preferably the pending xBRIEF) first — multi-PR bootstrap
 4. In a follow-up PR, activate (`pending/` → `active/`) without rewriting the approval
 5. `task verify:scope-provenance -- --base-ref origin/master --enforce` exits 0
@@ -105,8 +150,8 @@ Emptying `file_scope` to soft-warn past the gate is **not** the supported migrat
 ## Remediation
 
 ```bash
-task scope:record-approved-scope -- <xbrief-path> --actor <you>
-git add .deft/approved-scope/<plan-id>.json
+task scope:record-approved-scope -- <xbrief-path> --actor <you> --confirm
+git add .deft/approved-scope/<plan-id>.json .deft/approved-scope/<plan-id>.intent.json
 # merge that commit before (or without) co-changing the active xBRIEF expansion
 ```
 

package/main.md

@@ -200,10 +200,12 @@ Propagation: the canonical orchestrator preamble at [templates/agent-prompt-prea
 - ! Scope vBRIEFs live in lifecycle folders: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`
 - ! Scope vBRIEF filenames MUST follow: `YYYY-MM-DD-descriptive-slug.vbrief.json` (slug rules: [`conventions/vbrief-filenames.md`](./content/conventions/vbrief-filenames.md))
 - ! Playbooks use `playbook-{name}.vbrief.json` (named, not ULID-suffixed)
+- ! Completed xBRIEFs are evidence of what was built — full standing as a record of *what is*, zero authority over *what to build next* (#3383). The current contract is the active xBRIEF plus the human operator's live instruction. Both halves are required.
 - ⊗ Use ULID-suffixed filenames for plan, todo, or continue files
 - ⊗ Place vBRIEF files at workspace root
 - ⊗ Write `SPECIFICATION.md` directly — it MUST be generated from `specification.vbrief.json`
 - ⊗ Move scope vBRIEFs between lifecycle folders without updating `plan.status`
+- ⊗ Treat a completed xBRIEF as the next-build contract, or let it override the active story or the live human instruction
 
 ### Schema version: v0.6 (canonical)
 

package/meta/ralph.md

@@ -115,7 +115,7 @@ For each code generation, check:
 - [ ] **Documentation complete**
 - [ ] **No obvious security issues**
 - [ ] **Dependencies justified**
-- [ ] **Files <500 lines** (must be <1000)
+- [ ] **Files stay small** (review trigger, not a hard cap; see file-size-thresholds policy module / #1488 / #3424)
 
 ## 🛠️ Implementation in Warp (TBD)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.104.0",
+  "version": "0.105.0",
   "deftConsumerDeposit": true,
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "license": "MIT",

package/packs/rules/rules-pack-0.1.json

@@ -65,7 +65,7 @@
       "domain": "coding",
       "text": "All *.md in `docs/` directory (except README.md, AGENTS.md, WARP.md)",
       "path": "coding/coding.md",
-      "body": "# Coding Guidelines\n\nSoftware development specific guidelines for AI agents.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also** (load only when needed):\n- [../main.md](../../main.md) - General AI behavior and agent persona\n- [PROJECT.md](../../PROJECT.md) - For project-specific overrides\n- [../tools/telemetry.md](../tools/telemetry.md) - When implementing logging/tracing/metrics\n\n## Code Organization\n\n**Documentation:**\n- ! All *.md in `docs/` directory (except README.md, AGENTS.md, WARP.md)\n- ! Prior tasks/plans in `history/`\n- ! When code changes user-visible behavior, update matching user-facing docs in the same PR \u2014 see [docs.md](docs.md) (#447; lazy-load, not AGENTS always-on)\n\n**Filenames:**\n- ~ Use hyphens not underscores (unless language idiom)\n\n**Secrets:**\n- ! ALL secrets in `secrets/` dir as .env files\n- \u2297 Secrets in code\n\n## Code Search\n\n- ! use `rg`, or `ast-grep` (when available) instead of grep\n- ! Use Warp's built-in grep (which is rg) when running on warp\n- ~ Install if missing\n- ? Fall back to `grep` command only if tools cannot be installed\n\n## Version Control\n\nSee [../scm/git.md](../scm/git.md) for:\n- Commit conventions (Conventional Commits)\n- Safety rules (no force-push without permission)\n- Branch workflows\n\n## Code Design\n\n**Modularity:**\n- ! One responsibility per file/module\n- ~ Files <300 lines ideal; <500 lines recommended; <1000 lines a review trigger \u2014 split when exceeded unless genuinely single-responsibility (size is a smell, not a hard cap; #1488)\n- ! Explicit scope in task descriptions\n- ~ DRY: extract shared abstractions when logic is duplicated across 2+ call sites\n- \u2297 Copy-paste logic with minor variations \u2014 parameterise instead\n\n**Dependency Direction:**\n- \u2297 Circular imports between modules/packages\n- ~ Layered architecture: high-level modules depend on low-level ones, never the reverse\n- ! Use dependency inversion (interfaces/protocols) to break coupling across layers\n- See [hygiene.md](hygiene.md) for detection tools (madge, pydeps, Go compiler)\n\n**Contract-First:**\n- ! Define interfaces/types/protocols before implementation\n- ! Changes to public interfaces require explicit versioning or deprecation path\n- ! Document all public API contracts clearly\n\n**Immutability:**\n- ~ Prefer immutable data + pure functions\n- ~ When mutation needed, use narrow owned scopes (context managers, RAII)\n- \u2297 Global or singleton mutable state (almost always)\n\n**Error Handling:**\n- ~ Prefer Result/Option types or explicit exceptions over None/null/undefined\n- ! Document possible exceptions/error codes for all public functions\n- ! Validate all inputs at API boundaries\n- \u2297 Trust caller without validation\n- \u2297 Empty catch/except/recover blocks that swallow errors silently\n- \u2297 Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask errors \u2014 propagate explicitly\n- \u2297 Log-and-continue: catching an error and proceeding as if it didn't happen, unless provably non-fatal and documented\n- See [hygiene.md](hygiene.md) for full error-hiding anti-pattern catalogue\n\n**Readability:**\n- ! Follow language idioms strictly\n- ! Meaningful names over short names\n- ! Comments explain **why**, code shows **what**\n- \u2297 Clever code over clear code\n\n**State & Data Modeling (#1695):**\n- ! A field MUST encode exactly one fact. Do NOT overload a field's value \u2014 or its presence/absence \u2014 to also signal a second orthogonal concern. Smuggling decision-, config-, lifecycle-, or control-state through a data field is *in-band signaling*; give that signal its own out-of-band field.\n- ! \"Absence is not a decision.\" Distinguish \"unset / never considered\" from \"deliberately set to the default.\" If a workflow must know a human made a choice, record the choice explicitly \u2014 never infer it from whether a value-field is present.\n- ~ Orthogonality test: if two facts can vary independently (e.g. value==default while decided \u2208 {true,false}), they MUST live in separate slots. If one fact strictly implies the other (true Optional<T>, tombstones), sharing a slot is fine.\n- \u2297 Infer decision / onboarding / configuration state from the presence of a value field. Use an explicit out-of-band marker \u2014 cf. the resolver `source` provenance pattern (typed | default | default-on-error) directive already uses for *value*-provenance.\n- See [../patterns/in-band-signaling.md](../patterns/in-band-signaling.md) for the full model, orthogonality procedure, and the wipCap worked example (#1694).\n\n## Quality Standards\n\n**General:**\n- ! Run all relevant checks (lint, fmt, quality, build, test) before submitting changes\n- \u2297 Claim checks passed without running them\n- ! If checks cannot run, explicitly state why and what would have been executed\n- ~ Prioritize code quality and readability over backwards compatibility\n\n**Testing:**\n- ! Implementation is INCOMPLETE until tests written AND `task test:coverage` passes\n- See [../coding/testing.md](../coding/testing.md) for universal requirements\n\n**Security:**\n- ! Apply baseline security standards to every project from day one\n- 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)\n\n**Review process (#1471 / #212):**\n- ! Apply tool-agnostic review-cycle principles on every PR review response\n- 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\n- Greptile/GitHub adapter: [../skills/deft-directive-review-cycle/SKILL.md](../skills/deft-directive-review-cycle/SKILL.md)\n\n**Codebase Hygiene:**\n- See [hygiene.md](hygiene.md) for: dead code removal, circular dependency detection, error hiding patterns, legacy/deprecated code cleanup\n\n**Telemetry:**\n- See [../tools/telemetry.md](../tools/telemetry.md) for recommendations\n- ~ Structured logging for production\n- ~ Error tracking (Sentry.io or equivalent)\n- ? Distributed tracing for complex systems\n\n## Fail Loud: Completion Claims Require Outcome Verification (#1006)\n\nThe failure mode is the agent stating completion at the level of **intent** (\"I ran the migration\", \"the tests pass\", \"the feature works\") rather than at the level of **outcome verification** (\"all 167 records migrated, 0 skipped\", \"42 tests collected, 42 passed, 0 skipped, 0 xfailed\", \"the edge case asked about was reproduced and now returns the expected value\"). Outcome-blind completion claims hide silent skips, swallowed exceptions, suppressed errors, and unverified edge cases behind successful-sounding language. The example from the source: a database migration that completed \"successfully\" had silently skipped 14% of records on a constraint violation; the skip was logged but not surfaced; the bad reports were discovered 11 days later.\n\nThis rule is the OPERATIONAL complement to the EPISTEMIC honesty rules elsewhere in the framework (`main.md` morals section: don't present speculation as fact; label unverified claims). Morals.md says \"don't lie\". Fail-loud says \"count the records, check the logs, run the edge case, **then** claim completion.\" It is also the output-side complement to [goal-gate-determinism](../patterns/goal-gate-determinism.md) (#852 \u2014 the gate specifies what evidence is required) and machine-verifiable-spec (verification commands prevent silent skips) -- without fail-loud, an agent can satisfy the letter of a gate (\"tests pass\") while hiding the gap (\"some tests were skipped\").\n\n- ! Before claiming a batch operation succeeded, MUST verify the record count and surface it in the claim (\"migrated 167/167 records, 0 skipped, 0 errored\" -- not \"migration completed\")\n- ! Before claiming \"tests pass\", MUST report the count of collected / passed / skipped / xfailed / errored tests (\"42 collected, 42 passed, 0 skipped\" -- not \"tests pass\"). A skipped or xfailed test is NOT a passing test for the purpose of this claim\n- ! Before claiming \"the feature works\", MUST report the specific edge case that was verified (if the user asked about a specific edge case, that edge case MUST be in the verification report; \"the happy path works\" is not equivalent to \"the feature works\")\n- ! Before claiming a migration / data transform / batch job completed, MUST check the error log AND the skip log AND the constraint-violation surface; surface the counts even when zero (\"0 skipped, 0 errored\" is the load-bearing claim, not silence)\n- ! When uncertainty exists about whether something worked, MUST surface the uncertainty explicitly (\"the migration completed and reported success but I have not verified the per-record count -- recommend running `<verification-command>` before declaring done\")\n- \u2297 MUST NOT claim \"tests pass\" when any test was skipped, xfailed, or run with errors suppressed -- report the full counts instead\n- \u2297 MUST NOT claim \"migration completed\" / \"batch succeeded\" / \"job finished\" without checking and reporting the per-record outcome counts\n- \u2297 MUST NOT claim \"feature works\" when only the happy path was verified -- name the edge case that was tested, or surface that it wasn't\n- \u2297 MUST NOT use successful-sounding completion phrasing to paper over uncertainty -- default to surfacing uncertainty, not hiding it\n- \u2297 MUST NOT suppress error output (`2>$null`, `2>/dev/null`, `try/except: pass` around the verification command) and then claim completion based on the resulting silence\n\n- ! Before claiming \"feature complete\", \"ready for real users\", \"production-ready\", or equivalent area-complete language for a surface that has open graduations (Now+Later dual-path locks; #2899), MUST name the open `graduationRef`s, **or** explicitly state that graduation review was skipped and why \u2014 otherwise the claim is outcome-blind under this rule\n- \u2297 MUST NOT claim \"feature complete\" / \"production-ready\" / \"ready for real users\" for an area with open graduations without naming those `graduationRef`s or an explicit skip-with-reason\n\nThe 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.\n\n**Cross-references:** strategies discuss/probe Graduation dual-path locks (#2899); `## Quality Standards` above (`\u2297 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); [`patterns/goal-gate-determinism.md`](../patterns/goal-gate-determinism.md) (#852 \u2014 rigid goals/gates, flexible path); `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).\n\n## Calling LLM APIs (#481)\n\nWhen the project calls LLM APIs (OpenAI, Anthropic, Cohere, local models, etc.) or builds agentic functionality, the architectural standards in `patterns/llm-app.md` apply alongside the coding rules above. In the directive maintainer repo this section is **guidance for consumer projects** \u2014 provider names are illustrative labels under the framework instruction hierarchy, not runtime SDK surfaces (#2414; see `meta/security.md` `## Informational AppSec findings`). The short form:\n\n- ! User input is NEVER placed in the system prompt; the system prompt is the trust boundary\n- ! External content is ALWAYS wrapped in explicit delimiters (`<user_input>`, `<document>`, `<tool_result>`) and surfaces its trust tier\n- ! Tool call arguments are validated against a schema BEFORE execution (the LLM is a confused deputy)\n- ! LLM outputs are validated against expected schemas before being acted upon (no eval-of-output, no shell-of-output, no SQL-of-output)\n- \u2297 MUST NOT write LLM outputs back into the retrieval corpus in the same session without validation (RAG poisoning vector)\n\nSee [../patterns/llm-app.md](../patterns/llm-app.md) for the full standards: prompt construction, trust tiers, tool/function-call validation, RAG hygiene, output handling, multi-agent orchestration, and LLM-specific observability. See [../tools/telemetry.md](../tools/telemetry.md) `## LLM-specific observability (#481)` for the matching observability surface.\n\n## Debugging and Root-Cause Investigation (#1621)\n\nWhen a bug, failure, or unexpected behaviour needs diagnosis, the root-cause standards in `debugging.md` apply. The short form:\n\n- ! No fixes without root-cause investigation first (the Iron Law)\n- ! Reproduce the failure consistently before proposing a fix \u2014 a non-reproducible bug is not yet understood\n- ! Every factual claim cites evidence; an uncited claim is a `[HYPOTHESIS]`, not a finding (evidence before narrative)\n- ! Runtime/config values are proven from the runtime, never inferred from source code (config is not code)\n- \u2297 MUST NOT present a duration or an exit status (\"slow because phase X took N minutes\", \"failed because it timed out\") as a root cause \u2014 name a mechanism (no tautologies)\n- ! After 3 failed distinct fixes, STOP and escalate for architectural review (the 3-fix gate)\n\nSee [debugging.md](debugging.md) for the full four-phase process, evidence discipline, Fact vs Hypothesis labeling (#1580), the observability-gap loop, and the rationalization table. For a sustained multi-agent investigation posture, see the `deft-directive-debug` skill.\n\n## Build Automation\n\n**Taskfile:**\n- ! Use Task ([go-task](https://taskfile.dev)) for all repeatable operations\n- ! If `task` not found, attempt to install go-task\n- ! If installation fails, stop and ask user for help\n- See [../tools/taskfile.md](../tools/taskfile.md) for standards and common commands\n\n**Toolchain Validation:**\n- See [../coding/toolchain.md](../coding/toolchain.md) for rules on verifying required tools are installed before implementation begins\n\n**Build Output Validation:**\n- See [../coding/build-output.md](../coding/build-output.md) for rules on verifying `dist/` artifacts and non-compiled assets after custom build scripts run\n\n## Change Management\n\n**Impact Awareness:**\n- ! Before changing shared code, identify affected downstream modules/files\n- ~ Prefer additive changes (new functions, fields with defaults) over breaking renames\n- ! Make small, reversible changes\n- ! Explain impact and migration path for breaking changes\n\n**Production Safety:**\n- ! Assume production impact unless stated otherwise\n- ! Call out risk when touching: auth, billing, data, APIs, build systems\n- \u2297 Silent breaking behavior\n- ~ Test changes in staging/dev environment when possible\n\n## Language-Specific Guidelines\n\n**Languages:**\n- C++: [../languages/cpp.md](../languages/cpp.md)\n- Go: [../languages/go.md](../languages/go.md)\n- Office.js: [../languages/officejs.md](../languages/officejs.md)\n- Python: [../languages/python.md](../languages/python.md)\n- TypeScript: [../languages/typescript.md](../languages/typescript.md)\n- VBA: [../languages/vba.md](../languages/vba.md)\n\n**Interface Types:**\n- CLI: [../interfaces/cli.md](../interfaces/cli.md)\n- TUI: [../interfaces/tui.md](../interfaces/tui.md)\n- Web: [../interfaces/web.md](../interfaces/web.md)\n- REST API: [../interfaces/rest.md](../interfaces/rest.md)\n\n## Development Workflow\n\n**Localhost:**\n- No permission needed for curl localhost\n\n**Plans:**\n- ~ Create both:\n  1. Warp plan (using `create_plan` tool)\n  2. Archive copy in `history/plan-YYYY-MM-DD-description.md`\n\n## Project Context\n\n- ! Check [PROJECT.md](../../PROJECT.md) for project-specific overrides\n- ~ Inspect project config (package.json, pyproject.toml, etc.) for available scripts\n- ! Follow project-specific testing, coverage, and quality requirements\n\n## Anti-Patterns\n\n- \u2297 Secrets in code or version control\n- \u2297 Claiming checks passed without running them\n- \u2297 Single files mixing multiple responsibilities (large line count, e.g. >1000 lines, is a trigger to check cohesion \u2014 not a defect by itself; #1488)\n- \u2297 Skipping quality checks\n- \u2297 Breaking changes without explicit approval\n- \u2297 Using `grep` command when `rg` or Warp grep available\n- \u2297 Implementing code without tests\n- \u2297 Claiming \"done\" before running test:coverage\n- \u2297 Ignoring coverage drops\n- \u2297 Weak types (`any`, `interface{}`, untyped `object`) where concrete types are knowable\n- \u2297 Dead code: unused functions, unreachable branches, stale feature flags, commented-out blocks\n- \u2297 Error hiding: empty catch blocks, silent fallbacks, swallowed exceptions\n- \u2297 Circular imports between modules\n- \u2297 Duplicate logic across 2+ call sites without shared abstraction\n- \u2297 Outcome-blind completion claims: \"tests pass\" with skipped tests, \"migration completed\" without per-record counts, \"feature works\" without naming the verified edge case (#1006 -- see `## Fail Loud` above)\n- \u2297 Outcome-blind \"feature complete\" / \"production-ready\" claims that ignore open graduations (`graduationRef`s) without naming them or an explicit skip (#2899 / #1006 -- see `## Fail Loud` above)\n- \u2297 Averaging contradicting codebase patterns: writing new code that satisfies both of two conflicting patterns simultaneously (#1005 -- see `hygiene.md` `## Surface Conflicts`)\n- \u2297 Debugging by guess-and-check: fixing before reproducing, treating the first plausible hypothesis as confirmed, or presenting a duration/exit-status as a root cause (#1621 -- see `debugging.md`)\n"
+      "body": "# Coding Guidelines\n\nSoftware development specific guidelines for AI agents.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also** (load only when needed):\n- [../main.md](../../main.md) - General AI behavior and agent persona\n- [PROJECT.md](../../PROJECT.md) - For project-specific overrides\n- [../tools/telemetry.md](../tools/telemetry.md) - When implementing logging/tracing/metrics\n\n## Code Organization\n\n**Documentation:**\n- ! All *.md in `docs/` directory (except README.md, AGENTS.md, WARP.md)\n- ! Prior tasks/plans in `history/`\n- ! When code changes user-visible behavior, update matching user-facing docs in the same PR \u2014 see [docs.md](docs.md) (#447; lazy-load, not AGENTS always-on)\n\n**Filenames:**\n- ~ Use hyphens not underscores (unless language idiom)\n\n**Secrets:**\n- ! ALL secrets in `secrets/` dir as .env files\n- \u2297 Secrets in code\n\n## Code Search\n\n- ! use `rg`, or `ast-grep` (when available) instead of grep\n- ! Use Warp's built-in grep (which is rg) when running on warp\n- ~ Install if missing\n- ? Fall back to `grep` command only if tools cannot be installed\n\n## Version Control\n\nSee [../scm/git.md](../scm/git.md) for:\n- Commit conventions (Conventional Commits)\n- Safety rules (no force-push without permission)\n- Branch workflows\n\n## Code Design\n\n**Modularity:**\n- ! One responsibility per file/module\n- ~ Keep files small. Ideal, recommended, and review-trigger line counts are FILE_SIZE_IDEAL_LINES, FILE_SIZE_RECOMMENDED_LINES, and FILE_SIZE_REVIEW_TRIGGER_LINES in the file-size-thresholds policy module (packages/core/src/policy/file-size-thresholds.ts). Split when a file exceeds the review trigger unless it is genuinely single-responsibility (size is a smell, not a hard cap; #1488 / #3424)\n- ! Explicit scope in task descriptions\n- ~ DRY: extract shared abstractions when logic is duplicated across 2+ call sites\n- \u2297 Copy-paste logic with minor variations \u2014 parameterise instead\n\n**Dependency Direction:**\n- \u2297 Circular imports between modules/packages\n- ~ Layered architecture: high-level modules depend on low-level ones, never the reverse\n- ! Use dependency inversion (interfaces/protocols) to break coupling across layers\n- See [hygiene.md](hygiene.md) for detection tools (madge, pydeps, Go compiler)\n\n**Contract-First:**\n- ! Define interfaces/types/protocols before implementation\n- ! Changes to public interfaces require explicit versioning or deprecation path\n- ! Document all public API contracts clearly\n\n**Immutability:**\n- ~ Prefer immutable data + pure functions\n- ~ When mutation needed, use narrow owned scopes (context managers, RAII)\n- \u2297 Global or singleton mutable state (almost always)\n\n**Error Handling:**\n- ~ Prefer Result/Option types or explicit exceptions over None/null/undefined\n- ! Document possible exceptions/error codes for all public functions\n- ! Validate all inputs at API boundaries\n- \u2297 Trust caller without validation\n- \u2297 Empty catch/except/recover blocks that swallow errors silently\n- \u2297 Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask errors \u2014 propagate explicitly\n- \u2297 Log-and-continue: catching an error and proceeding as if it didn't happen, unless provably non-fatal and documented\n- See [hygiene.md](hygiene.md) for full error-hiding anti-pattern catalogue\n\n**Readability:**\n- ! Follow language idioms strictly\n- ! Meaningful names over short names\n- ! Comments explain **why**, code shows **what**\n- \u2297 Clever code over clear code\n\n**State & Data Modeling (#1695):**\n- ! A field MUST encode exactly one fact. Do NOT overload a field's value \u2014 or its presence/absence \u2014 to also signal a second orthogonal concern. Smuggling decision-, config-, lifecycle-, or control-state through a data field is *in-band signaling*; give that signal its own out-of-band field.\n- ! \"Absence is not a decision.\" Distinguish \"unset / never considered\" from \"deliberately set to the default.\" If a workflow must know a human made a choice, record the choice explicitly \u2014 never infer it from whether a value-field is present.\n- ~ Orthogonality test: if two facts can vary independently (e.g. value==default while decided \u2208 {true,false}), they MUST live in separate slots. If one fact strictly implies the other (true Optional<T>, tombstones), sharing a slot is fine.\n- \u2297 Infer decision / onboarding / configuration state from the presence of a value field. Use an explicit out-of-band marker \u2014 cf. the resolver `source` provenance pattern (typed | default | default-on-error) directive already uses for *value*-provenance.\n- See [../patterns/in-band-signaling.md](../patterns/in-band-signaling.md) for the full model, orthogonality procedure, and the wipCap worked example (#1694).\n\n## Quality Standards\n\n**General:**\n- ! Run all relevant checks (lint, fmt, quality, build, test) before submitting changes\n- \u2297 Claim checks passed without running them\n- ! If checks cannot run, explicitly state why and what would have been executed\n- ~ Prioritize code quality and readability over backwards compatibility\n\n**Testing:**\n- ! Implementation is INCOMPLETE until tests written AND `task test:coverage` passes\n- See [../coding/testing.md](../coding/testing.md) for universal requirements\n\n**Security:**\n- ! Apply baseline security standards to every project from day one\n- 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)\n\n**Review process (#1471 / #212):**\n- ! Apply tool-agnostic review-cycle principles on every PR review response\n- 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\n- Greptile/GitHub adapter: [../skills/deft-directive-review-cycle/SKILL.md](../skills/deft-directive-review-cycle/SKILL.md)\n\n**Codebase Hygiene:**\n- See [hygiene.md](hygiene.md) for: dead code removal, circular dependency detection, error hiding patterns, legacy/deprecated code cleanup\n\n**Telemetry:**\n- See [../tools/telemetry.md](../tools/telemetry.md) for recommendations\n- ~ Structured logging for production\n- ~ Error tracking (Sentry.io or equivalent)\n- ? Distributed tracing for complex systems\n\n## Fail Loud: Completion Claims Require Outcome Verification (#1006)\n\nThe failure mode is the agent stating completion at the level of **intent** (\"I ran the migration\", \"the tests pass\", \"the feature works\") rather than at the level of **outcome verification** (\"all 167 records migrated, 0 skipped\", \"42 tests collected, 42 passed, 0 skipped, 0 xfailed\", \"the edge case asked about was reproduced and now returns the expected value\"). Outcome-blind completion claims hide silent skips, swallowed exceptions, suppressed errors, and unverified edge cases behind successful-sounding language. The example from the source: a database migration that completed \"successfully\" had silently skipped 14% of records on a constraint violation; the skip was logged but not surfaced; the bad reports were discovered 11 days later.\n\nThis rule is the OPERATIONAL complement to the EPISTEMIC honesty rules elsewhere in the framework (`main.md` morals section: don't present speculation as fact; label unverified claims). Morals.md says \"don't lie\". Fail-loud says \"count the records, check the logs, run the edge case, **then** claim completion.\" It is also the output-side complement to [goal-gate-determinism](../patterns/goal-gate-determinism.md) (#852 \u2014 the gate specifies what evidence is required) and machine-verifiable-spec (verification commands prevent silent skips) -- without fail-loud, an agent can satisfy the letter of a gate (\"tests pass\") while hiding the gap (\"some tests were skipped\").\n\n- ! Before claiming a batch operation succeeded, MUST verify the record count and surface it in the claim (\"migrated 167/167 records, 0 skipped, 0 errored\" -- not \"migration completed\")\n- ! Before claiming \"tests pass\", MUST report the count of collected / passed / skipped / xfailed / errored tests (\"42 collected, 42 passed, 0 skipped\" -- not \"tests pass\"). A skipped or xfailed test is NOT a passing test for the purpose of this claim\n- ! Before claiming \"the feature works\", MUST report the specific edge case that was verified (if the user asked about a specific edge case, that edge case MUST be in the verification report; \"the happy path works\" is not equivalent to \"the feature works\")\n- ! Before claiming a migration / data transform / batch job completed, MUST check the error log AND the skip log AND the constraint-violation surface; surface the counts even when zero (\"0 skipped, 0 errored\" is the load-bearing claim, not silence)\n- ! When uncertainty exists about whether something worked, MUST surface the uncertainty explicitly (\"the migration completed and reported success but I have not verified the per-record count -- recommend running `<verification-command>` before declaring done\")\n- \u2297 MUST NOT claim \"tests pass\" when any test was skipped, xfailed, or run with errors suppressed -- report the full counts instead\n- \u2297 MUST NOT claim \"migration completed\" / \"batch succeeded\" / \"job finished\" without checking and reporting the per-record outcome counts\n- \u2297 MUST NOT claim \"feature works\" when only the happy path was verified -- name the edge case that was tested, or surface that it wasn't\n- \u2297 MUST NOT use successful-sounding completion phrasing to paper over uncertainty -- default to surfacing uncertainty, not hiding it\n- \u2297 MUST NOT suppress error output (`2>$null`, `2>/dev/null`, `try/except: pass` around the verification command) and then claim completion based on the resulting silence\n\n- ! Before claiming \"feature complete\", \"ready for real users\", \"production-ready\", or equivalent area-complete language for a surface that has open graduations (Now+Later dual-path locks; #2899), MUST name the open `graduationRef`s, **or** explicitly state that graduation review was skipped and why \u2014 otherwise the claim is outcome-blind under this rule\n- \u2297 MUST NOT claim \"feature complete\" / \"production-ready\" / \"ready for real users\" for an area with open graduations without naming those `graduationRef`s or an explicit skip-with-reason\n\nThe 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.\n\n**Cross-references:** strategies discuss/probe Graduation dual-path locks (#2899); `## Quality Standards` above (`\u2297 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); [`patterns/goal-gate-determinism.md`](../patterns/goal-gate-determinism.md) (#852 \u2014 rigid goals/gates, flexible path); `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).\n\n## Calling LLM APIs (#481)\n\nWhen the project calls LLM APIs (OpenAI, Anthropic, Cohere, local models, etc.) or builds agentic functionality, the architectural standards in `patterns/llm-app.md` apply alongside the coding rules above. In the directive maintainer repo this section is **guidance for consumer projects** \u2014 provider names are illustrative labels under the framework instruction hierarchy, not runtime SDK surfaces (#2414; see `meta/security.md` `## Informational AppSec findings`). The short form:\n\n- ! User input is NEVER placed in the system prompt; the system prompt is the trust boundary\n- ! External content is ALWAYS wrapped in explicit delimiters (`<user_input>`, `<document>`, `<tool_result>`) and surfaces its trust tier\n- ! Tool call arguments are validated against a schema BEFORE execution (the LLM is a confused deputy)\n- ! LLM outputs are validated against expected schemas before being acted upon (no eval-of-output, no shell-of-output, no SQL-of-output)\n- \u2297 MUST NOT write LLM outputs back into the retrieval corpus in the same session without validation (RAG poisoning vector)\n\nSee [../patterns/llm-app.md](../patterns/llm-app.md) for the full standards: prompt construction, trust tiers, tool/function-call validation, RAG hygiene, output handling, multi-agent orchestration, and LLM-specific observability. See [../tools/telemetry.md](../tools/telemetry.md) `## LLM-specific observability (#481)` for the matching observability surface.\n\n## Debugging and Root-Cause Investigation (#1621)\n\nWhen a bug, failure, or unexpected behaviour needs diagnosis, the root-cause standards in `debugging.md` apply. The short form:\n\n- ! No fixes without root-cause investigation first (the Iron Law)\n- ! Reproduce the failure consistently before proposing a fix \u2014 a non-reproducible bug is not yet understood\n- ! Every factual claim cites evidence; an uncited claim is a `[HYPOTHESIS]`, not a finding (evidence before narrative)\n- ! Runtime/config values are proven from the runtime, never inferred from source code (config is not code)\n- \u2297 MUST NOT present a duration or an exit status (\"slow because phase X took N minutes\", \"failed because it timed out\") as a root cause \u2014 name a mechanism (no tautologies)\n- ! After 3 failed distinct fixes, STOP and escalate for architectural review (the 3-fix gate)\n\nSee [debugging.md](debugging.md) for the full four-phase process, evidence discipline, Fact vs Hypothesis labeling (#1580), the observability-gap loop, and the rationalization table. For a sustained multi-agent investigation posture, see the `deft-directive-debug` skill.\n\n## Build Automation\n\n**Taskfile:**\n- ! Use Task ([go-task](https://taskfile.dev)) for all repeatable operations\n- ! If `task` not found, attempt to install go-task\n- ! If installation fails, stop and ask user for help\n- See [../tools/taskfile.md](../tools/taskfile.md) for standards and common commands\n\n**Toolchain Validation:**\n- See [../coding/toolchain.md](../coding/toolchain.md) for rules on verifying required tools are installed before implementation begins\n\n**Build Output Validation:**\n- See [../coding/build-output.md](../coding/build-output.md) for rules on verifying `dist/` artifacts and non-compiled assets after custom build scripts run\n\n## Change Management\n\n**Impact Awareness:**\n- ! Before changing shared code, identify affected downstream modules/files\n- ~ Prefer additive changes (new functions, fields with defaults) over breaking renames\n- ! Make small, reversible changes\n- ! Explain impact and migration path for breaking changes\n\n**Production Safety:**\n- ! Assume production impact unless stated otherwise\n- ! Call out risk when touching: auth, billing, data, APIs, build systems\n- \u2297 Silent breaking behavior\n- ~ Test changes in staging/dev environment when possible\n\n## Language-Specific Guidelines\n\n**Languages:**\n- C++: [../languages/cpp.md](../languages/cpp.md)\n- Go: [../languages/go.md](../languages/go.md)\n- Office.js: [../languages/officejs.md](../languages/officejs.md)\n- Python: [../languages/python.md](../languages/python.md)\n- TypeScript: [../languages/typescript.md](../languages/typescript.md)\n- VBA: [../languages/vba.md](../languages/vba.md)\n\n**Interface Types:**\n- CLI: [../interfaces/cli.md](../interfaces/cli.md)\n- TUI: [../interfaces/tui.md](../interfaces/tui.md)\n- Web: [../interfaces/web.md](../interfaces/web.md)\n- REST API: [../interfaces/rest.md](../interfaces/rest.md)\n\n## Development Workflow\n\n**Localhost:**\n- No permission needed for curl localhost\n\n**Plans:**\n- ~ Create both:\n  1. Warp plan (using `create_plan` tool)\n  2. Archive copy in `history/plan-YYYY-MM-DD-description.md`\n\n## Project Context\n\n- ! Check [PROJECT.md](../../PROJECT.md) for project-specific overrides\n- ~ Inspect project config (package.json, pyproject.toml, etc.) for available scripts\n- ! Follow project-specific testing, coverage, and quality requirements\n\n## Anti-Patterns\n\n- \u2297 Secrets in code or version control\n- \u2297 Claiming checks passed without running them\n- \u2297 Single files mixing multiple responsibilities (line count at or above FILE_SIZE_REVIEW_TRIGGER_LINES is a cohesion review trigger \u2014 not a defect by itself; #1488 / #3424)\n- \u2297 Skipping quality checks\n- \u2297 Breaking changes without explicit approval\n- \u2297 Using `grep` command when `rg` or Warp grep available\n- \u2297 Implementing code without tests\n- \u2297 Claiming \"done\" before running test:coverage\n- \u2297 Ignoring coverage drops\n- \u2297 Weak types (`any`, `interface{}`, untyped `object`) where concrete types are knowable\n- \u2297 Dead code: unused functions, unreachable branches, stale feature flags, commented-out blocks\n- \u2297 Error hiding: empty catch blocks, silent fallbacks, swallowed exceptions\n- \u2297 Circular imports between modules\n- \u2297 Duplicate logic across 2+ call sites without shared abstraction\n- \u2297 Outcome-blind completion claims: \"tests pass\" with skipped tests, \"migration completed\" without per-record counts, \"feature works\" without naming the verified edge case (#1006 -- see `## Fail Loud` above)\n- \u2297 Outcome-blind \"feature complete\" / \"production-ready\" claims that ignore open graduations (`graduationRef`s) without naming them or an explicit skip (#2899 / #1006 -- see `## Fail Loud` above)\n- \u2297 Averaging contradicting codebase patterns: writing new code that satisfies both of two conflicting patterns simultaneously (#1005 -- see `hygiene.md` `## Surface Conflicts`)\n- \u2297 Debugging by guess-and-check: fixing before reproducing, treating the first plausible hypothesis as confirmed, or presenting a duration/exit-status as a root cause (#1621 -- see `debugging.md`)\n"
     },
     {
       "id": "coding-002",
@@ -151,7 +151,7 @@
       "id": "coding-012",
       "tier": "SHOULD",
       "domain": "coding",
-      "text": "Files <300 lines ideal; <500 lines recommended; <1000 lines a review trigger \u2014 split when exceeded unless genuinely single-responsibility (size is a smell, not a hard cap; #1488)",
+      "text": "Keep files small. Ideal, recommended, and review-trigger line counts are FILE_SIZE_IDEAL_LINES, FILE_SIZE_RECOMMENDED_LINES, and FILE_SIZE_REVIEW_TRIGGER_LINES in the file-size-thresholds policy module (packages/core/src/policy/file-size-thresholds.ts). Split when a file exceeds the review trigger unless it is genuinely single-responsibility (size is a smell, not a hard cap; #1488 / #3424)",
       "path": "coding/coding.md",
       "body": null
     },
@@ -775,7 +775,7 @@
       "id": "coding-090",
       "tier": "MUST_NOT",
       "domain": "coding",
-      "text": "Single files mixing multiple responsibilities (large line count, e.g. >1000 lines, is a trigger to check cohesion \u2014 not a defect by itself; #1488)",
+      "text": "Single files mixing multiple responsibilities (line count at or above FILE_SIZE_REVIEW_TRIGGER_LINES is a cohesion review trigger \u2014 not a defect by itself; #1488 / #3424)",
       "path": "coding/coding.md",
       "body": null
     },