@deftai/directive-content 0.75.0 → 0.77.0

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

@@ -9,7 +9,7 @@
       "domain": "build-output",
       "text": "After running a custom build script, verify expected output files exist and are non-empty",
       "path": "coding/build-output.md",
-      "body": "# Build Output Validation\n\nRules for validating build output artifacts after custom build scripts run.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also**:\n- [coding.md](../coding/coding.md) \u2014 Build Automation section\n- [testing.md](../coding/testing.md) \u2014 Build Output Tests section\n\n## Artifact Verification\n\n- ! After running a custom build script, verify expected output files exist and are non-empty\n- ! When a build script copies/transforms non-compiled assets (manifests, configs, extension metadata), verify those files are present and structurally valid in the output directory\n- ! A build that exits 0 but produces stale or incomplete artifacts is a silent failure \u2014 treat it as a build failure (#105)\n- ~ Verify required keys/fields are present in structured output files (JSON manifests, config files, etc.)\n- \u2297 Assume a zero-exit-code build produced correct output without checking\n\n## Smoke Tests\n\n- ~ Build scripts that produce `dist/` artifacts have a smoke test verifying expected output files exist and contain expected content\n- ~ See [testing.md](../coding/testing.md#build-output-tests) for test type guidance and examples\n"
+      "body": "# Build Output Validation\n\nRules for validating build output artifacts after custom build scripts run.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**:\n- [coding.md](../coding/coding.md) — Build Automation section\n- [testing.md](../coding/testing.md) — Build Output Tests section\n\n## Artifact Verification\n\n- ! After running a custom build script, verify expected output files exist and are non-empty\n- ! When a build script copies/transforms non-compiled assets (manifests, configs, extension metadata), verify those files are present and structurally valid in the output directory\n- ! A build that exits 0 but produces stale or incomplete artifacts is a silent failure — treat it as a build failure (#105)\n- ~ Verify required keys/fields are present in structured output files (JSON manifests, config files, etc.)\n- ⊗ Assume a zero-exit-code build produced correct output without checking\n\n## Smoke Tests\n\n- ~ Build scripts that produce `dist/` artifacts have a smoke test verifying expected output files exist and contain expected content\n- ~ See [testing.md](../coding/testing.md#build-output-tests) for test type guidance and examples\n"
     },
     {
       "id": "build-output-002",
@@ -23,7 +23,7 @@
       "id": "build-output-003",
       "tier": "MUST",
       "domain": "build-output",
-      "text": "A build that exits 0 but produces stale or incomplete artifacts is a silent failure \u2014 treat it as a build failure (#105)",
+      "text": "A build that exits 0 but produces stale or incomplete artifacts is a silent failure — treat it as a build failure (#105)",
       "path": "coding/build-output.md",
       "body": null
     },
@@ -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\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## 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, and agent-specific threats (#661)\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 (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\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:** `## 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); `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).\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. 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 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, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ 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\n**Filenames:**\n- ~ Use hyphens not underscores (unless language idiom)\n\n**Secrets:**\n- ! ALL secrets in `secrets/` dir as .env files\n- ⊗ 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 — 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- ⊗ Copy-paste logic with minor variations — parameterise instead\n\n**Dependency Direction:**\n- ⊗ 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- ⊗ 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- ⊗ Trust caller without validation\n- ⊗ Empty catch/except/recover blocks that swallow errors silently\n- ⊗ Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask errors — propagate explicitly\n- ⊗ 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- ⊗ Clever code over clear code\n\n## Quality Standards\n\n**General:**\n- ! Run all relevant checks (lint, fmt, quality, build, test) before submitting changes\n- ⊗ 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, and agent-specific threats (#661)\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 (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- ⊗ MUST NOT claim \"tests pass\" when any test was skipped, xfailed, or run with errors suppressed -- report the full counts instead\n- ⊗ MUST NOT claim \"migration completed\" / \"batch succeeded\" / \"job finished\" without checking and reporting the per-record outcome counts\n- ⊗ 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- ⊗ MUST NOT use successful-sounding completion phrasing to paper over uncertainty -- default to surfacing uncertainty, not hiding it\n- ⊗ 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\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:** `## 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).\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** — 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- ⊗ 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 — 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- ⊗ 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 — 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- ⊗ 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- ⊗ Secrets in code or version control\n- ⊗ Claiming checks passed without running them\n- ⊗ Single files mixing multiple responsibilities (large line count, e.g. >1000 lines, is a trigger to check cohesion — not a defect by itself; #1488)\n- ⊗ Skipping quality checks\n- ⊗ Breaking changes without explicit approval\n- ⊗ Using `grep` command when `rg` or Warp grep available\n- ⊗ Implementing code without tests\n- ⊗ Claiming \"done\" before running test:coverage\n- ⊗ Ignoring coverage drops\n- ⊗ Weak types (`any`, `interface{}`, untyped `object`) where concrete types are knowable\n- ⊗ Dead code: unused functions, unreachable branches, stale feature flags, commented-out blocks\n- ⊗ Error hiding: empty catch blocks, silent fallbacks, swallowed exceptions\n- ⊗ Circular imports between modules\n- ⊗ Duplicate logic across 2+ call sites without shared abstraction\n- ⊗ 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- ⊗ Averaging contradicting codebase patterns: writing new code that satisfies both of two conflicting patterns simultaneously (#1005 -- see `hygiene.md` `## Surface Conflicts`)\n- ⊗ 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",
@@ -143,7 +143,7 @@
       "id": "coding-011",
       "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": "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)",
       "path": "coding/coding.md",
       "body": null
     },
@@ -167,7 +167,7 @@
       "id": "coding-014",
       "tier": "MUST_NOT",
       "domain": "coding",
-      "text": "Copy-paste logic with minor variations \u2014 parameterise instead",
+      "text": "Copy-paste logic with minor variations — parameterise instead",
       "path": "coding/coding.md",
       "body": null
     },
@@ -287,7 +287,7 @@
       "id": "coding-029",
       "tier": "MUST_NOT",
       "domain": "coding",
-      "text": "Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask errors \u2014 propagate explicitly",
+      "text": "Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask errors — propagate explicitly",
       "path": "coding/coding.md",
       "body": null
     },
@@ -535,7 +535,7 @@
       "id": "coding-060",
       "tier": "MUST",
       "domain": "coding",
-      "text": "Reproduce the failure consistently before proposing a fix \u2014 a non-reproducible bug is not yet understood",
+      "text": "Reproduce the failure consistently before proposing a fix — a non-reproducible bug is not yet understood",
       "path": "coding/coding.md",
       "body": null
     },
@@ -559,7 +559,7 @@
       "id": "coding-063",
       "tier": "MUST_NOT",
       "domain": "coding",
-      "text": "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)",
+      "text": "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 — name a mechanism (no tautologies)",
       "path": "coding/coding.md",
       "body": null
     },
@@ -711,7 +711,7 @@
       "id": "coding-082",
       "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 (large line count, e.g. >1000 lines, is a trigger to check cohesion — not a defect by itself; #1488)",
       "path": "coding/coding.md",
       "body": null
     },
@@ -833,13 +833,13 @@
       "domain": "debugging",
       "text": "Before proposing or writing any fix, the root cause MUST be identified with evidence.",
       "path": "coding/debugging.md",
-      "body": "# Debugging and Root-Cause Investigation (#1621)\n\nSystematic root-cause process for AI agents. The failure mode this file prevents\nis **thrashing**: retrying random fixes, fixing before understanding, and\ntreating the first plausible hypothesis as correct. Debugging is an\nevidence-discipline, not a guess-and-check loop.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\nFor a sustained, multi-agent investigation posture (claim ledger, falsification\nwaves, validator gate), see the `deft-directive-debug` skill and the vendored\nreference design under `docs/reference/forensic-research/`.\n\n## The Iron Law\n\n```\nNO FIXES WITHOUT ROOT-CAUSE INVESTIGATION FIRST\n```\n\n- ! Before proposing or writing any fix, the root cause MUST be identified with evidence.\n- \u2297 MUST NOT propose a fix while the investigation phase is incomplete \u2014 violating the letter of this process is violating the spirit of debugging.\n\n## The Four Phases\n\nEach phase MUST complete before the next begins.\n\n### Phase 1 \u2014 Root-Cause Investigation\n- ! Read the error message completely before doing anything else.\n- ! Reproduce the failure consistently \u2014 a non-reproducible bug is not yet understood.\n- ! Check recent changes (what changed when the symptom appeared?).\n- ! Gather evidence at component boundaries \u2014 add diagnostic instrumentation before proposing fixes.\n- ! Trace data flow backward from the symptom toward the cause.\n\n### Phase 2 \u2014 Pattern Analysis\n- ! Find a working example of similar functionality in the codebase.\n- ! Compare the failing path against the working reference and identify what is structurally different.\n- ~ Look for the pattern, not just the instance.\n\n### Phase 3 \u2014 Hypothesis Testing\n- ! Form one hypothesis and test it minimally.\n- ! Change one variable at a time.\n- ! Confirm the fix addresses the root cause, not just the symptom.\n\n### Phase 4 \u2014 Implementation\n- ! Write a failing test that demonstrates the bug.\n- ! Implement the single fix.\n- ! Verify the test passes and that no regressions were introduced.\n\n## The 3-Fix Architecture Gate\n\n- ! If 3 or more distinct fixes have failed, STOP. MUST NOT attempt a fourth fix.\n- ! Escalate with: \"N fixes attempted, root cause not found \u2014 architectural review needed.\" The architecture may be the problem.\n\n## Multi-Component Systems\n\n- ! Before proposing fixes in a multi-component system, add diagnostic instrumentation at every boundary to observe the actual data flow.\n- \u2297 MUST NOT guess which component is at fault without boundary evidence.\n\n## Evidence Discipline (forensic rigor)\n\nThese rules raise the four-phase loop from \"structured guessing\" to\nevidence-based investigation. They are adapted from the vendored\n`forensic-research` reference design.\n\n- ! **Evidence before narrative** \u2014 every factual claim MUST cite specific evidence (a log line, a metric, a file:line, a reproduction). An uncited claim is a `[HYPOTHESIS]`, not a finding.\n- ! **Config is not code** \u2014 a production/runtime flag value MUST be proven from the runtime (env dump, secrets manager, a log line showing the actual value). \u2297 MUST NOT infer a runtime value from source code or docs alone.\n- ! **Proof-required disproval** \u2014 \"no evidence found\" resolves a theory to `unknown`, never to `failed`. Marking a theory `failed` (ruled out) MUST cite specific counter-evidence.\n- ! **Falsification before fixation** \u2014 before committing to a leading theory, MUST attempt the cheapest test that would disprove it. A theory that survives a real disproof attempt is stronger than one merely asserted.\n- \u2297 **No tautologies** \u2014 \"it failed because it timed out\" and \"it was slow because phase X took N minutes\" MUST NOT be presented as root causes. Name a **mechanism**, or state \"mechanism not verified\" after exhausting the cheap checks. A duration is evidence for the mechanism search, not the mechanism.\n\n## Fact vs Hypothesis Labeling\n\n- ! Every finding MUST be labeled **Fact** (an observable claim grounded in file:line / log / metric evidence) or **Hypothesis** (an interpretation that could be wrong and still needs verification).\n- ! A finding labeled Fact MUST carry its evidence citation.\n\nThis is the debugging-side adoption of the review/triage labeling vocabulary\nowned by #1580 \u2014 that issue remains the owner of the review-cycle and triage\nfindings-format surface; this file is a consumer of the shared vocabulary.\n\n## Observability Gaps (close the loop)\n\n- ! When the root cause was reached by **inference** (indirect evidence, missing telemetry), the investigation MUST emit an \"observability gaps\" note: what could not be measured, what to log/measure next time, and why it would make the next investigation definitive.\n- ~ Treat each investigation as an opportunity to improve the system's telemetry, not just to land a fix.\n\n## Rationalization Table\n\n| Excuse | Reality |\n|---|---|\n| \"This seems obvious\" | Obvious bugs have root causes too |\n| \"I'll investigate if this fix doesn't work\" | The first fix sets the pattern \u2014 investigate first |\n| \"We're under time pressure\" | Rushing guarantees rework; systematic is faster than thrashing |\n| \"One more fix attempt\" | 3+ failures = architectural problem; question the pattern |\n| \"No evidence, so it's not that\" | No evidence means `unknown`, not ruled out |\n\n## Anti-Patterns\n\n- \u2297 Fixing before reproducing the failure\n- \u2297 Cargo-cult debugging: changing things until it works, with no understanding of why\n- \u2297 Treating the first plausible hypothesis as confirmed without testing it\n- \u2297 Skipping Phase 2 because a fix seems obvious\n- \u2297 Presenting a duration or an exit status as a root cause (tautology)\n- \u2297 Inferring a runtime config value from source code instead of proving it at runtime\n- \u2297 Marking a theory \"ruled out\" without counter-evidence\n- \u2297 A fourth fix attempt after three have failed without an architectural review\n"
+      "body": "# Debugging and Root-Cause Investigation (#1621)\n\nSystematic root-cause process for AI agents. The failure mode this file prevents\nis **thrashing**: retrying random fixes, fixing before understanding, and\ntreating the first plausible hypothesis as correct. Debugging is an\nevidence-discipline, not a guess-and-check loop.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\nFor a sustained, multi-agent investigation posture (claim ledger, falsification\nwaves, validator gate), see the `deft-directive-debug` skill and the vendored\nreference design under `docs/reference/forensic-research/`.\n\n## The Iron Law\n\n```\nNO FIXES WITHOUT ROOT-CAUSE INVESTIGATION FIRST\n```\n\n- ! Before proposing or writing any fix, the root cause MUST be identified with evidence.\n- ⊗ MUST NOT propose a fix while the investigation phase is incomplete — violating the letter of this process is violating the spirit of debugging.\n\n## The Four Phases\n\nEach phase MUST complete before the next begins.\n\n### Phase 1 — Root-Cause Investigation\n- ! Read the error message completely before doing anything else.\n- ! Reproduce the failure consistently — a non-reproducible bug is not yet understood.\n- ! Check recent changes (what changed when the symptom appeared?).\n- ! Gather evidence at component boundaries — add diagnostic instrumentation before proposing fixes.\n- ! Trace data flow backward from the symptom toward the cause.\n\n### Phase 2 — Pattern Analysis\n- ! Find a working example of similar functionality in the codebase.\n- ! Compare the failing path against the working reference and identify what is structurally different.\n- ~ Look for the pattern, not just the instance.\n\n### Phase 3 — Hypothesis Testing\n- ! Form one hypothesis and test it minimally.\n- ! Change one variable at a time.\n- ! Confirm the fix addresses the root cause, not just the symptom.\n\n### Phase 4 — Implementation\n- ! Write a failing test that demonstrates the bug.\n- ! Implement the single fix.\n- ! Verify the test passes and that no regressions were introduced.\n\n## The 3-Fix Architecture Gate\n\n- ! If 3 or more distinct fixes have failed, STOP. MUST NOT attempt a fourth fix.\n- ! Escalate with: \"N fixes attempted, root cause not found — architectural review needed.\" The architecture may be the problem.\n\n## Multi-Component Systems\n\n- ! Before proposing fixes in a multi-component system, add diagnostic instrumentation at every boundary to observe the actual data flow.\n- ⊗ MUST NOT guess which component is at fault without boundary evidence.\n\n## Evidence Discipline (forensic rigor)\n\nThese rules raise the four-phase loop from \"structured guessing\" to\nevidence-based investigation. They are adapted from the vendored\n`forensic-research` reference design.\n\n- ! **Evidence before narrative** — every factual claim MUST cite specific evidence (a log line, a metric, a file:line, a reproduction). An uncited claim is a `[HYPOTHESIS]`, not a finding.\n- ! **Config is not code** — a production/runtime flag value MUST be proven from the runtime (env dump, secrets manager, a log line showing the actual value). ⊗ MUST NOT infer a runtime value from source code or docs alone.\n- ! **Proof-required disproval** — \"no evidence found\" resolves a theory to `unknown`, never to `failed`. Marking a theory `failed` (ruled out) MUST cite specific counter-evidence.\n- ! **Falsification before fixation** — before committing to a leading theory, MUST attempt the cheapest test that would disprove it. A theory that survives a real disproof attempt is stronger than one merely asserted.\n- ⊗ **No tautologies** — \"it failed because it timed out\" and \"it was slow because phase X took N minutes\" MUST NOT be presented as root causes. Name a **mechanism**, or state \"mechanism not verified\" after exhausting the cheap checks. A duration is evidence for the mechanism search, not the mechanism.\n\n## Fact vs Hypothesis Labeling\n\n- ! Every finding MUST be labeled **Fact** (an observable claim grounded in file:line / log / metric evidence) or **Hypothesis** (an interpretation that could be wrong and still needs verification).\n- ! A finding labeled Fact MUST carry its evidence citation.\n\nThis is the debugging-side adoption of the review/triage labeling vocabulary\nowned by #1580 — that issue remains the owner of the review-cycle and triage\nfindings-format surface; this file is a consumer of the shared vocabulary.\n\n## Observability Gaps (close the loop)\n\n- ! When the root cause was reached by **inference** (indirect evidence, missing telemetry), the investigation MUST emit an \"observability gaps\" note: what could not be measured, what to log/measure next time, and why it would make the next investigation definitive.\n- ~ Treat each investigation as an opportunity to improve the system's telemetry, not just to land a fix.\n\n## Rationalization Table\n\n| Excuse | Reality |\n|---|---|\n| \"This seems obvious\" | Obvious bugs have root causes too |\n| \"I'll investigate if this fix doesn't work\" | The first fix sets the pattern — investigate first |\n| \"We're under time pressure\" | Rushing guarantees rework; systematic is faster than thrashing |\n| \"One more fix attempt\" | 3+ failures = architectural problem; question the pattern |\n| \"No evidence, so it's not that\" | No evidence means `unknown`, not ruled out |\n\n## Anti-Patterns\n\n- ⊗ Fixing before reproducing the failure\n- ⊗ Cargo-cult debugging: changing things until it works, with no understanding of why\n- ⊗ Treating the first plausible hypothesis as confirmed without testing it\n- ⊗ Skipping Phase 2 because a fix seems obvious\n- ⊗ Presenting a duration or an exit status as a root cause (tautology)\n- ⊗ Inferring a runtime config value from source code instead of proving it at runtime\n- ⊗ Marking a theory \"ruled out\" without counter-evidence\n- ⊗ A fourth fix attempt after three have failed without an architectural review\n"
     },
     {
       "id": "debugging-002",
       "tier": "MUST_NOT",
       "domain": "debugging",
-      "text": "MUST NOT propose a fix while the investigation phase is incomplete \u2014 violating the letter of this process is violating the spirit of debugging.",
+      "text": "MUST NOT propose a fix while the investigation phase is incomplete — violating the letter of this process is violating the spirit of debugging.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -855,7 +855,7 @@
       "id": "debugging-004",
       "tier": "MUST",
       "domain": "debugging",
-      "text": "Reproduce the failure consistently \u2014 a non-reproducible bug is not yet understood.",
+      "text": "Reproduce the failure consistently — a non-reproducible bug is not yet understood.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -871,7 +871,7 @@
       "id": "debugging-006",
       "tier": "MUST",
       "domain": "debugging",
-      "text": "Gather evidence at component boundaries \u2014 add diagnostic instrumentation before proposing fixes.",
+      "text": "Gather evidence at component boundaries — add diagnostic instrumentation before proposing fixes.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -967,7 +967,7 @@
       "id": "debugging-018",
       "tier": "MUST",
       "domain": "debugging",
-      "text": "Escalate with: \"N fixes attempted, root cause not found \u2014 architectural review needed.\" The architecture may be the problem.",
+      "text": "Escalate with: \"N fixes attempted, root cause not found — architectural review needed.\" The architecture may be the problem.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -991,7 +991,7 @@
       "id": "debugging-021",
       "tier": "MUST",
       "domain": "debugging",
-      "text": "**Evidence before narrative** \u2014 every factual claim MUST cite specific evidence (a log line, a metric, a file:line, a reproduction). An uncited claim is a `[HYPOTHESIS]`, not a finding.",
+      "text": "**Evidence before narrative** — every factual claim MUST cite specific evidence (a log line, a metric, a file:line, a reproduction). An uncited claim is a `[HYPOTHESIS]`, not a finding.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -999,7 +999,7 @@
       "id": "debugging-022",
       "tier": "MUST",
       "domain": "debugging",
-      "text": "**Config is not code** \u2014 a production/runtime flag value MUST be proven from the runtime (env dump, secrets manager, a log line showing the actual value). \u2297 MUST NOT infer a runtime value from source code or docs alone.",
+      "text": "**Config is not code** — a production/runtime flag value MUST be proven from the runtime (env dump, secrets manager, a log line showing the actual value). ⊗ MUST NOT infer a runtime value from source code or docs alone.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -1007,7 +1007,7 @@
       "id": "debugging-023",
       "tier": "MUST",
       "domain": "debugging",
-      "text": "**Proof-required disproval** \u2014 \"no evidence found\" resolves a theory to `unknown`, never to `failed`. Marking a theory `failed` (ruled out) MUST cite specific counter-evidence.",
+      "text": "**Proof-required disproval** — \"no evidence found\" resolves a theory to `unknown`, never to `failed`. Marking a theory `failed` (ruled out) MUST cite specific counter-evidence.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -1015,7 +1015,7 @@
       "id": "debugging-024",
       "tier": "MUST",
       "domain": "debugging",
-      "text": "**Falsification before fixation** \u2014 before committing to a leading theory, MUST attempt the cheapest test that would disprove it. A theory that survives a real disproof attempt is stronger than one merely asserted.",
+      "text": "**Falsification before fixation** — before committing to a leading theory, MUST attempt the cheapest test that would disprove it. A theory that survives a real disproof attempt is stronger than one merely asserted.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -1023,7 +1023,7 @@
       "id": "debugging-025",
       "tier": "MUST_NOT",
       "domain": "debugging",
-      "text": "**No tautologies** \u2014 \"it failed because it timed out\" and \"it was slow because phase X took N minutes\" MUST NOT be presented as root causes. Name a **mechanism**, or state \"mechanism not verified\" after exhausting the cheap checks. A duration is evidence for the mechanism search, not the mechanism.",
+      "text": "**No tautologies** — \"it failed because it timed out\" and \"it was slow because phase X took N minutes\" MUST NOT be presented as root causes. Name a **mechanism**, or state \"mechanism not verified\" after exhausting the cheap checks. A duration is evidence for the mechanism search, not the mechanism.",
       "path": "coding/debugging.md",
       "body": null
     },
@@ -1129,7 +1129,7 @@
       "domain": "holzmann",
       "text": "These rules MUST be understood as the canonical high-assurance reference for Deft.",
       "path": "coding/holzmann.md",
-      "body": "# Power of Ten \u2013 Adapted for Deft  \nJPL/NASA-inspired rules for reliable, verifiable code  \n(Original: Gerard J. Holzmann, \"The Power of Ten \u2013 Rules for Developing Safety-Critical Code\", IEEE Computer, June 2006)\n\n**\u26a0\ufe0f See also** (load only when needed):\n- [coding.md](coding.md) - General coding guidelines\n- [../verification/verification.md](../verification/verification.md) - Verification practices (Holzmann ladder)\n\n! These rules MUST be understood as the canonical high-assurance reference for Deft.\n~ Apply the general intent across all languages.  \n~ Put language-specific enforcement, tooling, and exceptions only in languages/*.md files.\n\n## Notation Legend (Deft RFC 2119 compact style)\n! = MUST (required, mandatory)  \n~ = SHOULD (recommended, strong preference)  \n\u2249 = SHOULD NOT (discouraged, avoid unless justified)  \n\u2297 = MUST NOT (forbidden, never do this)\n? = MAY \n\n## The Adapted Rules\n\n1. Simple control flow  \n   \u2297 Use direct or indirect recursion\n   ~ Use explicit iteration or stacks instead.\n   \u2297 Exotic/non-local jumps (goto where supported, longjmp equivalents, setjmp). \n   ~ Restrict control flow to basic constructs: if/else, bounded for/while, switch/case/match.  \n   ! Keep code analyzable and provably terminating where possible.\n\n2. Bounded loops  \n   ! Every loop MUST have a statically provable fixed upper bound or mechanically verifiable termination condition.  \n   \u2297 Naked infinite loops (while True:, for {} without escape guarantee) are forbidden.  \n   ~ Prefer for i in range(MAX) / for i := 0; i < MAX; i++ {} patterns wherever practical.  \n   ! Termination guarantee MUST be preserved in all loops.\n\n3. Fixed resource allocation after initialization  \n   ~ Allocate/grow dynamic structures (lists, maps, slices, heaps) during startup/initialization phase only.  \n   \u2249 Grow structures (append, map inserts, slice appends) in hot paths or long-running loops unless bounded.  \n   \u2297 Unbounded dynamic allocation/growth in steady-state operation is forbidden (where language-relevant).  \n   ! Resource usage MUST remain predictable after initialization.\n\n4. Small functions  \n   ~ Functions SHOULD be \u2264 40\u201360 lines (aim for one screen / printed page).\n   ~ Cyclomatic complexity SHOULD be \u2264 10 per function.  \n   ! Small, focused functions MUST be preferred for verifiability and reviewability.\n\n5. Runtime checks & assertions  \n   ~ Every non-trivial function SHOULD include at least two explicit runtime checks/assertions.\n   ~ Use preconditions, postconditions, or invariants via language-native mechanisms.  \n   ! Runtime checks MUST catch violations early in non-trivial logic.\n\n6. Minimal data scope  \n   ! Mutable shared/global state MUST be minimized \u2014 prefer local, passed, or immutable data.  \n   \u2297 Unnecessary module/package-level mutable variables (except constants) are forbidden.  \n   ~ Dependency injection or functional style SHOULD be used where practical.  \n   ! Scope reduction MUST reduce coupling and side effects.\n\n7. Error & return checking  \n   ! Non-void return values and error indicators MUST never be ignored.  \n   ! In error-returning languages every error MUST be checked or explicitly propagated.  \n   \u2297 Silent failure / ignored exceptions are forbidden unless explicitly documented as safe.  \n   ! Explicit error handling MUST be enforced.\n\n8. Restricted metaprogramming  \n   \u2297 Complex/multi-level macros or preprocessor abuse are forbidden (C/C++).  \n   \u2249 Heavy decorators, metaclasses, or code generation that obscures control flow SHOULD be avoided.  \n   ~ Metaprogramming SHOULD remain minimal and local in safety-critical paths.\n   ! Analyzability MUST be preserved; metaprogramming MUST NOT obscure control flow.\n\n9. Restricted indirection  \n   \u2297 Multi-level pointers / double indirection are forbidden (C/C++ raw pointers).  \n   \u2249 Deep pointer chains or excessive indirection SHOULD be avoided in other languages.  \n   ~ Prefer slices, references, or owned types (Rust, Go).  \n   ! Indirection MUST be kept simple to reduce aliasing risk.\n\n10. Maximum static checking  \n    ! Compile/lint with maximum warnings enabled and treat warnings as errors.  \n    ! Strictest static analysis tools available for the language MUST be used.  \n    ! Static checking MUST catch issues at build time.\n\n## Additional Holzmann-inspired Practices\n~ Lightweight, interactive analysis tools SHOULD be preferred (Cobra philosophy).  \n~ Consider adding task cobra target for repo-wide queries (functions >40 lines, unbounded loops).  \n! Verification ladder MUST integrate with verification/ practices.  \n~ Every significant PR SHOULD include a short verifiability note.\n\n## References\n~ Original paper: https://spinroot.com/gerard/pdf/P10.pdf  \n~ Holzmann's SPIN model checker: https://spinroot.com\n\n! This adaptation preserves JPL flight-software reliability philosophy for Deft's layered system.\n"
+      "body": "# Power of Ten – Adapted for Deft  \nJPL/NASA-inspired rules for reliable, verifiable code  \n(Original: Gerard J. Holzmann, \"The Power of Ten – Rules for Developing Safety-Critical Code\", IEEE Computer, June 2006)\n\n**⚠️ See also** (load only when needed):\n- [coding.md](coding.md) - General coding guidelines\n- [../verification/verification.md](../verification/verification.md) - Verification practices (Holzmann ladder)\n\n! These rules MUST be understood as the canonical high-assurance reference for Deft.\n~ Apply the general intent across all languages.  \n~ Put language-specific enforcement, tooling, and exceptions only in languages/*.md files.\n\n## Notation Legend (Deft RFC 2119 compact style)\n! = MUST (required, mandatory)  \n~ = SHOULD (recommended, strong preference)  \n≉ = SHOULD NOT (discouraged, avoid unless justified)  \n⊗ = MUST NOT (forbidden, never do this)\n? = MAY \n\n## The Adapted Rules\n\n1. Simple control flow  \n   ⊗ Use direct or indirect recursion\n   ~ Use explicit iteration or stacks instead.\n   ⊗ Exotic/non-local jumps (goto where supported, longjmp equivalents, setjmp). \n   ~ Restrict control flow to basic constructs: if/else, bounded for/while, switch/case/match.  \n   ! Keep code analyzable and provably terminating where possible.\n\n2. Bounded loops  \n   ! Every loop MUST have a statically provable fixed upper bound or mechanically verifiable termination condition.  \n   ⊗ Naked infinite loops (while True:, for {} without escape guarantee) are forbidden.  \n   ~ Prefer for i in range(MAX) / for i := 0; i < MAX; i++ {} patterns wherever practical.  \n   ! Termination guarantee MUST be preserved in all loops.\n\n3. Fixed resource allocation after initialization  \n   ~ Allocate/grow dynamic structures (lists, maps, slices, heaps) during startup/initialization phase only.  \n   ≉ Grow structures (append, map inserts, slice appends) in hot paths or long-running loops unless bounded.  \n   ⊗ Unbounded dynamic allocation/growth in steady-state operation is forbidden (where language-relevant).  \n   ! Resource usage MUST remain predictable after initialization.\n\n4. Small functions  \n   ~ Functions SHOULD be ≤ 40–60 lines (aim for one screen / printed page).\n   ~ Cyclomatic complexity SHOULD be ≤ 10 per function.  \n   ! Small, focused functions MUST be preferred for verifiability and reviewability.\n\n5. Runtime checks & assertions  \n   ~ Every non-trivial function SHOULD include at least two explicit runtime checks/assertions.\n   ~ Use preconditions, postconditions, or invariants via language-native mechanisms.  \n   ! Runtime checks MUST catch violations early in non-trivial logic.\n\n6. Minimal data scope  \n   ! Mutable shared/global state MUST be minimized — prefer local, passed, or immutable data.  \n   ⊗ Unnecessary module/package-level mutable variables (except constants) are forbidden.  \n   ~ Dependency injection or functional style SHOULD be used where practical.  \n   ! Scope reduction MUST reduce coupling and side effects.\n\n7. Error & return checking  \n   ! Non-void return values and error indicators MUST never be ignored.  \n   ! In error-returning languages every error MUST be checked or explicitly propagated.  \n   ⊗ Silent failure / ignored exceptions are forbidden unless explicitly documented as safe.  \n   ! Explicit error handling MUST be enforced.\n\n8. Restricted metaprogramming  \n   ⊗ Complex/multi-level macros or preprocessor abuse are forbidden (C/C++).  \n   ≉ Heavy decorators, metaclasses, or code generation that obscures control flow SHOULD be avoided.  \n   ~ Metaprogramming SHOULD remain minimal and local in safety-critical paths.\n   ! Analyzability MUST be preserved; metaprogramming MUST NOT obscure control flow.\n\n9. Restricted indirection  \n   ⊗ Multi-level pointers / double indirection are forbidden (C/C++ raw pointers).  \n   ≉ Deep pointer chains or excessive indirection SHOULD be avoided in other languages.  \n   ~ Prefer slices, references, or owned types (Rust, Go).  \n   ! Indirection MUST be kept simple to reduce aliasing risk.\n\n10. Maximum static checking  \n    ! Compile/lint with maximum warnings enabled and treat warnings as errors.  \n    ! Strictest static analysis tools available for the language MUST be used.  \n    ! Static checking MUST catch issues at build time.\n\n## Additional Holzmann-inspired Practices\n~ Lightweight, interactive analysis tools SHOULD be preferred (Cobra philosophy).  \n~ Consider adding task cobra target for repo-wide queries (functions >40 lines, unbounded loops).  \n! Verification ladder MUST integrate with verification/ practices.  \n~ Every significant PR SHOULD include a short verifiability note.\n\n## References\n~ Original paper: https://spinroot.com/gerard/pdf/P10.pdf  \n~ Holzmann's SPIN model checker: https://spinroot.com\n\n! This adaptation preserves JPL flight-software reliability philosophy for Deft's layered system.\n"
     },
     {
       "id": "holzmann-002",
@@ -1295,7 +1295,7 @@
       "id": "holzmann-022",
       "tier": "SHOULD",
       "domain": "holzmann",
-      "text": "Functions SHOULD be \u2264 40\u201360 lines (aim for one screen / printed page).",
+      "text": "Functions SHOULD be ≤ 40–60 lines (aim for one screen / printed page).",
       "path": "coding/holzmann.md",
       "body": null
     },
@@ -1303,7 +1303,7 @@
       "id": "holzmann-023",
       "tier": "SHOULD",
       "domain": "holzmann",
-      "text": "Cyclomatic complexity SHOULD be \u2264 10 per function.",
+      "text": "Cyclomatic complexity SHOULD be ≤ 10 per function.",
       "path": "coding/holzmann.md",
       "body": null
     },
@@ -1343,7 +1343,7 @@
       "id": "holzmann-028",
       "tier": "MUST",
       "domain": "holzmann",
-      "text": "Mutable shared/global state MUST be minimized \u2014 prefer local, passed, or immutable data.",
+      "text": "Mutable shared/global state MUST be minimized — prefer local, passed, or immutable data.",
       "path": "coding/holzmann.md",
       "body": null
     },
@@ -1553,13 +1553,13 @@
       "domain": "hygiene",
       "text": "Before marking any refactor or cleanup task done, verify no unreferenced code was left behind",
       "path": "coding/hygiene.md",
-      "body": "# Codebase Hygiene\n\nRules for ongoing codebase health \u2014 keeping existing code clean, not just writing new code well.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also**:\n- [coding.md](coding.md) \u2014 Code design principles\n- [verification/verification.md](../verification/verification.md) \u2014 Stub and legacy detection\n- [coding/testing.md](testing.md) \u2014 Test coverage requirements\n\n---\n\n## Dead Code Removal\n\nDead code accumulates silently and degrades readability and maintainability.\n\n- ! Before marking any refactor or cleanup task done, verify no unreferenced code was left behind\n- \u2297 Commented-out code blocks committed to version control \u2014 delete, don't comment out\n- \u2297 Functions, classes, or variables that are defined but never called/imported anywhere\n- \u2297 Unused imports, dependencies, or exports\n- ~ Use language-specific dead code tools as part of periodic hygiene passes:\n  - Python: `vulture` \u2014 detects unused functions, classes, variables\n  - Go: `deadcode` (golang.org/x/tools/cmd/deadcode) or `staticcheck` unused analysis\n  - TypeScript/JS: `knip` \u2014 detects unused exports, files, and dependencies\n- ~ Run dead code tools before major releases or after significant refactors\n- ? Add dead code tool as a Taskfile target (e.g. `task hygiene`) for periodic use\n\n---\n\n## Circular Dependencies\n\nCircular imports create tight coupling, prevent modular testing, and indicate architectural problems.\n\n- \u2297 Circular imports between modules/packages \u2014 detect and eliminate\n- ! When circular dependency exists, resolve by extracting shared types/interfaces to a lower-level module, not by restructuring import order\n- ~ Enforce layered architecture: high-level modules depend on low-level ones, never the reverse\n- ! Use dependency inversion (interfaces/protocols) to break necessary coupling across layers\n- ~ Use language-specific tools to detect cycles:\n  - Python: `pydeps` or `importlab` for full cycle detection\n  - Go: the compiler rejects import cycles \u2014 trust the error; fix by extracting shared packages\n  - TypeScript/JS: `madge` \u2014 visualises and detects circular dependencies\n- ~ For large codebases, add `madge --circular --exit-code` (or equivalent) as a CI check\n\n---\n\n## Error Handling: No Hiding\n\nTry/catch and equivalent constructs serve a legitimate purpose at **API/input boundaries** \u2014 sanitizing unknown or untrusted input. Everywhere else, they should propagate errors explicitly.\n\n**Legitimate uses:**\n- Parsing external input (JSON, user input, file content)\n- Third-party SDK calls that may throw undocumented errors\n- Top-level process handlers (recover from unexpected crashes with logging)\n\n**Illegitimate uses (remove these):**\n\n- \u2297 Empty catch/except/recover blocks that swallow errors silently\n- \u2297 `except Exception: pass` or equivalent \u2014 log at minimum, re-raise if appropriate\n- \u2297 Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask an error \u2014 propagate explicitly\n- \u2297 Log-and-continue: catching an error, logging it, and proceeding as if nothing happened \u2014 unless the error is provably non-fatal AND that decision is documented in a comment\n- \u2297 Fallback patterns that hide failures from callers (e.g. \"if this fails, return cached/stale data\" without surfacing the error)\n- ! When removing a try/catch, confirm the error propagates to a caller that can handle it \u2014 do not simply delete\n\n---\n\n## Legacy and Deprecated Code\n\nLegacy accumulation makes codebases fragile and hard to reason about. Code should have one active path, not a graveyard of old approaches alongside new ones.\n\n- \u2297 Parallel implementations: old approach and new approach coexisting without a migration path\n- \u2297 Feature flags or toggle branches where the flag is always-on or always-off \u2014 collapse to the live path\n- \u2297 Compatibility shims maintained beyond their stated removal date\n- ! When replacing an implementation: delete the old one in the same commit, not \"after testing\"\n- ~ Scan for these markers as legacy indicators:\n  - Comments: `# deprecated`, `// TODO: remove`, `LEGACY`, `COMPAT`, `OLD_`, `# old way`\n  - Python decorators: `@deprecated`\n  - Go: `// Deprecated:` godoc marker (legitimate when part of a public API \u2014 remove the symbol if internal)\n- ~ When encountering legacy code during unrelated work, file a hygiene task rather than ignoring it\n- \u2297 Comments describing in-flight replacement work (\"this used to be X, now it's Y\") \u2014 remove once the migration is complete; they are noise for future readers\n\n---\n\n## Surface Conflicts: Pick One, Explain, Flag the Other (#1005)\n\nWhen two existing patterns in the codebase contradict each other (error-handling shapes, state-management approaches, naming conventions, component patterns, test structure, API-shape conventions), the path of least resistance is to write new code that satisfies BOTH simultaneously. The result is doubled logic (two error handlers, two validation paths), incoherent behaviour at the seam where both patterns interact, and a future agent facing the same two-pattern conflict and averaging again. **\"Average\" code that satisfies both contradicting rules is the worst code.**\n\n- ! When two existing patterns in the codebase contradict, MUST pick ONE -- prefer the more recent OR the more tested -- and write new code against that pattern only\n- ! MUST explain the choice in the commit message, PR body, or an inline comment near the new code (one sentence -- which pattern was chosen, which was dropped, why)\n- ! MUST flag the dropped pattern as deprecated for cleanup: either (a) file a follow-up GitHub issue and reference its number, or (b) add a `# deprecated: see <ref>` / `// Deprecated: see <ref>` marker on the dropped pattern in the same PR so the legacy-code rules above pick it up on the next hygiene pass\n- \u2297 MUST NOT blend the two patterns -- doubled error handlers, dual validation paths, parallel state stores, or any other \"satisfy both\" shape\n- \u2297 MUST NOT silently choose one pattern without recording the choice -- a future agent must be able to read the commit / PR / comment and understand why this code does not match the other pattern they see elsewhere\n- ? Exception: if the contradiction is INTENTIONAL (e.g. legacy path maintained for backward compat, gradual migration in flight), MUST document that explicitly (`# kept for v1 compat -- removal tracked in #NNN`) rather than flagging for cleanup\n\nThis applies across: error handling, state management, naming conventions, component patterns, test structure, API-shape conventions, dependency-injection styles, configuration-loading patterns, and any other surface where contradicting patterns can accumulate over a codebase's lifetime.\n\n**Cross-references:** sibling rule `## Legacy and Deprecated Code` above (the dropped pattern lands under those rules once flagged); `coding/coding.md` `## Code Design` (the modularity rules that govern the kept pattern); `skills/deft-directive-build/SKILL.md` Step 1 (the build skill applies this rule when it encounters contradicting patterns during a brownfield implementation).\n\n---\n\n## DRY: Don't Repeat Yourself\n\nDuplication is the root cause of inconsistent behaviour and maintenance burden.\n\n- ~ Extract shared abstractions when logic is duplicated across 2+ call sites\n- \u2297 Copy-paste logic with minor variations \u2014 parameterise instead\n- ! When deduplicating, verify the abstraction is actually shared behaviour, not coincidental similarity\n- \u2249 Premature abstraction \u2014 only extract when the duplication is real and the shared contract is clear\n\n---\n\n## Comments: Signal vs. Noise\n\nComments should explain **why**, not **what**. Remove noise; keep signal.\n\n- \u2297 Comments describing what the code does (the code itself shows this)\n- \u2297 In-motion commentary: \"replaced X with Y\", \"temporarily disabled\", \"new approach below\"\n- \u2297 Commented-out code \u2014 delete it; version control preserves history\n- \u2297 Section dividers and banners that add no information (e.g. `# --- helpers ---`)\n- ! When editing a file, remove stale comments as you go \u2014 do not leave them for later\n- ~ When a comment is needed, be concise: one line explaining the non-obvious reason, not a paragraph\n"
+      "body": "# Codebase Hygiene\n\nRules for ongoing codebase health — keeping existing code clean, not just writing new code well.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**:\n- [coding.md](coding.md) — Code design principles\n- [verification/verification.md](../verification/verification.md) — Stub and legacy detection\n- [coding/testing.md](testing.md) — Test coverage requirements\n\n---\n\n## Dead Code Removal\n\nDead code accumulates silently and degrades readability and maintainability.\n\n- ! Before marking any refactor or cleanup task done, verify no unreferenced code was left behind\n- ⊗ Commented-out code blocks committed to version control — delete, don't comment out\n- ⊗ Functions, classes, or variables that are defined but never called/imported anywhere\n- ⊗ Unused imports, dependencies, or exports\n- ~ Use language-specific dead code tools as part of periodic hygiene passes:\n  - Python: `vulture` — detects unused functions, classes, variables\n  - Go: `deadcode` (golang.org/x/tools/cmd/deadcode) or `staticcheck` unused analysis\n  - TypeScript/JS: `knip` — detects unused exports, files, and dependencies\n- ~ Run dead code tools before major releases or after significant refactors\n- ? Add dead code tool as a Taskfile target (e.g. `task hygiene`) for periodic use\n\n---\n\n## Circular Dependencies\n\nCircular imports create tight coupling, prevent modular testing, and indicate architectural problems.\n\n- ⊗ Circular imports between modules/packages — detect and eliminate\n- ! When circular dependency exists, resolve by extracting shared types/interfaces to a lower-level module, not by restructuring import order\n- ~ Enforce layered architecture: high-level modules depend on low-level ones, never the reverse\n- ! Use dependency inversion (interfaces/protocols) to break necessary coupling across layers\n- ~ Use language-specific tools to detect cycles:\n  - Python: `pydeps` or `importlab` for full cycle detection\n  - Go: the compiler rejects import cycles — trust the error; fix by extracting shared packages\n  - TypeScript/JS: `madge` — visualises and detects circular dependencies\n- ~ For large codebases, add `madge --circular --exit-code` (or equivalent) as a CI check\n\n---\n\n## Error Handling: No Hiding\n\nTry/catch and equivalent constructs serve a legitimate purpose at **API/input boundaries** — sanitizing unknown or untrusted input. Everywhere else, they should propagate errors explicitly.\n\n**Legitimate uses:**\n- Parsing external input (JSON, user input, file content)\n- Third-party SDK calls that may throw undocumented errors\n- Top-level process handlers (recover from unexpected crashes with logging)\n\n**Illegitimate uses (remove these):**\n\n- ⊗ Empty catch/except/recover blocks that swallow errors silently\n- ⊗ `except Exception: pass` or equivalent — log at minimum, re-raise if appropriate\n- ⊗ Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask an error — propagate explicitly\n- ⊗ Log-and-continue: catching an error, logging it, and proceeding as if nothing happened — unless the error is provably non-fatal AND that decision is documented in a comment\n- ⊗ Fallback patterns that hide failures from callers (e.g. \"if this fails, return cached/stale data\" without surfacing the error)\n- ! When removing a try/catch, confirm the error propagates to a caller that can handle it — do not simply delete\n\n---\n\n## Legacy and Deprecated Code\n\nLegacy accumulation makes codebases fragile and hard to reason about. Code should have one active path, not a graveyard of old approaches alongside new ones.\n\n- ⊗ Parallel implementations: old approach and new approach coexisting without a migration path\n- ⊗ Feature flags or toggle branches where the flag is always-on or always-off — collapse to the live path\n- ⊗ Compatibility shims maintained beyond their stated removal date\n- ! When replacing an implementation: delete the old one in the same commit, not \"after testing\"\n- ~ Scan for these markers as legacy indicators:\n  - Comments: `# deprecated`, `// TODO: remove`, `LEGACY`, `COMPAT`, `OLD_`, `# old way`\n  - Python decorators: `@deprecated`\n  - Go: `// Deprecated:` godoc marker (legitimate when part of a public API — remove the symbol if internal)\n- ~ When encountering legacy code during unrelated work, file a hygiene task rather than ignoring it\n- ⊗ Comments describing in-flight replacement work (\"this used to be X, now it's Y\") — remove once the migration is complete; they are noise for future readers\n\n---\n\n## Surface Conflicts: Pick One, Explain, Flag the Other (#1005)\n\nWhen two existing patterns in the codebase contradict each other (error-handling shapes, state-management approaches, naming conventions, component patterns, test structure, API-shape conventions), the path of least resistance is to write new code that satisfies BOTH simultaneously. The result is doubled logic (two error handlers, two validation paths), incoherent behaviour at the seam where both patterns interact, and a future agent facing the same two-pattern conflict and averaging again. **\"Average\" code that satisfies both contradicting rules is the worst code.**\n\n- ! When two existing patterns in the codebase contradict, MUST pick ONE -- prefer the more recent OR the more tested -- and write new code against that pattern only\n- ! MUST explain the choice in the commit message, PR body, or an inline comment near the new code (one sentence -- which pattern was chosen, which was dropped, why)\n- ! MUST flag the dropped pattern as deprecated for cleanup: either (a) file a follow-up GitHub issue and reference its number, or (b) add a `# deprecated: see <ref>` / `// Deprecated: see <ref>` marker on the dropped pattern in the same PR so the legacy-code rules above pick it up on the next hygiene pass\n- ⊗ MUST NOT blend the two patterns -- doubled error handlers, dual validation paths, parallel state stores, or any other \"satisfy both\" shape\n- ⊗ MUST NOT silently choose one pattern without recording the choice -- a future agent must be able to read the commit / PR / comment and understand why this code does not match the other pattern they see elsewhere\n- ? Exception: if the contradiction is INTENTIONAL (e.g. legacy path maintained for backward compat, gradual migration in flight), MUST document that explicitly (`# kept for v1 compat -- removal tracked in #NNN`) rather than flagging for cleanup\n\nThis applies across: error handling, state management, naming conventions, component patterns, test structure, API-shape conventions, dependency-injection styles, configuration-loading patterns, and any other surface where contradicting patterns can accumulate over a codebase's lifetime.\n\n**Cross-references:** sibling rule `## Legacy and Deprecated Code` above (the dropped pattern lands under those rules once flagged); `coding/coding.md` `## Code Design` (the modularity rules that govern the kept pattern); `skills/deft-directive-build/SKILL.md` Step 1 (the build skill applies this rule when it encounters contradicting patterns during a brownfield implementation).\n\n---\n\n## DRY: Don't Repeat Yourself\n\nDuplication is the root cause of inconsistent behaviour and maintenance burden.\n\n- ~ Extract shared abstractions when logic is duplicated across 2+ call sites\n- ⊗ Copy-paste logic with minor variations — parameterise instead\n- ! When deduplicating, verify the abstraction is actually shared behaviour, not coincidental similarity\n- ≉ Premature abstraction — only extract when the duplication is real and the shared contract is clear\n\n---\n\n## Comments: Signal vs. Noise\n\nComments should explain **why**, not **what**. Remove noise; keep signal.\n\n- ⊗ Comments describing what the code does (the code itself shows this)\n- ⊗ In-motion commentary: \"replaced X with Y\", \"temporarily disabled\", \"new approach below\"\n- ⊗ Commented-out code — delete it; version control preserves history\n- ⊗ Section dividers and banners that add no information (e.g. `# --- helpers ---`)\n- ! When editing a file, remove stale comments as you go — do not leave them for later\n- ~ When a comment is needed, be concise: one line explaining the non-obvious reason, not a paragraph\n"
     },
     {
       "id": "hygiene-002",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Commented-out code blocks committed to version control \u2014 delete, don't comment out",
+      "text": "Commented-out code blocks committed to version control — delete, don't comment out",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1607,7 +1607,7 @@
       "id": "hygiene-008",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Circular imports between modules/packages \u2014 detect and eliminate",
+      "text": "Circular imports between modules/packages — detect and eliminate",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1663,7 +1663,7 @@
       "id": "hygiene-015",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "`except Exception: pass` or equivalent \u2014 log at minimum, re-raise if appropriate",
+      "text": "`except Exception: pass` or equivalent — log at minimum, re-raise if appropriate",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1671,7 +1671,7 @@
       "id": "hygiene-016",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask an error \u2014 propagate explicitly",
+      "text": "Returning neutral/zero values (None, {}, [], 0, false, \"\") to mask an error — propagate explicitly",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1679,7 +1679,7 @@
       "id": "hygiene-017",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Log-and-continue: catching an error, logging it, and proceeding as if nothing happened \u2014 unless the error is provably non-fatal AND that decision is documented in a comment",
+      "text": "Log-and-continue: catching an error, logging it, and proceeding as if nothing happened — unless the error is provably non-fatal AND that decision is documented in a comment",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1695,7 +1695,7 @@
       "id": "hygiene-019",
       "tier": "MUST",
       "domain": "hygiene",
-      "text": "When removing a try/catch, confirm the error propagates to a caller that can handle it \u2014 do not simply delete",
+      "text": "When removing a try/catch, confirm the error propagates to a caller that can handle it — do not simply delete",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1711,7 +1711,7 @@
       "id": "hygiene-021",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Feature flags or toggle branches where the flag is always-on or always-off \u2014 collapse to the live path",
+      "text": "Feature flags or toggle branches where the flag is always-on or always-off — collapse to the live path",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1751,7 +1751,7 @@
       "id": "hygiene-026",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Comments describing in-flight replacement work (\"this used to be X, now it's Y\") \u2014 remove once the migration is complete; they are noise for future readers",
+      "text": "Comments describing in-flight replacement work (\"this used to be X, now it's Y\") — remove once the migration is complete; they are noise for future readers",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1815,7 +1815,7 @@
       "id": "hygiene-034",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Copy-paste logic with minor variations \u2014 parameterise instead",
+      "text": "Copy-paste logic with minor variations — parameterise instead",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1831,7 +1831,7 @@
       "id": "hygiene-036",
       "tier": "SHOULD_NOT",
       "domain": "hygiene",
-      "text": "Premature abstraction \u2014 only extract when the duplication is real and the shared contract is clear",
+      "text": "Premature abstraction — only extract when the duplication is real and the shared contract is clear",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1855,7 +1855,7 @@
       "id": "hygiene-039",
       "tier": "MUST_NOT",
       "domain": "hygiene",
-      "text": "Commented-out code \u2014 delete it; version control preserves history",
+      "text": "Commented-out code — delete it; version control preserves history",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1871,7 +1871,7 @@
       "id": "hygiene-041",
       "tier": "MUST",
       "domain": "hygiene",
-      "text": "When editing a file, remove stale comments as you go \u2014 do not leave them for later",
+      "text": "When editing a file, remove stale comments as you go — do not leave them for later",
       "path": "coding/hygiene.md",
       "body": null
     },
@@ -1889,7 +1889,7 @@
       "domain": "security",
       "text": "Validate all inputs at trust boundaries; reject malformed input, do not silently sanitize",
       "path": "coding/security.md",
-      "body": "# Security Standards\n\nBaseline security requirements that apply to every project Deft creates or maintains. This is a baseline standards file, not a comprehensive security audit guide \u2014 see project-specific threat models for deeper coverage.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n## Universal Requirements\n\n- ! Validate all inputs at trust boundaries; reject malformed input, do not silently sanitize\n- ! Treat all data from outside the trust boundary (users, network, files, agents, tools) as adversarial until validated\n- ! Run dependency vulnerability scans on introduction AND on a recurring cadence (weekly minimum)\n- ! Keep secrets out of source, logs, error messages, and build artifacts (see [coding.md `Secrets`](coding.md#code-organization))\n- \u2297 Roll custom cryptography, authentication, or session handling \u2014 use vetted libraries\n- \u2297 Disable security checks \"temporarily\" without an issue tracking re-enablement\n\n## Input Validation & Injection Prevention\n\n- ! Validate type, length, range, and format at every API boundary\n- ! Use parameterized queries / prepared statements for ALL database access\n- ! Apply context-appropriate output encoding (HTML, URL, JSON, shell, SQL) at the point of use, not at storage\n- ! Reject untrusted input outright when it fails validation; do not coerce or \"fix\" it\n- ! Use safe deserialization (JSON over pickle/yaml-load; allow-lists for polymorphic types)\n- \u2297 String interpolation in SQL, shell, or command construction\n- \u2297 `eval`, `exec`, `subprocess(shell=True)`, or equivalent on untrusted input\n- \u2297 Trust client-side validation as the sole defence \u2014 re-validate server-side\n\n## Authentication & Authorization\n\n- ! Use established auth libraries / identity providers (OAuth2/OIDC, Passport, Authlib, etc.)\n- ! Enforce authorization at the API / service layer, never only in the UI\n- ! Use short-lived access tokens; rotate refresh tokens; revoke server-side on logout / compromise\n- ! Hash passwords with a memory-hard algorithm (argon2id, bcrypt, scrypt) \u2014 never plain SHA / MD5\n- ! Enforce MFA for administrative / production access paths\n- \u2297 Roll custom session, password, or token handling\n- \u2297 Hard-code credentials, API keys, or tokens in source \u2014 see Secrets Management below\n- \u2297 Log credentials, full tokens, or session cookies\n\n## Secrets Management\n\nExtends and reinforces [coding.md Secrets rule](coding.md#code-organization). Projects that include any AI agent process MUST also apply the tightened `## No-Read-Secret Rule for Agent Systems (#587)` section below -- the `.env`-files-as-default pattern that is compliant for traditional services is NOT compliant when an agent can read the filesystem.\n\n- ! Store ALL secrets in `secrets/` as `.env` files (or a dedicated secret manager), gitignored\n- ! Read secrets via environment variables / vault clients at runtime\n- ! Rotate secrets on a documented cadence and on any suspected compromise\n- ! Redact tokens, passwords, and PII before logging or surfacing in error messages\n- \u2297 Secrets in code, config committed to VCS, CI logs, or chat transcripts\n- \u2297 Print, `echo`, or interpolate secrets into shell strings; pass via env or `--*-file` flags instead\n- \u2297 Log full credentials, refresh tokens, or PII\n\n## Dependency Security\n\n- ! Pin direct dependency versions in lock files (`uv.lock`, `package-lock.json`, `go.sum`, `Cargo.lock`)\n- ! Audit dependencies on introduction with the language-native scanner:\n  - Python: `pip-audit` (or `uv pip audit`)\n  - Node: `npm audit` / `pnpm audit`\n  - Go: `govulncheck`\n  - Rust: `cargo audit`\n- ! Enable Dependabot (or equivalent) for weekly version + security PRs\n- ! Resolve CRITICAL / HIGH advisories before merge; document deferral with a tracked issue\n- ~ Run `osv-scanner scan source --recursive .` periodically across mixed-language repos\n- \u2297 Disable lockfile checks to \"speed up\" CI\n- \u2297 Pin to floating refs (`main`, `latest`, `@v1`) for third-party GitHub Actions \u2014 pin to a full SHA\n\n## Agent-Specific Threats\n\nDirective builds AI agent frameworks; agents introduce a distinct threat surface beyond classic web security.\n\n- ! Treat ALL user-provided content (chat, files, tool outputs, web fetches) as potentially adversarial \u2014 assume prompt injection\n- ! Isolate tool outputs from the trust boundary: never expose raw internal file contents, environment variables, or system prompts to untrusted input channels\n- ! Gate destructive tool calls (file deletion, repo deletion, force-push, admin merge, billing changes) behind explicit user consent OR a deterministic preflight check\n- ! Bound agent autonomy: declare per-tool allow / deny lists; do not grant blanket shell or network access by default\n- ! Log every tool invocation with arguments redacted for secrets so post-incident review is possible\n- \u2297 Reflect retrieved web content, repo issue bodies, or third-party comments directly back into a privileged tool-call argument without sanitization\n- \u2297 Expose internal system prompts, hidden tool definitions, or other agents' messages to an untrusted input surface\n- \u2297 Run model-suggested shell commands without a deterministic safety classifier (see `scripts/preflight_gh.py` for the canonical pattern)\n\n## Tooling\n\n- ~ Static analysis: language-native linter with security rules enabled (ruff S-rules, golangci-lint gosec, eslint security plugin)\n- ~ Secret scanners: `gitleaks` on pre-commit and CI\n- ~ SAST: CodeQL default setup for hosted repos\n- ~ Container scanning: `trivy fs` or `trivy image` for any Dockerfile / OCI artifact\n- ~ Dependency review: GitHub Dependency Review action on PRs\n\n## Reporting Vulnerabilities\n\n- ! Every project MUST document a vulnerability reporting path (GitHub Security Advisories, `SECURITY.md`, or equivalent)\n- ! Acknowledge reports within a documented SLA; never silently close\n- \u2297 Discuss unfixed vulnerabilities in public issues / PRs\n\n## No-Read-Secret Rule for Agent Systems (#587)\n\nWhen AI agents are part of the system, every filesystem-accessible secret is one a prompt-injection attack could exfiltrate to an external inference server. The `.env`-on-disk pattern that is fine for traditional services becomes a structural security hole the moment a non-deterministic reader is in the loop -- the standard `dotenv` flow makes secrets part of the agent's context by construction.\n\n- ! When the project includes any AI agent process, store secrets in a dedicated secret manager (cloud KMS / Vault / 1Password / Infisical Agent Vault) -- not in `.env` files on disk\n- ! Inject secrets at process start into the agent's environment (or, preferred, deliver them via a credential proxy so the agent never reads the underlying value); fetch from the secret store at runtime, do not bake into images\n- ! Scope each credential to the agent identity that uses it -- one scoped credential per agent or per deployment, auditable separately\n- ~ For production agent systems, prefer the agent credential proxy pattern: a TLS-intercepting forward proxy (or sidecar) attaches credentials to outbound requests so the agent completes its work without ever reading the plaintext secret\n- \u2297 Commit `.env` files in projects where any agent process can read the filesystem -- the agent's context (and any external inference server it calls) inherits everything the agent can read\n- \u2297 Share one API key across multiple agents -- per-identity scoping is what makes the audit log usable when a key is compromised\n\nCross-references: [coding.md `Secrets`](coding.md#code-organization) (this rule extends the existing Secrets rule for agent contexts) | `Secrets Management` section above | the in-flight `patterns/executor-layer-credentials.md` credential-proxy pattern (Wave 2, tracked at [#806](https://github.com/deftai/directive/issues/806); not yet on master) | Infisical Agent Vault <https://github.com/Infisical/agent-vault> (reference implementation).\n\n## Tool-Call Safety Is Independent of Text-Level Safety (#686)\n\nText-level safety alignment does not transfer to the tool-call boundary. An agent whose text outputs satisfy safety constraints can still execute harmful tool calls -- empirically demonstrated in the Agent Behavioral Contracts literature (Cartagena & Teixeira 2026). A safety-aligned model is NOT safe at the tool boundary unless the tool boundary enforces it separately.\n\n- ! Enforce hard constraints on high-impact tools at the call site -- middleware, gateway, or contract layer -- separate from the model's text-level safety training\n- ! Declare an explicit constraint tier for every tool in the tool registry: `read-only`, `reversible`, `irreversible`, or `destructive`. Tools without a declared tier MUST be treated as `destructive` by default\n- ! Audit-log every tool invocation at the tool-call layer (tool name, arguments redacted for secrets, caller identity, outcome). Text-level logs of the model's reasoning are insufficient for post-incident review\n- ! For `irreversible` / `destructive` tools, gate execution with a deterministic preflight (allow-list, environment check, ack token) outside the model -- never let the model decide on its own that an operation is safe\n- \u2297 Rely on model-level safety training as the only barrier between an agent and a destructive tool call -- text alignment provides no guarantee at the tool boundary\n- \u2297 Ship a tool registry where any tool is missing a constraint-tier declaration -- the default-to-`destructive` fallback exists for staging, not production\n\nCross-references: `Agent-Specific Threats` section above | the in-flight `patterns/executor-layer-credentials.md` tool-call gateway pattern (Wave 2, tracked at [#806](https://github.com/deftai/directive/issues/806); not yet on master) | [`scripts/preflight_gh.py`](../../scripts/preflight_gh.py) (#1019 reference implementation of a per-tool deterministic safety classifier) | Cartagena & Teixeira 2026 <https://arxiv.org/abs/2602.22302>.\n\n## Destructive-Op Guardrails -- Environment Isolation + Irreversibility (#708)\n\nThe April 2026 PocketOS / Railway incident -- a Cursor/Claude agent deleted a production database AND its backups in roughly nine seconds after being told to \"clean up the staging DB\" -- is the canonical recurrence record for two distinct gaps: acting on a prompt-claimed environment instead of a verified one, and treating \"destructive\" as excluding backups. The two gates below close those gaps; the incident is documented at [`incidents/2026-04-pocketos-railway-prod-db-wipe.md`](../../incidents/2026-04-pocketos-railway-prod-db-wipe.md).\n\n### Environment Isolation Gate\n\n- ! Before any write or destructive operation, the agent MUST positively identify the target environment (prod / staging / dev) from a TRUSTED, NON-PROMPT signal -- env var (e.g. `APP_ENV`), config file, or connection-string introspection. The user's wording is NOT a trusted signal\n- ! Enumerate the prod-detection heuristics explicitly in the project's runbook: hostname or connection-string contains `prod` / `production`, matches the documented prod hostname(s), or resolves into a documented prod-VPC CIDR. A trusted signal that disagrees with the prompt always wins\n- ! If the environment cannot be verified from a trusted signal, the agent MUST refuse the operation and escalate to a human. \"Probably staging\" is a refusal, not an approval\n- \u2297 Trust the user's wording (e.g. \"clean up the staging DB\") as environment authorisation -- the prompt is the untrusted input, the env var / connection string is the trusted signal\n- \u2297 Heuristically downgrade an unverified environment to \"non-prod\" so the operation can proceed -- the gate fails closed\n\n### Irreversibility Gate\n\n- ! Destructive operations -- DB `DROP` / `TRUNCATE` / `DELETE` without `WHERE`, `rm -rf`, force-push to a shared branch, table rename over an existing target, AND any mutation of a backup -- require BOTH a tested rollback path AND an explicit in-session human ack token before execution\n- ! Backups are first-class state. Deleting, overwriting, truncating, or \"rotating\" a backup is itself a destructive operation and MUST go through this gate\n- ! A verified non-prod environment (Environment Isolation Gate passed with `env != prod`) MAY relax the human-ack requirement but does NOT remove the rollback-path requirement -- a dev DB without a rollback is still a footgun\n- ~ Declare the irreversibility-tier classification for the project's destructive verbs in the in-flight `conventions/verb-classification.json` (tracked at [#1095](https://github.com/deftai/directive/issues/1095) closed-verb scope-expansion gate; not yet on master). Inline declaration in the operation's runbook is acceptable until that file lands\n- \u2297 Execute a destructive operation in a verified prod environment without an in-session human ack token -- \"the user authorised the project\" is not session-scoped consent\n- \u2297 Treat a backup as out-of-scope for the irreversibility gate -- the PocketOS incident is the recurrence record; backups were destroyed in the same nine-second window as the live database\n\nCross-references: [`incidents/README.md`](../incidents/README.md) (incidents library format) | [`incidents/2026-04-pocketos-railway-prod-db-wipe.md`](../../incidents/2026-04-pocketos-railway-prod-db-wipe.md) (seed entry) | `Agent-Specific Threats` section above (this section extends it) | [`scripts/preflight_gh.py`](../../scripts/preflight_gh.py) (#1019 deterministic-classifier reference) | #1095 closed-verb scope-expansion gate (consumes the irreversibility-tier classification).\n\n## Anti-Patterns\n\n- \u2297 \"We'll add security later\" \u2014 baseline standards apply from day one\n- \u2297 Silent sanitization that masks malformed input rather than rejecting it\n- \u2297 Disabling lockfile / signature / scanner checks to ship faster\n- \u2297 Trusting agent / model output as if it were validated user input\n- \u2297 Logging entire request bodies or environment dumps in production\n- \u2297 Granting agents blanket network or shell access without per-tool allow-lists\n- \u2297 Reflecting third-party content (issue bodies, web pages, tool outputs) into privileged tool calls unsanitized\n\n---\n\n**See also**: [coding.md](coding.md) (general coding standards, Secrets rule) | [testing.md](testing.md) (Security Tests section) | [hygiene.md](hygiene.md) (error-hiding anti-patterns) | [../scm/github.md](../scm/github.md) (destructive `gh` verbs preflight gate #1019) | [../incidents/README.md](../incidents/README.md) (incidents library, #708)\n"
+      "body": "# Security Standards\n\nBaseline security requirements that apply to every project Deft creates or maintains. This is a baseline standards file, not a comprehensive security audit guide — see project-specific threat models for deeper coverage.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## Universal Requirements\n\n- ! Validate all inputs at trust boundaries; reject malformed input, do not silently sanitize\n- ! Treat all data from outside the trust boundary (users, network, files, agents, tools) as adversarial until validated\n- ! Run dependency vulnerability scans on introduction AND on a recurring cadence (weekly minimum)\n- ! Keep secrets out of source, logs, error messages, and build artifacts (see [coding.md `Secrets`](coding.md#code-organization))\n- ⊗ Roll custom cryptography, authentication, or session handling — use vetted libraries\n- ⊗ Disable security checks \"temporarily\" without an issue tracking re-enablement\n\n## Input Validation & Injection Prevention\n\n- ! Validate type, length, range, and format at every API boundary\n- ! Use parameterized queries / prepared statements for ALL database access\n- ! Apply context-appropriate output encoding (HTML, URL, JSON, shell, SQL) at the point of use, not at storage\n- ! Reject untrusted input outright when it fails validation; do not coerce or \"fix\" it\n- ! Use safe deserialization (JSON over pickle/yaml-load; allow-lists for polymorphic types)\n- ⊗ String interpolation in SQL, shell, or command construction\n- ⊗ `eval`, `exec`, `subprocess(shell=True)`, or equivalent on untrusted input\n- ⊗ Trust client-side validation as the sole defence — re-validate server-side\n\n## Authentication & Authorization\n\n- ! Use established auth libraries / identity providers (OAuth2/OIDC, Passport, Authlib, etc.)\n- ! Enforce authorization at the API / service layer, never only in the UI\n- ! Use short-lived access tokens; rotate refresh tokens; revoke server-side on logout / compromise\n- ! Hash passwords with a memory-hard algorithm (argon2id, bcrypt, scrypt) — never plain SHA / MD5\n- ! Enforce MFA for administrative / production access paths\n- ⊗ Roll custom session, password, or token handling\n- ⊗ Hard-code credentials, API keys, or tokens in source — see Secrets Management below\n- ⊗ Log credentials, full tokens, or session cookies\n\n## Secrets Management\n\nExtends and reinforces [coding.md Secrets rule](coding.md#code-organization). Projects that include any AI agent process MUST also apply the tightened `## No-Read-Secret Rule for Agent Systems (#587)` section below -- the `.env`-files-as-default pattern that is compliant for traditional services is NOT compliant when an agent can read the filesystem.\n\n- ! Store ALL secrets in `secrets/` as `.env` files (or a dedicated secret manager), gitignored\n- ! Read secrets via environment variables / vault clients at runtime\n- ! Rotate secrets on a documented cadence and on any suspected compromise\n- ! Redact tokens, passwords, and PII before logging or surfacing in error messages\n- ⊗ Secrets in code, config committed to VCS, CI logs, or chat transcripts\n- ⊗ Print, `echo`, or interpolate secrets into shell strings; pass via env or `--*-file` flags instead\n- ⊗ Log full credentials, refresh tokens, or PII\n\n## Dependency Security\n\n- ! Pin direct dependency versions in lock files (`uv.lock`, `package-lock.json`, `go.sum`, `Cargo.lock`)\n- ! Audit dependencies on introduction with the language-native scanner:\n  - Python: `pip-audit` (or `uv pip audit`)\n  - Node: `npm audit` / `pnpm audit`\n  - Go: `govulncheck`\n  - Rust: `cargo audit`\n- ! Enable Dependabot (or equivalent) for weekly version + security PRs\n- ! Resolve CRITICAL / HIGH advisories before merge; document deferral with a tracked issue\n- ~ Run `osv-scanner scan source --recursive .` periodically across mixed-language repos\n- ⊗ Disable lockfile checks to \"speed up\" CI\n- ⊗ Pin to floating refs (`main`, `latest`, `@v1`) for third-party GitHub Actions — pin to a full SHA\n\n## Agent-Specific Threats\n\nDirective builds AI agent frameworks; agents introduce a distinct threat surface beyond classic web security.\n\n- ! Treat ALL user-provided content (chat, files, tool outputs, web fetches) as potentially adversarial — assume prompt injection\n- ! Isolate tool outputs from the trust boundary: never expose raw internal file contents, environment variables, or system prompts to untrusted input channels\n- ! Gate destructive tool calls (file deletion, repo deletion, force-push, admin merge, billing changes) behind explicit user consent OR a deterministic preflight check\n- ! Bound agent autonomy: declare per-tool allow / deny lists; do not grant blanket shell or network access by default\n- ! Log every tool invocation with arguments redacted for secrets so post-incident review is possible\n- ⊗ Reflect retrieved web content, repo issue bodies, or third-party comments directly back into a privileged tool-call argument without sanitization\n- ⊗ Expose internal system prompts, hidden tool definitions, or other agents' messages to an untrusted input surface\n- ⊗ Run model-suggested shell commands without a deterministic safety classifier (see `scripts/preflight_gh.py` for the canonical pattern)\n\n## Tooling\n\n- ~ Static analysis: language-native linter with security rules enabled (ruff S-rules, golangci-lint gosec, eslint security plugin)\n- ~ Secret scanners: `gitleaks` on pre-commit and CI\n- ~ SAST: CodeQL default setup for hosted repos\n- ~ Container scanning: `trivy fs` or `trivy image` for any Dockerfile / OCI artifact\n- ~ Dependency review: GitHub Dependency Review action on PRs\n\n## Reporting Vulnerabilities\n\n- ! Every project MUST document a vulnerability reporting path (GitHub Security Advisories, `SECURITY.md`, or equivalent)\n- ! Acknowledge reports within a documented SLA; never silently close\n- ⊗ Discuss unfixed vulnerabilities in public issues / PRs\n\n## No-Read-Secret Rule for Agent Systems (#587)\n\nWhen AI agents are part of the system, every filesystem-accessible secret is one a prompt-injection attack could exfiltrate to an external inference server. The `.env`-on-disk pattern that is fine for traditional services becomes a structural security hole the moment a non-deterministic reader is in the loop -- the standard `dotenv` flow makes secrets part of the agent's context by construction.\n\n- ! When the project includes any AI agent process, store secrets in a dedicated secret manager (cloud KMS / Vault / 1Password / Infisical Agent Vault) -- not in `.env` files on disk\n- ! Inject secrets at process start into the agent's environment (or, preferred, deliver them via a credential proxy so the agent never reads the underlying value); fetch from the secret store at runtime, do not bake into images\n- ! Scope each credential to the agent identity that uses it -- one scoped credential per agent or per deployment, auditable separately\n- ~ For production agent systems, prefer the agent credential proxy pattern: a TLS-intercepting forward proxy (or sidecar) attaches credentials to outbound requests so the agent completes its work without ever reading the plaintext secret\n- ⊗ Commit `.env` files in projects where any agent process can read the filesystem -- the agent's context (and any external inference server it calls) inherits everything the agent can read\n- ⊗ Share one API key across multiple agents -- per-identity scoping is what makes the audit log usable when a key is compromised\n\nCross-references: [coding.md `Secrets`](coding.md#code-organization) (this rule extends the existing Secrets rule for agent contexts) | `Secrets Management` section above | the in-flight `patterns/executor-layer-credentials.md` credential-proxy pattern (Wave 2, tracked at [#806](https://github.com/deftai/directive/issues/806); not yet on master) | Infisical Agent Vault <https://github.com/Infisical/agent-vault> (reference implementation).\n\n## Tool-Call Safety Is Independent of Text-Level Safety (#686)\n\nText-level safety alignment does not transfer to the tool-call boundary. An agent whose text outputs satisfy safety constraints can still execute harmful tool calls -- empirically demonstrated in the Agent Behavioral Contracts literature (Cartagena & Teixeira 2026). A safety-aligned model is NOT safe at the tool boundary unless the tool boundary enforces it separately.\n\n- ! Enforce hard constraints on high-impact tools at the call site -- middleware, gateway, or contract layer -- separate from the model's text-level safety training\n- ! Declare an explicit constraint tier for every tool in the tool registry: `read-only`, `reversible`, `irreversible`, or `destructive`. Tools without a declared tier MUST be treated as `destructive` by default\n- ! Audit-log every tool invocation at the tool-call layer (tool name, arguments redacted for secrets, caller identity, outcome). Text-level logs of the model's reasoning are insufficient for post-incident review\n- ! For `irreversible` / `destructive` tools, gate execution with a deterministic preflight (allow-list, environment check, ack token) outside the model -- never let the model decide on its own that an operation is safe\n- ⊗ Rely on model-level safety training as the only barrier between an agent and a destructive tool call -- text alignment provides no guarantee at the tool boundary\n- ⊗ Ship a tool registry where any tool is missing a constraint-tier declaration -- the default-to-`destructive` fallback exists for staging, not production\n\nCross-references: `Agent-Specific Threats` section above | the in-flight `patterns/executor-layer-credentials.md` tool-call gateway pattern (Wave 2, tracked at [#806](https://github.com/deftai/directive/issues/806); not yet on master) | [`scripts/preflight_gh.py`](../../scripts/preflight_gh.py) (#1019 reference implementation of a per-tool deterministic safety classifier) | Cartagena & Teixeira 2026 <https://arxiv.org/abs/2602.22302>.\n\n## Destructive-Op Guardrails -- Environment Isolation + Irreversibility (#708)\n\nThe April 2026 PocketOS / Railway incident -- a Cursor/Claude agent deleted a production database AND its backups in roughly nine seconds after being told to \"clean up the staging DB\" -- is the canonical recurrence record for two distinct gaps: acting on a prompt-claimed environment instead of a verified one, and treating \"destructive\" as excluding backups. The two gates below close those gaps; the incident is documented at [`incidents/2026-04-pocketos-railway-prod-db-wipe.md`](../../incidents/2026-04-pocketos-railway-prod-db-wipe.md).\n\n### Environment Isolation Gate\n\n- ! Before any write or destructive operation, the agent MUST positively identify the target environment (prod / staging / dev) from a TRUSTED, NON-PROMPT signal -- env var (e.g. `APP_ENV`), config file, or connection-string introspection. The user's wording is NOT a trusted signal\n- ! Enumerate the prod-detection heuristics explicitly in the project's runbook: hostname or connection-string contains `prod` / `production`, matches the documented prod hostname(s), or resolves into a documented prod-VPC CIDR. A trusted signal that disagrees with the prompt always wins\n- ! If the environment cannot be verified from a trusted signal, the agent MUST refuse the operation and escalate to a human. \"Probably staging\" is a refusal, not an approval\n- ⊗ Trust the user's wording (e.g. \"clean up the staging DB\") as environment authorisation -- the prompt is the untrusted input, the env var / connection string is the trusted signal\n- ⊗ Heuristically downgrade an unverified environment to \"non-prod\" so the operation can proceed -- the gate fails closed\n\n### Irreversibility Gate\n\n- ! Destructive operations -- DB `DROP` / `TRUNCATE` / `DELETE` without `WHERE`, `rm -rf`, force-push to a shared branch, table rename over an existing target, AND any mutation of a backup -- require BOTH a tested rollback path AND an explicit in-session human ack token before execution\n- ! Backups are first-class state. Deleting, overwriting, truncating, or \"rotating\" a backup is itself a destructive operation and MUST go through this gate\n- ! A verified non-prod environment (Environment Isolation Gate passed with `env != prod`) MAY relax the human-ack requirement but does NOT remove the rollback-path requirement -- a dev DB without a rollback is still a footgun\n- ~ Declare the irreversibility-tier classification for the project's destructive verbs in the in-flight `conventions/verb-classification.json` (tracked at [#1095](https://github.com/deftai/directive/issues/1095) closed-verb scope-expansion gate; not yet on master). Inline declaration in the operation's runbook is acceptable until that file lands\n- ⊗ Execute a destructive operation in a verified prod environment without an in-session human ack token -- \"the user authorised the project\" is not session-scoped consent\n- ⊗ Treat a backup as out-of-scope for the irreversibility gate -- the PocketOS incident is the recurrence record; backups were destroyed in the same nine-second window as the live database\n\nCross-references: [`incidents/README.md`](../incidents/README.md) (incidents library format) | [`incidents/2026-04-pocketos-railway-prod-db-wipe.md`](../../incidents/2026-04-pocketos-railway-prod-db-wipe.md) (seed entry) | `Agent-Specific Threats` section above (this section extends it) | [`scripts/preflight_gh.py`](../../scripts/preflight_gh.py) (#1019 deterministic-classifier reference) | #1095 closed-verb scope-expansion gate (consumes the irreversibility-tier classification).\n\n## Anti-Patterns\n\n- ⊗ \"We'll add security later\" — baseline standards apply from day one\n- ⊗ Silent sanitization that masks malformed input rather than rejecting it\n- ⊗ Disabling lockfile / signature / scanner checks to ship faster\n- ⊗ Trusting agent / model output as if it were validated user input\n- ⊗ Logging entire request bodies or environment dumps in production\n- ⊗ Granting agents blanket network or shell access without per-tool allow-lists\n- ⊗ Reflecting third-party content (issue bodies, web pages, tool outputs) into privileged tool calls unsanitized\n\n---\n\n**See also**: [coding.md](coding.md) (general coding standards, Secrets rule) | [testing.md](testing.md) (Security Tests section) | [hygiene.md](hygiene.md) (error-hiding anti-patterns) | [../scm/github.md](../scm/github.md) (destructive `gh` verbs preflight gate #1019) | [../incidents/README.md](../incidents/README.md) (incidents library, #708)\n"
     },
     {
       "id": "security-002",
@@ -1919,7 +1919,7 @@
       "id": "security-005",
       "tier": "MUST_NOT",
       "domain": "security",
-      "text": "Roll custom cryptography, authentication, or session handling \u2014 use vetted libraries",
+      "text": "Roll custom cryptography, authentication, or session handling — use vetted libraries",
       "path": "coding/security.md",
       "body": null
     },
@@ -1991,7 +1991,7 @@
       "id": "security-014",
       "tier": "MUST_NOT",
       "domain": "security",
-      "text": "Trust client-side validation as the sole defence \u2014 re-validate server-side",
+      "text": "Trust client-side validation as the sole defence — re-validate server-side",
       "path": "coding/security.md",
       "body": null
     },
@@ -2023,7 +2023,7 @@
       "id": "security-018",
       "tier": "MUST",
       "domain": "security",
-      "text": "Hash passwords with a memory-hard algorithm (argon2id, bcrypt, scrypt) \u2014 never plain SHA / MD5",
+      "text": "Hash passwords with a memory-hard algorithm (argon2id, bcrypt, scrypt) — never plain SHA / MD5",
       "path": "coding/security.md",
       "body": null
     },
@@ -2047,7 +2047,7 @@
       "id": "security-021",
       "tier": "MUST_NOT",
       "domain": "security",
-      "text": "Hard-code credentials, API keys, or tokens in source \u2014 see Secrets Management below",
+      "text": "Hard-code credentials, API keys, or tokens in source — see Secrets Management below",
       "path": "coding/security.md",
       "body": null
     },
@@ -2167,7 +2167,7 @@
       "id": "security-036",
       "tier": "MUST_NOT",
       "domain": "security",
-      "text": "Pin to floating refs (`main`, `latest`, `@v1`) for third-party GitHub Actions \u2014 pin to a full SHA",
+      "text": "Pin to floating refs (`main`, `latest`, `@v1`) for third-party GitHub Actions — pin to a full SHA",
       "path": "coding/security.md",
       "body": null
     },
@@ -2175,7 +2175,7 @@
       "id": "security-037",
       "tier": "MUST",
       "domain": "security",
-      "text": "Treat ALL user-provided content (chat, files, tool outputs, web fetches) as potentially adversarial \u2014 assume prompt injection",
+      "text": "Treat ALL user-provided content (chat, files, tool outputs, web fetches) as potentially adversarial — assume prompt injection",
       "path": "coding/security.md",
       "body": null
     },
@@ -2487,7 +2487,7 @@
       "id": "security-076",
       "tier": "MUST_NOT",
       "domain": "security",
-      "text": "\"We'll add security later\" \u2014 baseline standards apply from day one",
+      "text": "\"We'll add security later\" — baseline standards apply from day one",
       "path": "coding/security.md",
       "body": null
     },
@@ -2543,15 +2543,15 @@
       "id": "testing-001",
       "tier": "MUST",
       "domain": "testing",
-      "text": "Achieve \u226585% coverage (overall + per-module/package/file)",
+      "text": "Achieve ≥85% coverage (overall + per-module/package/file)",
       "path": "coding/testing.md",
-      "body": "# Testing Standards\n\nUniversal testing requirements across all languages and interfaces.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n## Universal Requirements\n\n- ! Achieve \u226585% coverage (overall + per-module/package/file)\n- ! Include \u226550 fuzzing tests per input point\n- ~ Have integration tests for critical paths/workflows\n- ! Exclude entry points and main functions from coverage\n- ! Test all code paths: normal, edge cases, error conditions\n- ! Run `task check` (or equivalent) before commit\n- \u2297 say a (todo-list|plan|phase|project) is done if relevant tests have not been written, run, and PASSED.\n- \u2297 assume its ok for a test to fail in any situation\n\n## Test-First Development\n\n- ! Implementation is INCOMPLETE until tests written AND `task test:coverage` passes\n- ! New functions/classes MUST have corresponding tests in same commit\n- ! Modified functions MUST update existing tests to maintain coverage\n- ! Run `task test:coverage` after ANY code change to verify \u226585% maintained\n- ! If coverage drops below threshold, implementation is INCOMPLETE\n- ~ Write tests for edge cases, not just happy paths\n- \u2297 Skip test updates when modifying existing functions\n- \u2297 Implement code without tests\n- \u2297 Claim \"done\" before running test:coverage\n\n## Coverage\n\n**What to count:**\n\n- ! All source code in src/, internal/, pkg/, lib/\n\n**What to exclude:**\n\n- ! Entry points: main(), **main**, index.ts (if trivial)\n- ! Generated code\n- ! Third-party code\n- ! Test files themselves\n\n**Thresholds:**\n\n- ! \u226585% lines\n- ! \u226585% functions/methods\n- ! \u226585% branches\n- ! \u226585% statements\n\n## Test Types\n\n### Unit Tests\n\n- ! Individual functions/methods/components\n- ! Normal cases + edge cases + error conditions\n- ! Fast execution (milliseconds)\n- ! No external dependencies (use mocks/stubs)\n\n### Integration Tests\n\n- ~ Full workflows with real dependencies\n- ~ Realistic scenarios\n- ~ Database, API, file system interactions\n- ~ Slower execution acceptable\n\n### Fuzzing Tests\n\n- ! \u226550 fuzzing tests per input point\n- ! Random/malformed inputs\n- ! Catch unexpected crashes, hangs, exceptions\n\n### Load/Performance Tests\n\n- ~ For performance-critical code\n- ~ Measure response times under load\n- Tools: JMeter, Gatling, k6, Apache Bench\n\n### Security Tests\n\n- ! For code handling untrusted input\n- ! SQL injection, XSS, auth bypass, path traversal\n- Tools: OWASP ZAP, Burp Suite, SQLMap\n\n### Snapshot Tests\n\n- ~ For CLI output, rendered UI, generated files\n- ~ Detect unintended output changes\n\n### Build Output Tests\n\n- ~ Build scripts that produce `dist/` artifacts have a smoke test verifying expected output files exist and contain expected content\n- ! Non-compiled assets (manifests, configs, extension metadata) that bundlers don't track are explicitly verified post-build\n- ~ Verify file presence, non-empty size, and structural validity (e.g. required JSON keys present)\n- ! A build that exits 0 but produces stale or incomplete artifacts is a silent failure \u2014 treat it as a build failure (#105)\n\n## Language-Specific Details\n\n**Python**: [../languages/python.md](../languages/python.md#testing) - pytest, pytest-cov, pytest-mock\n**Go**: [../languages/go.md](../languages/go.md#testing) - Testify, table-driven tests\n**C++**: [../languages/cpp.md](../languages/cpp.md#testing) - Catch2/GoogleTest, GoogleMock\n**TypeScript**: [../languages/typescript.md](../languages/typescript.md#testing) - Vitest/Jest, React Testing Library\n**CLI**: [../interfaces/cli.md](../interfaces/cli.md#testing) - CliRunner, format validation\n**REST APIs**: [../interfaces/rest.md](../interfaces/rest.md#testing) - endpoint testing, security testing\n\n## Test Organization\n\n**File naming:**\n\n- Python: `test_*.py` or `*_test.py`\n- Go: `*_test.go`\n- C++: `test_*.cpp` or `*_test.cpp`\n- TypeScript: `*.spec.ts` or `*.test.ts`\n\n**Directory structure:**\n\n```\nproject/\n\u251c\u2500\u2500 src/           # Source code\n\u251c\u2500\u2500 tests/         # Test files\n\u2502   \u251c\u2500\u2500 unit/      # Unit tests\n\u2502   \u2514\u2500\u2500 integration/  # Integration tests (optional separation)\n```\n\n## Best Practices\n\n- ! Write tests before or alongside code (TDD encouraged)\n- ! One assertion per test (or logically grouped assertions)\n- ~ Use descriptive test names: `test_user_login_with_invalid_password`\n- ! Arrange-Act-Assert (AAA) pattern\n- ! Test behavior, not implementation\n- \u2249 Rely on test execution order\n- ! Clean up resources (files, DB, connections) in teardown\n\n## Anti-patterns\n\n- \u2297 Skip tests to meet deadlines\n- \u2297 Test only happy paths (edge cases critical)\n- \u2297 Mock everything (integration tests needed too)\n- \u2297 Ignore flaky tests (fix or remove them)\n- \u2297 Commit failing tests\n- \u2297 Write tests that depend on external state\n- \u2297 Hard-code dates, times, random values\n- \u2297 Implementing code without tests\n- \u2297 Claiming \"done\" before running test:coverage\n- \u2297 Ignoring coverage drops\n\n## CI/CD Integration\n\n- ! Tests run automatically on every commit/PR\n- ! Block merges if tests fail\n- ! Block merges if coverage drops below threshold\n- ~ Test in multiple environments (OS, versions)\n\n---\n\n**See also**: [main.md](../../main.md) | Language-specific testing in python.md, go.md, cpp.md, typescript.md\n"
+      "body": "# Testing Standards\n\nUniversal testing requirements across all languages and interfaces.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## Universal Requirements\n\n- ! Achieve ≥85% coverage (overall + per-module/package/file)\n- ! Include ≥50 fuzzing tests per input point\n- ~ Have integration tests for critical paths/workflows\n- ! Exclude entry points and main functions from coverage\n- ! Test all code paths: normal, edge cases, error conditions\n- ! Run `task check` (or equivalent) before commit\n- ⊗ say a (todo-list|plan|phase|project) is done if relevant tests have not been written, run, and PASSED.\n- ⊗ assume its ok for a test to fail in any situation\n\n## Test-First Development\n\n- ! Implementation is INCOMPLETE until tests written AND `task test:coverage` passes\n- ! New functions/classes MUST have corresponding tests in same commit\n- ! Modified functions MUST update existing tests to maintain coverage\n- ! Run `task test:coverage` after ANY code change to verify ≥85% maintained\n- ! If coverage drops below threshold, implementation is INCOMPLETE\n- ~ Write tests for edge cases, not just happy paths\n- ⊗ Skip test updates when modifying existing functions\n- ⊗ Implement code without tests\n- ⊗ Claim \"done\" before running test:coverage\n\n## Coverage\n\n**What to count:**\n\n- ! All source code in src/, internal/, pkg/, lib/\n\n**What to exclude:**\n\n- ! Entry points: main(), **main**, index.ts (if trivial)\n- ! Generated code\n- ! Third-party code\n- ! Test files themselves\n\n**Thresholds:**\n\n- ! ≥85% lines\n- ! ≥85% functions/methods\n- ! ≥85% branches\n- ! ≥85% statements\n\n## Test Types\n\n### Unit Tests\n\n- ! Individual functions/methods/components\n- ! Normal cases + edge cases + error conditions\n- ! Fast execution (milliseconds)\n- ! No external dependencies (use mocks/stubs)\n\n### Integration Tests\n\n- ~ Full workflows with real dependencies\n- ~ Realistic scenarios\n- ~ Database, API, file system interactions\n- ~ Slower execution acceptable\n\n### Fuzzing Tests\n\n- ! ≥50 fuzzing tests per input point\n- ! Random/malformed inputs\n- ! Catch unexpected crashes, hangs, exceptions\n\n### Load/Performance Tests\n\n- ~ For performance-critical code\n- ~ Measure response times under load\n- Tools: JMeter, Gatling, k6, Apache Bench\n\n### Security Tests\n\n- ! For code handling untrusted input\n- ! SQL injection, XSS, auth bypass, path traversal\n- Tools: OWASP ZAP, Burp Suite, SQLMap\n\n### Snapshot Tests\n\n- ~ For CLI output, rendered UI, generated files\n- ~ Detect unintended output changes\n\n### Build Output Tests\n\n- ~ Build scripts that produce `dist/` artifacts have a smoke test verifying expected output files exist and contain expected content\n- ! Non-compiled assets (manifests, configs, extension metadata) that bundlers don't track are explicitly verified post-build\n- ~ Verify file presence, non-empty size, and structural validity (e.g. required JSON keys present)\n- ! A build that exits 0 but produces stale or incomplete artifacts is a silent failure — treat it as a build failure (#105)\n\n## Language-Specific Details\n\n**Python**: [../languages/python.md](../languages/python.md#testing) - pytest, pytest-cov, pytest-mock\n**Go**: [../languages/go.md](../languages/go.md#testing) - Testify, table-driven tests\n**C++**: [../languages/cpp.md](../languages/cpp.md#testing) - Catch2/GoogleTest, GoogleMock\n**TypeScript**: [../languages/typescript.md](../languages/typescript.md#testing) - Vitest/Jest, React Testing Library\n**CLI**: [../interfaces/cli.md](../interfaces/cli.md#testing) - CliRunner, format validation\n**REST APIs**: [../interfaces/rest.md](../interfaces/rest.md#testing) - endpoint testing, security testing\n\n## Test Organization\n\n**File naming:**\n\n- Python: `test_*.py` or `*_test.py`\n- Go: `*_test.go`\n- C++: `test_*.cpp` or `*_test.cpp`\n- TypeScript: `*.spec.ts` or `*.test.ts`\n\n**Directory structure:**\n\n```\nproject/\n├── src/           # Source code\n├── tests/         # Test files\n│   ├── unit/      # Unit tests\n│   └── integration/  # Integration tests (optional separation)\n```\n\n## Best Practices\n\n- ! Write tests before or alongside code (TDD encouraged)\n- ! One assertion per test (or logically grouped assertions)\n- ~ Use descriptive test names: `test_user_login_with_invalid_password`\n- ! Arrange-Act-Assert (AAA) pattern\n- ! Test behavior, not implementation\n- ≉ Rely on test execution order\n- ! Clean up resources (files, DB, connections) in teardown\n\n## Anti-patterns\n\n- ⊗ Skip tests to meet deadlines\n- ⊗ Test only happy paths (edge cases critical)\n- ⊗ Mock everything (integration tests needed too)\n- ⊗ Ignore flaky tests (fix or remove them)\n- ⊗ Commit failing tests\n- ⊗ Write tests that depend on external state\n- ⊗ Hard-code dates, times, random values\n- ⊗ Implementing code without tests\n- ⊗ Claiming \"done\" before running test:coverage\n- ⊗ Ignoring coverage drops\n\n## CI/CD Integration\n\n- ! Tests run automatically on every commit/PR\n- ! Block merges if tests fail\n- ! Block merges if coverage drops below threshold\n- ~ Test in multiple environments (OS, versions)\n\n---\n\n**See also**: [main.md](../../main.md) | Language-specific testing in python.md, go.md, cpp.md, typescript.md\n"
     },
     {
       "id": "testing-002",
       "tier": "MUST",
       "domain": "testing",
-      "text": "Include \u226550 fuzzing tests per input point",
+      "text": "Include ≥50 fuzzing tests per input point",
       "path": "coding/testing.md",
       "body": null
     },
@@ -2631,7 +2631,7 @@
       "id": "testing-012",
       "tier": "MUST",
       "domain": "testing",
-      "text": "Run `task test:coverage` after ANY code change to verify \u226585% maintained",
+      "text": "Run `task test:coverage` after ANY code change to verify ≥85% maintained",
       "path": "coding/testing.md",
       "body": null
     },
@@ -2719,7 +2719,7 @@
       "id": "testing-023",
       "tier": "MUST",
       "domain": "testing",
-      "text": "\u226585% lines",
+      "text": "≥85% lines",
       "path": "coding/testing.md",
       "body": null
     },
@@ -2727,7 +2727,7 @@
       "id": "testing-024",
       "tier": "MUST",
       "domain": "testing",
-      "text": "\u226585% functions/methods",
+      "text": "≥85% functions/methods",
       "path": "coding/testing.md",
       "body": null
     },
@@ -2735,7 +2735,7 @@
       "id": "testing-025",
       "tier": "MUST",
       "domain": "testing",
-      "text": "\u226585% branches",
+      "text": "≥85% branches",
       "path": "coding/testing.md",
       "body": null
     },
@@ -2743,7 +2743,7 @@
       "id": "testing-026",
       "tier": "MUST",
       "domain": "testing",
-      "text": "\u226585% statements",
+      "text": "≥85% statements",
       "path": "coding/testing.md",
       "body": null
     },
@@ -2815,7 +2815,7 @@
       "id": "testing-035",
       "tier": "MUST",
       "domain": "testing",
-      "text": "\u226550 fuzzing tests per input point",
+      "text": "≥50 fuzzing tests per input point",
       "path": "coding/testing.md",
       "body": null
     },
@@ -2911,7 +2911,7 @@
       "id": "testing-047",
       "tier": "MUST",
       "domain": "testing",
-      "text": "A build that exits 0 but produces stale or incomplete artifacts is a silent failure \u2014 treat it as a build failure (#105)",
+      "text": "A build that exits 0 but produces stale or incomplete artifacts is a silent failure — treat it as a build failure (#105)",
       "path": "coding/testing.md",
       "body": null
     },
@@ -3089,13 +3089,13 @@
       "domain": "toolchain",
       "text": "Before beginning implementation, verify all required toolchain components are installed and functional",
       "path": "coding/toolchain.md",
-      "body": "# Toolchain Validation\n\nRules for verifying that required tools are installed and functional before beginning implementation.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, \u2249=SHOULD NOT, \u2297=MUST NOT, ?=MAY.\n\n**\u26a0\ufe0f See also**:\n- [coding.md](coding.md) \u2014 Build Automation section\n- [build-output.md](build-output.md) \u2014 post-build artifact validation\n\n## Pre-Implementation Gate\n\n- ! Before beginning implementation, verify all required toolchain components are installed and functional\n- ! Required components vary by project \u2014 at minimum verify: task runner, language compiler/runtime, and platform SDK if applicable\n- ! If any required tool is missing or non-functional, stop and report \u2014 do not proceed with implementation\n- \u2297 Assume a tool is available because it was present in a previous session or referenced in the spec\n- \u2297 Proceed with implementation when the build or test toolchain is unavailable\n\n## What to Verify\n\n- ! Task runner: `task --version` (required for quality gates)\n- ! Language runtime/compiler: e.g. `go version`, `python --version`, `node --version`, `swift --version`\n- ! Platform SDK (if applicable): e.g. `xcode-select -p` for iOS/macOS, Android SDK path for Android\n- ! Project-specific tools listed in PROJECT.md or SPECIFICATION.md\n\n## On Missing Tools\n\n- ! Report exactly which tools are missing and provide install guidance\n- ! Do not partially implement using available tools while skipping quality gates\n- ~ Offer to help install missing tools if the user consents\n## uv Project Pinning (#1011)\n**Why this rule exists:** without an explicit pin, `uv run` walks upward from cwd looking for the nearest `pyproject.toml` and binds to whatever it finds first. When a deft consumer's repo root has no `pyproject.toml` of its own (the common case for non-Python projects), uv escapes the framework directory and resolves to an ancestor workspace `pyproject.toml`. That ancestor's build backend (frequently unresolvable in the consumer environment) crashes during environment resolution before any framework task body runs. The root-cause analysis lives in `vbrief/active/2026-05-11-1011-*.vbrief.json`.\nThe project's two-layer mitigation:\n- ! **Layer 1 (env)** -- the root `Taskfile.yml` `env:` block sets `UV_PROJECT: '{{.TASKFILE_DIR}}'`. This is the safety net for any task that forgets the CLI flag in a future edit.\n- ! **Layer 2 (CLI)** -- every `uv run` invocation in `tasks/*.yml` and the root `Taskfile.yml` uses the explicit `uv --project \"<pin>\" run ...` form. Subfiles pin against `{{.DEFT_ROOT}}` (defined via `{{joinPath .TASKFILE_DIR \"..\"}}`); the root `Taskfile.yml` pins against `{{.TASKFILE_DIR}}` directly. CLI beats env beats walk, so the flag is the contract; the env var is defense-in-depth.\n- \u2297 Add a plain `uv run` line to any framework task -- the content guard in `tests/content/test_taskfile_uv_project_pin.py` will fail closed and the consumer-side breakage class returns immediately.\n- \u2297 Rely on cwd or a caller-exported `UV_PROJECT` to pin the project root. Task's `env:` does not override an already-exported `UV_PROJECT` from the caller's shell, and propagation through included subfiles depends on inclusion semantics. The CLI flag is unconditional.\nCross-references: `Taskfile.yml` (Layer 1 env block), `tasks/*.yml` (Layer 2 call sites), `tests/content/test_taskfile_uv_project_pin.py` (deterministic content + slow behaviour regression).\n"
+      "body": "# Toolchain Validation\n\nRules for verifying that required tools are installed and functional before beginning implementation.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**⚠️ See also**:\n- [coding.md](coding.md) — Build Automation section\n- [build-output.md](build-output.md) — post-build artifact validation\n\n## Pre-Implementation Gate\n\n- ! Before beginning implementation, verify all required toolchain components are installed and functional\n- ! Required components vary by project — at minimum verify: task runner, language compiler/runtime, and platform SDK if applicable\n- ! If any required tool is missing or non-functional, stop and report — do not proceed with implementation\n- ⊗ Assume a tool is available because it was present in a previous session or referenced in the spec\n- ⊗ Proceed with implementation when the build or test toolchain is unavailable\n\n## What to Verify\n\n- ! Task runner: `task --version` (required for quality gates)\n- ! Language runtime/compiler: e.g. `go version`, `python --version`, `node --version`, `swift --version`\n- ! Platform SDK (if applicable): e.g. `xcode-select -p` for iOS/macOS, Android SDK path for Android\n- ! Project-specific tools listed in PROJECT.md or SPECIFICATION.md\n\n## On Missing Tools\n\n- ! Report exactly which tools are missing and provide install guidance\n- ! Do not partially implement using available tools while skipping quality gates\n- ~ Offer to help install missing tools if the user consents\n## uv Project Pinning (#1011)\n**Why this rule exists:** without an explicit pin, `uv run` walks upward from cwd looking for the nearest `pyproject.toml` and binds to whatever it finds first. When a deft consumer's repo root has no `pyproject.toml` of its own (the common case for non-Python projects), uv escapes the framework directory and resolves to an ancestor workspace `pyproject.toml`. That ancestor's build backend (frequently unresolvable in the consumer environment) crashes during environment resolution before any framework task body runs. The root-cause analysis lives in `vbrief/active/2026-05-11-1011-*.vbrief.json`.\nThe project's two-layer mitigation:\n- ! **Layer 1 (env)** -- the root `Taskfile.yml` `env:` block sets `UV_PROJECT: '{{.TASKFILE_DIR}}'`. This is the safety net for any task that forgets the CLI flag in a future edit.\n- ! **Layer 2 (CLI)** -- every `uv run` invocation in `tasks/*.yml` and the root `Taskfile.yml` uses the explicit `uv --project \"<pin>\" run ...` form. Subfiles pin against `{{.DEFT_ROOT}}` (defined via `{{joinPath .TASKFILE_DIR \"..\"}}`); the root `Taskfile.yml` pins against `{{.TASKFILE_DIR}}` directly. CLI beats env beats walk, so the flag is the contract; the env var is defense-in-depth.\n- ⊗ Add a plain `uv run` line to any framework task -- the content guard in `tests/content/test_taskfile_uv_project_pin.py` will fail closed and the consumer-side breakage class returns immediately.\n- ⊗ Rely on cwd or a caller-exported `UV_PROJECT` to pin the project root. Task's `env:` does not override an already-exported `UV_PROJECT` from the caller's shell, and propagation through included subfiles depends on inclusion semantics. The CLI flag is unconditional.\nCross-references: `Taskfile.yml` (Layer 1 env block), `tasks/*.yml` (Layer 2 call sites), `tests/content/test_taskfile_uv_project_pin.py` (deterministic content + slow behaviour regression).\n"
     },
     {
       "id": "toolchain-002",
       "tier": "MUST",
       "domain": "toolchain",
-      "text": "Required components vary by project \u2014 at minimum verify: task runner, language compiler/runtime, and platform SDK if applicable",
+      "text": "Required components vary by project — at minimum verify: task runner, language compiler/runtime, and platform SDK if applicable",
       "path": "coding/toolchain.md",
       "body": null
     },
@@ -3103,7 +3103,7 @@
       "id": "toolchain-003",
       "tier": "MUST",
       "domain": "toolchain",
-      "text": "If any required tool is missing or non-functional, stop and report \u2014 do not proceed with implementation",
+      "text": "If any required tool is missing or non-functional, stop and report — do not proceed with implementation",
       "path": "coding/toolchain.md",
       "body": null
     },
@@ -3359,7 +3359,7 @@
       "id": "agents-019",
       "tier": "MUST",
       "domain": "agents",
-      "text": "Before designing a multi-step workflow from scratch, scan `content/skills/` for an existing skill that covers the task \u2014 skills are versioned, tested, and encode lessons from prior runs",
+      "text": "Before designing a multi-step workflow from scratch, scan `content/skills/` for an existing skill that covers the task — skills are versioned, tested, and encode lessons from prior runs",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3551,7 +3551,7 @@
       "id": "agents-043",
       "tier": "MUST_NOT",
       "domain": "agents",
-      "text": "Begin editing files before checking scope vBRIEF coverage and creating a feature branch \u2014 even if the user says \"yes\" or \"proceed\"",
+      "text": "Begin editing files before checking scope vBRIEF coverage and creating a feature branch — even if the user says \"yes\" or \"proceed\"",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3575,7 +3575,7 @@
       "id": "agents-046",
       "tier": "MUST",
       "domain": "agents",
-      "text": "Always work on a feature branch \u2014 never commit directly to master/main unless the user explicitly instructs it or `PROJECT-DEFINITION.vbrief.json` has `plan.policy.allowDirectCommitsToMaster = true` (typed flag, #746). The legacy `Allow direct commits to master:` narrative key is recognised at read time with a deprecation warning; new writes go through the typed surface only.",
+      "text": "Always work on a feature branch — never commit directly to master/main unless the user explicitly instructs it or `PROJECT-DEFINITION.vbrief.json` has `plan.policy.allowDirectCommitsToMaster = true` (typed flag, #746). The legacy `Allow direct commits to master:` narrative key is recognised at read time with a deprecation warning; new writes go through the typed surface only.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3663,7 +3663,7 @@
       "id": "agents-057",
       "tier": "MUST",
       "domain": "agents",
-      "text": "On PS 5.1, MUST use Python `pathlib` for all file edits touching non-ASCII glyphs (em dashes, arrows, \u2297, \u2713, \u2026, smart quotes, etc.) -- never `Get-Content -Raw` / `Set-Content` / inline `-replace` / backtick-n interpolation",
+      "text": "On PS 5.1, MUST use Python `pathlib` for all file edits touching non-ASCII glyphs (em dashes, arrows, ⊗, ✓, …, smart quotes, etc.) -- never `Get-Content -Raw` / `Set-Content` / inline `-replace` / backtick-n interpolation",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3687,7 +3687,7 @@
       "id": "agents-060",
       "tier": "MUST_NOT",
       "domain": "agents",
-      "text": "Round-trip a file containing non-ASCII content through PS 5.1 commands (`Get-Content` \u2192 `-replace` \u2192 `Set-Content`, `Get-Content` \u2192 string concat \u2192 `WriteAllText`, here-strings interpolating non-ASCII) -- the read-side decode corrupts the bytes regardless of how the write side is encoded",
+      "text": "Round-trip a file containing non-ASCII content through PS 5.1 commands (`Get-Content` → `-replace` → `Set-Content`, `Get-Content` → string concat → `WriteAllText`, here-strings interpolating non-ASCII) -- the read-side decode corrupts the bytes regardless of how the write side is encoded",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3911,7 +3911,7 @@
       "id": "agents-088",
       "tier": "MUST",
       "domain": "agents",
-      "text": "Within a single review cycle, toggle PR Draft\u2194Ready state at most once. Once Ready, stay Ready unless a P0 finding demands a re-Draft -- each toggle costs a GraphQL mutation and stale Draft re-toggles are the documented failure mode for the PR #652-class merge cascades.",
+      "text": "Within a single review cycle, toggle PR Draft↔Ready state at most once. Once Ready, stay Ready unless a P0 finding demands a re-Draft -- each toggle costs a GraphQL mutation and stale Draft re-toggles are the documented failure mode for the PR #652-class merge cascades.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3919,7 +3919,7 @@
       "id": "agents-089",
       "tier": "MUST",
       "domain": "agents",
-      "text": "Before any GraphQL-heavy operation (PR readiness check, review polling, batch issue ingest, mass `gh pr list`), probe `gh api rate_limit` (the live, uncached form) and inspect `graphql.remaining`. If < 500, switch to REST equivalents or batch+wait until the bucket resets. The decision tree lives in `content/templates/agent-prompt-preamble.md` \u00a7 7. Do NOT use `ghx api rate_limit` for the throttle probe -- ghx is a cached read-only GET proxy, so the cached value can be stale; under N-concurrent-workers the GraphQL bucket can deplete within minutes between probe and use, causing an agent to proceed into GraphQL-heavy work against an exhausted bucket.",
+      "text": "Before any GraphQL-heavy operation (PR readiness check, review polling, batch issue ingest, mass `gh pr list`), probe `gh api rate_limit` (the live, uncached form) and inspect `graphql.remaining`. If < 500, switch to REST equivalents or batch+wait until the bucket resets. The decision tree lives in `content/templates/agent-prompt-preamble.md` § 7. Do NOT use `ghx api rate_limit` for the throttle probe -- ghx is a cached read-only GET proxy, so the cached value can be stale; under N-concurrent-workers the GraphQL bucket can deplete within minutes between probe and use, causing an agent to proceed into GraphQL-heavy work against an exhausted bucket.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3927,7 +3927,7 @@
       "id": "agents-090",
       "tier": "MUST",
       "domain": "agents",
-      "text": "Dispatcher-level lifecycle hygiene: workers MUST be all-or-nothing on their dispatch envelope. Mid-scope user-approval gates require two separate dispatches (Scope A \u2192 worker reports back \u2192 user approves \u2192 Scope B). A worker that finishes its tool loop while emitting a \"paused, awaiting reply\" status message will be observed as `succeeded` (terminal) by the platform; its `agent_id` then becomes unreachable and reply messages have no live runtime to deliver to. Splitting at the gate is the only enforceable mitigation. See `content/templates/agent-prompt-preamble.md` \u00a7 9.",
+      "text": "Dispatcher-level lifecycle hygiene: workers MUST be all-or-nothing on their dispatch envelope. Mid-scope user-approval gates require two separate dispatches (Scope A → worker reports back → user approves → Scope B). A worker that finishes its tool loop while emitting a \"paused, awaiting reply\" status message will be observed as `succeeded` (terminal) by the platform; its `agent_id` then becomes unreachable and reply messages have no live runtime to deliver to. Splitting at the gate is the only enforceable mitigation. See `content/templates/agent-prompt-preamble.md` § 9.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3951,7 +3951,7 @@
       "id": "agents-093",
       "tier": "MUST",
       "domain": "agents",
-      "text": "**Worker-owns-lifecycle (Gap C):** When dispatching an implementation worker, the envelope MUST declare `stop-at: pr-open` OR `drive-to: merge-ready` (default for story work). Workers scoped `drive-to: merge-ready` own PR + review cycle + fix batches through merge-ready as ONE unit of work \u2014 they spawn their own review poller per review-cycle monitoring tiers; the orchestrator MUST NOT hand back at PR-open and re-dispatch separate leaf agents for review/fixes.",
+      "text": "**Worker-owns-lifecycle (Gap C):** When dispatching an implementation worker, the envelope MUST declare `stop-at: pr-open` OR `drive-to: merge-ready` (default for story work). Workers scoped `drive-to: merge-ready` own PR + review cycle + fix batches through merge-ready as ONE unit of work — they spawn their own review poller per review-cycle monitoring tiers; the orchestrator MUST NOT hand back at PR-open and re-dispatch separate leaf agents for review/fixes.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -3967,7 +3967,7 @@
       "id": "agents-095",
       "tier": "MUST",
       "domain": "agents",
-      "text": "**Deliberate model routing:** Before ANY sub-agent dispatch (cohort OR single), make a deliberate per-`worker_role` routing decision via `task verify:routing` / `task swarm:routing-set` \u2014 never silently inherit the parent model. Deterministic gate enforcement is #1877; this bullet is behavioral doctrine only.",
+      "text": "**Deliberate model routing:** Before ANY sub-agent dispatch (cohort OR single), make a deliberate per-`worker_role` routing decision via `task verify:routing` / `task swarm:routing-set` — never silently inherit the parent model. Deterministic gate enforcement is #1877; this bullet is behavioral doctrine only.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -4015,7 +4015,7 @@
       "id": "agents-101",
       "tier": "MUST_NOT",
       "domain": "agents",
-      "text": "Do NOT delete prior amendment comments when updating the current-shape comment \u2014 they remain the audit trail.",
+      "text": "Do NOT delete prior amendment comments when updating the current-shape comment — they remain the audit trail.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -4023,7 +4023,7 @@
       "id": "agents-102",
       "tier": "MUST_NOT",
       "domain": "agents",
-      "text": "Do NOT replace the current-shape comment with a fresh comment \u2014 it must be edited in place so its permalink is stable.",
+      "text": "Do NOT replace the current-shape comment with a fresh comment — it must be edited in place so its permalink is stable.",
       "path": "AGENTS.md",
       "body": null
     },
@@ -4071,7 +4071,7 @@
       "id": "main-006",
       "tier": "SHOULD",
       "domain": "main",
-      "text": "Be direct, critical, and constructive \u2014 say when suboptimal, propose better options",
+      "text": "Be direct, critical, and constructive — say when suboptimal, propose better options",
       "path": "main.md",
       "body": null
     },
@@ -4103,7 +4103,7 @@
       "id": "main-010",
       "tier": "MUST",
       "domain": "main",
-      "text": "Prose is fallback only \u2014 never preferred when a stronger form applies.",
+      "text": "Prose is fallback only — never preferred when a stronger form applies.",
       "path": "main.md",
       "body": null
     },
@@ -4151,7 +4151,7 @@
       "id": "main-016",
       "tier": "MUST",
       "domain": "main",
-      "text": "Before implementing any planned change that touches 3+ files or has an accepted plan artifact, propose `/deft:change <name>` and present the change name for explicit confirmation (e.g. \"Confirm? yes/no\") \u2014 the user must reply with an affirmative (`yes`, `confirmed`, `approve`) to satisfy this gate; a broad 'proceed', 'do it', or 'go ahead' does NOT satisfy it",
+      "text": "Before implementing any planned change that touches 3+ files or has an accepted plan artifact, propose `/deft:change <name>` and present the change name for explicit confirmation (e.g. \"Confirm? yes/no\") — the user must reply with an affirmative (`yes`, `confirmed`, `approve`) to satisfy this gate; a broad 'proceed', 'do it', or 'go ahead' does NOT satisfy it",
       "path": "main.md",
       "body": null
     },
@@ -4167,7 +4167,7 @@
       "id": "main-018",
       "tier": "MUST",
       "domain": "main",
-      "text": "No implementation is complete until tests are written and the project quality gate passes (`task deft:check` in consumer projects using the canonical include; `task check` inside the directive repo) \u2014 this gate applies unconditionally and a general 'proceed' instruction does not waive it. This gate has two dimensions: (a) **regression coverage** -- existing tests continue to pass, and (b) **forward coverage** -- new source files (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`) have corresponding new test files that exercise the new code paths. Running existing tests alone satisfies (a) but not (b)",
+      "text": "No implementation is complete until tests are written and the project quality gate passes (`task deft:check` in consumer projects using the canonical include; `task check` inside the directive repo) — this gate applies unconditionally and a general 'proceed' instruction does not waive it. This gate has two dimensions: (a) **regression coverage** -- existing tests continue to pass, and (b) **forward coverage** -- new source files (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`) have corresponding new test files that exercise the new code paths. Running existing tests alone satisfies (a) but not (b)",
       "path": "main.md",
       "body": null
     },
@@ -4175,7 +4175,7 @@
       "id": "main-019",
       "tier": "MUST_NOT",
       "domain": "main",
-      "text": "Commit or push directly to the default branch (master/main) \u2014 always create a feature branch and open a PR, even for single-commit changes. The only exception is if the user **explicitly** instructs a direct commit for the current task, or if `PROJECT-DEFINITION.vbrief.json` has `plan.policy.allowDirectCommitsToMaster = true` (typed flag, #746). The legacy `Allow direct commits to master:` narrative key is recognised at read time with a deprecation warning; new writes go through the typed surface only. Three enforcement surfaces back this rule (#747): (1) `.githooks/pre-commit` and `.githooks/pre-push` hooks calling `scripts/preflight_branch.py` (install with `task deft:setup` in consumer projects using the canonical include); (2) `task deft:verify:branch` wired into the `task deft:check` aggregate for consumers; (3) the `branch-gate` GH Actions workflow rejecting PRs where `head_ref == base_ref`. Override paths: `task deft:policy:allow-direct-commits -- --confirm` (typed flag, audited to `meta/policy-changes.log`) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` (emergency env-var bypass). In the directive repo itself, the same tasks are valid without the `deft:` prefix. See [`contracts/deterministic-questions.md`](./content/contracts/deterministic-questions.md) for the canonical Discuss/Back rule that governs every numbered-menu prompt across deft skills (#767).",
+      "text": "Commit or push directly to the default branch (master/main) — always create a feature branch and open a PR, even for single-commit changes. The only exception is if the user **explicitly** instructs a direct commit for the current task, or if `PROJECT-DEFINITION.vbrief.json` has `plan.policy.allowDirectCommitsToMaster = true` (typed flag, #746). The legacy `Allow direct commits to master:` narrative key is recognised at read time with a deprecation warning; new writes go through the typed surface only. Three enforcement surfaces back this rule (#747): (1) `.githooks/pre-commit` and `.githooks/pre-push` hooks calling `scripts/preflight_branch.py` (install with `task deft:setup` in consumer projects using the canonical include); (2) `task deft:verify:branch` wired into the `task deft:check` aggregate for consumers; (3) the `branch-gate` GH Actions workflow rejecting PRs where `head_ref == base_ref`. Override paths: `task deft:policy:allow-direct-commits -- --confirm` (typed flag, audited to `meta/policy-changes.log`) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` (emergency env-var bypass). In the directive repo itself, the same tasks are valid without the `deft:` prefix. See [`contracts/deterministic-questions.md`](./content/contracts/deterministic-questions.md) for the canonical Discuss/Back rule that governs every numbered-menu prompt across deft skills (#767).",
       "path": "main.md",
       "body": null
     },
@@ -4183,7 +4183,7 @@
       "id": "main-020",
       "tier": "MUST_NOT",
       "domain": "main",
-      "text": "Fix a discovered issue in-place mid-task without filing a GitHub issue \u2014 always file the issue and continue the current task; do not derail the active workflow to apply an instant fix (#198). **Carve-out**: if the discovered issue is a hard blocker (the current task literally cannot be completed without fixing it), fixing it in-scope is permitted, but a GitHub issue MUST be filed before or alongside the fix; nice-to-fix, quality improvements, and adjacent issues remain prohibited (#241)",
+      "text": "Fix a discovered issue in-place mid-task without filing a GitHub issue — always file the issue and continue the current task; do not derail the active workflow to apply an instant fix (#198). **Carve-out**: if the discovered issue is a hard blocker (the current task literally cannot be completed without fixing it), fixing it in-scope is permitted, but a GitHub issue MUST be filed before or alongside the fix; nice-to-fix, quality improvements, and adjacent issues remain prohibited (#241)",
       "path": "main.md",
       "body": null
     },
@@ -4191,7 +4191,7 @@
       "id": "main-021",
       "tier": "MUST_NOT",
       "domain": "main",
-      "text": "Continue executing a skill past its explicit instruction boundary \u2014 when a skill's steps are complete, stop and return to the calling context; do not drift into adjacent work (#198)",
+      "text": "Continue executing a skill past its explicit instruction boundary — when a skill's steps are complete, stop and return to the calling context; do not drift into adjacent work (#198)",
       "path": "main.md",
       "body": null
     },
@@ -4199,7 +4199,7 @@
       "id": "main-022",
       "tier": "MUST",
       "domain": "main",
-      "text": "The end of a skill's final step is an exit condition \u2014 do not continue into adjacent work, even if it seems related or trivial",
+      "text": "The end of a skill's final step is an exit condition — do not continue into adjacent work, even if it seems related or trivial",
       "path": "main.md",
       "body": null
     },
@@ -4391,7 +4391,7 @@
       "id": "main-046",
       "tier": "MUST",
       "domain": "main",
-      "text": "All vBRIEF files MUST be stored in `./vbrief/` or its lifecycle subfolders \u2014 never in workspace root",
+      "text": "All vBRIEF files MUST be stored in `./vbrief/` or its lifecycle subfolders — never in workspace root",
       "path": "main.md",
       "body": null
     },
@@ -4399,7 +4399,7 @@
       "id": "main-047",
       "tier": "MUST",
       "domain": "main",
-      "text": "Use `PROJECT-DEFINITION.vbrief.json` (singular) as the project identity gestalt \u2014 narratives for identity, items as scope registry",
+      "text": "Use `PROJECT-DEFINITION.vbrief.json` (singular) as the project identity gestalt — narratives for identity, items as scope registry",
       "path": "main.md",
       "body": null
     },
@@ -4471,7 +4471,7 @@
       "id": "main-056",
       "tier": "MUST_NOT",
       "domain": "main",
-      "text": "Write `SPECIFICATION.md` directly \u2014 it MUST be generated from `specification.vbrief.json`",
+      "text": "Write `SPECIFICATION.md` directly — it MUST be generated from `specification.vbrief.json`",
       "path": "main.md",
       "body": null
     },
@@ -4567,7 +4567,7 @@
       "id": "main-068",
       "tier": "SHOULD",
       "domain": "main",
-      "text": "Run a `--dry-run` pass first on any project with non-trivial SPEC / ROADMAP content so you can read `RECONCILIATION.md` / `LEGACY-REPORT.md` before committing to the change. Backups (`.premigrate.*`) are always created before any destructive write \u2014 `--rollback` restores them.",
+      "text": "Run a `--dry-run` pass first on any project with non-trivial SPEC / ROADMAP content so you can read `RECONCILIATION.md` / `LEGACY-REPORT.md` before committing to the change. Backups (`.premigrate.*`) are always created before any destructive write — `--rollback` restores them.",
       "path": "main.md",
       "body": null
     },