@deftai/directive-content 0.55.0

package/coding/coding.md

@@ -0,0 +1,235 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Coding Guidelines
+
+Software development specific guidelines for AI agents.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also** (load only when needed):
+- [../main.md](../../main.md) - General AI behavior and agent persona
+- [PROJECT.md](../../PROJECT.md) - For project-specific overrides
+- [../tools/telemetry.md](../tools/telemetry.md) - When implementing logging/tracing/metrics
+
+## Code Organization
+
+**Documentation:**
+- ! All *.md in `docs/` directory (except README.md, AGENTS.md, WARP.md)
+- ! Prior tasks/plans in `history/`
+
+**Filenames:**
+- ~ Use hyphens not underscores (unless language idiom)
+
+**Secrets:**
+- ! ALL secrets in `secrets/` dir as .env files
+- ⊗ Secrets in code
+
+## Code Search
+
+- ! use `rg`, or `ast-grep` (when available) instead of grep
+- ! Use Warp's built-in grep (which is rg) when running on warp
+- ~ Install if missing
+- ? Fall back to `grep` command only if tools cannot be installed
+
+## Version Control
+
+See [../scm/git.md](../scm/git.md) for:
+- Commit conventions (Conventional Commits)
+- Safety rules (no force-push without permission)
+- Branch workflows
+
+## Code Design
+
+**Modularity:**
+- ! One responsibility per file/module
+- ~ Files <300 lines ideal; <500 lines recommended; <1000 lines a review trigger — split when exceeded unless genuinely single-responsibility (size is a smell, not a hard cap; #1488)
+- ! Explicit scope in task descriptions
+- ~ DRY: extract shared abstractions when logic is duplicated across 2+ call sites
+- ⊗ Copy-paste logic with minor variations — parameterise instead
+
+**Dependency Direction:**
+- ⊗ Circular imports between modules/packages
+- ~ Layered architecture: high-level modules depend on low-level ones, never the reverse
+- ! Use dependency inversion (interfaces/protocols) to break coupling across layers
+- See [hygiene.md](hygiene.md) for detection tools (madge, pydeps, Go compiler)
+
+**Contract-First:**
+- ! Define interfaces/types/protocols before implementation
+- ! Changes to public interfaces require explicit versioning or deprecation path
+- ! Document all public API contracts clearly
+
+**Immutability:**
+- ~ Prefer immutable data + pure functions
+- ~ When mutation needed, use narrow owned scopes (context managers, RAII)
+- ⊗ Global or singleton mutable state (almost always)
+
+**Error Handling:**
+- ~ Prefer Result/Option types or explicit exceptions over None/null/undefined
+- ! Document possible exceptions/error codes for all public functions
+- ! Validate all inputs at API boundaries
+- ⊗ Trust caller without validation
+- ⊗ Empty catch/except/recover blocks that swallow errors silently
+- ⊗ Returning neutral/zero values (None, {}, [], 0, false, "") to mask errors — propagate explicitly
+- ⊗ Log-and-continue: catching an error and proceeding as if it didn't happen, unless provably non-fatal and documented
+- See [hygiene.md](hygiene.md) for full error-hiding anti-pattern catalogue
+
+**Readability:**
+- ! Follow language idioms strictly
+- ! Meaningful names over short names
+- ! Comments explain **why**, code shows **what**
+- ⊗ Clever code over clear code
+
+## Quality Standards
+
+**General:**
+- ! Run all relevant checks (lint, fmt, quality, build, test) before submitting changes
+- ⊗ Claim checks passed without running them
+- ! If checks cannot run, explicitly state why and what would have been executed
+- ~ Prioritize code quality and readability over backwards compatibility
+
+**Testing:**
+- ! Implementation is INCOMPLETE until tests written AND `task test:coverage` passes
+- See [../coding/testing.md](../coding/testing.md) for universal requirements
+
+**Security:**
+- ! Apply baseline security standards to every project from day one
+- See [../coding/security.md](../coding/security.md) for input validation, authn/authz, secrets, dependency, and agent-specific threats (#661)
+
+**Codebase Hygiene:**
+- See [hygiene.md](hygiene.md) for: dead code removal, circular dependency detection, error hiding patterns, legacy/deprecated code cleanup
+
+**Telemetry:**
+- See [../tools/telemetry.md](../tools/telemetry.md) for recommendations
+- ~ Structured logging for production
+- ~ Error tracking (Sentry.io or equivalent)
+- ? Distributed tracing for complex systems
+
+## Fail Loud: Completion Claims Require Outcome Verification (#1006)
+
+The 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.
+
+This 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").
+
+- ! 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")
+- ! 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
+- ! 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")
+- ! 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)
+- ! 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")
+- ⊗ MUST NOT claim "tests pass" when any test was skipped, xfailed, or run with errors suppressed -- report the full counts instead
+- ⊗ MUST NOT claim "migration completed" / "batch succeeded" / "job finished" without checking and reporting the per-record outcome counts
+- ⊗ 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
+- ⊗ MUST NOT use successful-sounding completion phrasing to paper over uncertainty -- default to surfacing uncertainty, not hiding it
+- ⊗ 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
+
+The rule applies to agent completion claims during task execution. It applies equally to claims to the user, claims in commit messages, claims in PR bodies, claims in CHANGELOG entries, and claims in status messages to a parent agent. A short, honest "the migration completed; I did not verify the per-record count" is strictly preferred over a confident "migration completed successfully" that hides the gap.
+
+**Cross-references:** `## 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).
+
+## Calling LLM APIs (#481)
+
+When 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:
+
+- ! User input is NEVER placed in the system prompt; the system prompt is the trust boundary
+- ! External content is ALWAYS wrapped in explicit delimiters (`<user_input>`, `<document>`, `<tool_result>`) and surfaces its trust tier
+- ! Tool call arguments are validated against a schema BEFORE execution (the LLM is a confused deputy)
+- ! LLM outputs are validated against expected schemas before being acted upon (no eval-of-output, no shell-of-output, no SQL-of-output)
+- ⊗ MUST NOT write LLM outputs back into the retrieval corpus in the same session without validation (RAG poisoning vector)
+
+See [../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.
+
+## Debugging and Root-Cause Investigation (#1621)
+
+When a bug, failure, or unexpected behaviour needs diagnosis, the root-cause standards in `debugging.md` apply. The short form:
+
+- ! No fixes without root-cause investigation first (the Iron Law)
+- ! Reproduce the failure consistently before proposing a fix — a non-reproducible bug is not yet understood
+- ! Every factual claim cites evidence; an uncited claim is a `[HYPOTHESIS]`, not a finding (evidence before narrative)
+- ! Runtime/config values are proven from the runtime, never inferred from source code (config is not code)
+- ⊗ 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)
+- ! After 3 failed distinct fixes, STOP and escalate for architectural review (the 3-fix gate)
+
+See [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.
+
+## Build Automation
+
+**Taskfile:**
+- ! Use Task ([go-task](https://taskfile.dev)) for all repeatable operations
+- ! If `task` not found, attempt to install go-task
+- ! If installation fails, stop and ask user for help
+- See [../tools/taskfile.md](../tools/taskfile.md) for standards and common commands
+
+**Toolchain Validation:**
+- See [../coding/toolchain.md](../coding/toolchain.md) for rules on verifying required tools are installed before implementation begins
+
+**Build Output Validation:**
+- See [../coding/build-output.md](../coding/build-output.md) for rules on verifying `dist/` artifacts and non-compiled assets after custom build scripts run
+
+## Change Management
+
+**Impact Awareness:**
+- ! Before changing shared code, identify affected downstream modules/files
+- ~ Prefer additive changes (new functions, fields with defaults) over breaking renames
+- ! Make small, reversible changes
+- ! Explain impact and migration path for breaking changes
+
+**Production Safety:**
+- ! Assume production impact unless stated otherwise
+- ! Call out risk when touching: auth, billing, data, APIs, build systems
+- ⊗ Silent breaking behavior
+- ~ Test changes in staging/dev environment when possible
+
+## Language-Specific Guidelines
+
+**Languages:**
+- C++: [../languages/cpp.md](../languages/cpp.md)
+- Go: [../languages/go.md](../languages/go.md)
+- Office.js: [../languages/officejs.md](../languages/officejs.md)
+- Python: [../languages/python.md](../languages/python.md)
+- TypeScript: [../languages/typescript.md](../languages/typescript.md)
+- VBA: [../languages/vba.md](../languages/vba.md)
+
+**Interface Types:**
+- CLI: [../interfaces/cli.md](../interfaces/cli.md)
+- TUI: [../interfaces/tui.md](../interfaces/tui.md)
+- Web: [../interfaces/web.md](../interfaces/web.md)
+- REST API: [../interfaces/rest.md](../interfaces/rest.md)
+
+## Development Workflow
+
+**Localhost:**
+- No permission needed for curl localhost
+
+**Plans:**
+- ~ Create both:
+  1. Warp plan (using `create_plan` tool)
+  2. Archive copy in `history/plan-YYYY-MM-DD-description.md`
+
+## Project Context
+
+- ! Check [PROJECT.md](../../PROJECT.md) for project-specific overrides
+- ~ Inspect project config (package.json, pyproject.toml, etc.) for available scripts
+- ! Follow project-specific testing, coverage, and quality requirements
+
+## Anti-Patterns
+
+- ⊗ Secrets in code or version control
+- ⊗ Claiming checks passed without running them
+- ⊗ Single files mixing multiple responsibilities (large line count, e.g. >1000 lines, is a trigger to check cohesion — not a defect by itself; #1488)
+- ⊗ Skipping quality checks
+- ⊗ Breaking changes without explicit approval
+- ⊗ Using `grep` command when `rg` or Warp grep available
+- ⊗ Implementing code without tests
+- ⊗ Claiming "done" before running test:coverage
+- ⊗ Ignoring coverage drops
+- ⊗ Weak types (`any`, `interface{}`, untyped `object`) where concrete types are knowable
+- ⊗ Dead code: unused functions, unreachable branches, stale feature flags, commented-out blocks
+- ⊗ Error hiding: empty catch blocks, silent fallbacks, swallowed exceptions
+- ⊗ Circular imports between modules
+- ⊗ Duplicate logic across 2+ call sites without shared abstraction
+- ⊗ 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)
+- ⊗ Averaging contradicting codebase patterns: writing new code that satisfies both of two conflicting patterns simultaneously (#1005 -- see `hygiene.md` `## Surface Conflicts`)
+- ⊗ 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`)

package/coding/debugging.md

@@ -0,0 +1,110 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Debugging and Root-Cause Investigation (#1621)
+
+Systematic root-cause process for AI agents. The failure mode this file prevents
+is **thrashing**: retrying random fixes, fixing before understanding, and
+treating the first plausible hypothesis as correct. Debugging is an
+evidence-discipline, not a guess-and-check loop.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+For a sustained, multi-agent investigation posture (claim ledger, falsification
+waves, validator gate), see the `deft-directive-debug` skill and the vendored
+reference design under `docs/reference/forensic-research/`.
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT-CAUSE INVESTIGATION FIRST
+```
+
+- ! Before proposing or writing any fix, the root cause MUST be identified with evidence.
+- ⊗ MUST NOT propose a fix while the investigation phase is incomplete — violating the letter of this process is violating the spirit of debugging.
+
+## The Four Phases
+
+Each phase MUST complete before the next begins.
+
+### Phase 1 — Root-Cause Investigation
+- ! Read the error message completely before doing anything else.
+- ! Reproduce the failure consistently — a non-reproducible bug is not yet understood.
+- ! Check recent changes (what changed when the symptom appeared?).
+- ! Gather evidence at component boundaries — add diagnostic instrumentation before proposing fixes.
+- ! Trace data flow backward from the symptom toward the cause.
+
+### Phase 2 — Pattern Analysis
+- ! Find a working example of similar functionality in the codebase.
+- ! Compare the failing path against the working reference and identify what is structurally different.
+- ~ Look for the pattern, not just the instance.
+
+### Phase 3 — Hypothesis Testing
+- ! Form one hypothesis and test it minimally.
+- ! Change one variable at a time.
+- ! Confirm the fix addresses the root cause, not just the symptom.
+
+### Phase 4 — Implementation
+- ! Write a failing test that demonstrates the bug.
+- ! Implement the single fix.
+- ! Verify the test passes and that no regressions were introduced.
+
+## The 3-Fix Architecture Gate
+
+- ! If 3 or more distinct fixes have failed, STOP. MUST NOT attempt a fourth fix.
+- ! Escalate with: "N fixes attempted, root cause not found — architectural review needed." The architecture may be the problem.
+
+## Multi-Component Systems
+
+- ! Before proposing fixes in a multi-component system, add diagnostic instrumentation at every boundary to observe the actual data flow.
+- ⊗ MUST NOT guess which component is at fault without boundary evidence.
+
+## Evidence Discipline (forensic rigor)
+
+These rules raise the four-phase loop from "structured guessing" to
+evidence-based investigation. They are adapted from the vendored
+`forensic-research` reference design.
+
+- ! **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.
+- ! **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.
+- ! **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.
+- ! **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.
+- ⊗ **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.
+
+## Fact vs Hypothesis Labeling
+
+- ! 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).
+- ! A finding labeled Fact MUST carry its evidence citation.
+
+This is the debugging-side adoption of the review/triage labeling vocabulary
+owned by #1580 — that issue remains the owner of the review-cycle and triage
+findings-format surface; this file is a consumer of the shared vocabulary.
+
+## Observability Gaps (close the loop)
+
+- ! 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.
+- ~ Treat each investigation as an opportunity to improve the system's telemetry, not just to land a fix.
+
+## Rationalization Table
+
+| Excuse | Reality |
+|---|---|
+| "This seems obvious" | Obvious bugs have root causes too |
+| "I'll investigate if this fix doesn't work" | The first fix sets the pattern — investigate first |
+| "We're under time pressure" | Rushing guarantees rework; systematic is faster than thrashing |
+| "One more fix attempt" | 3+ failures = architectural problem; question the pattern |
+| "No evidence, so it's not that" | No evidence means `unknown`, not ruled out |
+
+## Anti-Patterns
+
+- ⊗ Fixing before reproducing the failure
+- ⊗ Cargo-cult debugging: changing things until it works, with no understanding of why
+- ⊗ Treating the first plausible hypothesis as confirmed without testing it
+- ⊗ Skipping Phase 2 because a fix seems obvious
+- ⊗ Presenting a duration or an exit status as a root cause (tautology)
+- ⊗ Inferring a runtime config value from source code instead of proving it at runtime
+- ⊗ Marking a theory "ruled out" without counter-evidence
+- ⊗ A fourth fix attempt after three have failed without an architectural review

package/coding/holzmann.md

@@ -0,0 +1,96 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Power of Ten – Adapted for Deft  
+JPL/NASA-inspired rules for reliable, verifiable code  
+(Original: Gerard J. Holzmann, "The Power of Ten – Rules for Developing Safety-Critical Code", IEEE Computer, June 2006)
+
+**⚠️ See also** (load only when needed):
+- [coding.md](coding.md) - General coding guidelines
+- [../verification/verification.md](../verification/verification.md) - Verification practices (Holzmann ladder)
+
+! These rules MUST be understood as the canonical high-assurance reference for Deft.
+~ Apply the general intent across all languages.  
+~ Put language-specific enforcement, tooling, and exceptions only in languages/*.md files.
+
+## Notation Legend (Deft RFC 2119 compact style)
+! = MUST (required, mandatory)  
+~ = SHOULD (recommended, strong preference)  
+≉ = SHOULD NOT (discouraged, avoid unless justified)  
+⊗ = MUST NOT (forbidden, never do this)
+? = MAY 
+
+## The Adapted Rules
+
+1. Simple control flow  
+   ⊗ Use direct or indirect recursion
+   ~ Use explicit iteration or stacks instead.
+   ⊗ Exotic/non-local jumps (goto where supported, longjmp equivalents, setjmp). 
+   ~ Restrict control flow to basic constructs: if/else, bounded for/while, switch/case/match.  
+   ! Keep code analyzable and provably terminating where possible.
+
+2. Bounded loops  
+   ! Every loop MUST have a statically provable fixed upper bound or mechanically verifiable termination condition.  
+   ⊗ Naked infinite loops (while True:, for {} without escape guarantee) are forbidden.  
+   ~ Prefer for i in range(MAX) / for i := 0; i < MAX; i++ {} patterns wherever practical.  
+   ! Termination guarantee MUST be preserved in all loops.
+
+3. Fixed resource allocation after initialization  
+   ~ Allocate/grow dynamic structures (lists, maps, slices, heaps) during startup/initialization phase only.  
+   ≉ Grow structures (append, map inserts, slice appends) in hot paths or long-running loops unless bounded.  
+   ⊗ Unbounded dynamic allocation/growth in steady-state operation is forbidden (where language-relevant).  
+   ! Resource usage MUST remain predictable after initialization.
+
+4. Small functions  
+   ~ Functions SHOULD be ≤ 40–60 lines (aim for one screen / printed page).
+   ~ Cyclomatic complexity SHOULD be ≤ 10 per function.  
+   ! Small, focused functions MUST be preferred for verifiability and reviewability.
+
+5. Runtime checks & assertions  
+   ~ Every non-trivial function SHOULD include at least two explicit runtime checks/assertions.
+   ~ Use preconditions, postconditions, or invariants via language-native mechanisms.  
+   ! Runtime checks MUST catch violations early in non-trivial logic.
+
+6. Minimal data scope  
+   ! Mutable shared/global state MUST be minimized — prefer local, passed, or immutable data.  
+   ⊗ Unnecessary module/package-level mutable variables (except constants) are forbidden.  
+   ~ Dependency injection or functional style SHOULD be used where practical.  
+   ! Scope reduction MUST reduce coupling and side effects.
+
+7. Error & return checking  
+   ! Non-void return values and error indicators MUST never be ignored.  
+   ! In error-returning languages every error MUST be checked or explicitly propagated.  
+   ⊗ Silent failure / ignored exceptions are forbidden unless explicitly documented as safe.  
+   ! Explicit error handling MUST be enforced.
+
+8. Restricted metaprogramming  
+   ⊗ Complex/multi-level macros or preprocessor abuse are forbidden (C/C++).  
+   ≉ Heavy decorators, metaclasses, or code generation that obscures control flow SHOULD be avoided.  
+   ~ Metaprogramming SHOULD remain minimal and local in safety-critical paths.
+   ! Analyzability MUST be preserved; metaprogramming MUST NOT obscure control flow.
+
+9. Restricted indirection  
+   ⊗ Multi-level pointers / double indirection are forbidden (C/C++ raw pointers).  
+   ≉ Deep pointer chains or excessive indirection SHOULD be avoided in other languages.  
+   ~ Prefer slices, references, or owned types (Rust, Go).  
+   ! Indirection MUST be kept simple to reduce aliasing risk.
+
+10. Maximum static checking  
+    ! Compile/lint with maximum warnings enabled and treat warnings as errors.  
+    ! Strictest static analysis tools available for the language MUST be used.  
+    ! Static checking MUST catch issues at build time.
+
+## Additional Holzmann-inspired Practices
+~ Lightweight, interactive analysis tools SHOULD be preferred (Cobra philosophy).  
+~ Consider adding task cobra target for repo-wide queries (functions >40 lines, unbounded loops).  
+! Verification ladder MUST integrate with verification/ practices.  
+~ Every significant PR SHOULD include a short verifiability note.
+
+## References
+~ Original paper: https://spinroot.com/gerard/pdf/P10.pdf  
+~ Holzmann's SPIN model checker: https://spinroot.com
+
+! This adaptation preserves JPL flight-software reliability philosophy for Deft's layered system.

package/coding/hygiene.md

@@ -0,0 +1,127 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Codebase Hygiene
+
+Rules for ongoing codebase health — keeping existing code clean, not just writing new code well.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**:
+- [coding.md](coding.md) — Code design principles
+- [verification/verification.md](../verification/verification.md) — Stub and legacy detection
+- [coding/testing.md](testing.md) — Test coverage requirements
+
+---
+
+## Dead Code Removal
+
+Dead code accumulates silently and degrades readability and maintainability.
+
+- ! Before marking any refactor or cleanup task done, verify no unreferenced code was left behind
+- ⊗ Commented-out code blocks committed to version control — delete, don't comment out
+- ⊗ Functions, classes, or variables that are defined but never called/imported anywhere
+- ⊗ Unused imports, dependencies, or exports
+- ~ Use language-specific dead code tools as part of periodic hygiene passes:
+  - Python: `vulture` — detects unused functions, classes, variables
+  - Go: `deadcode` (golang.org/x/tools/cmd/deadcode) or `staticcheck` unused analysis
+  - TypeScript/JS: `knip` — detects unused exports, files, and dependencies
+- ~ Run dead code tools before major releases or after significant refactors
+- ? Add dead code tool as a Taskfile target (e.g. `task hygiene`) for periodic use
+
+---
+
+## Circular Dependencies
+
+Circular imports create tight coupling, prevent modular testing, and indicate architectural problems.
+
+- ⊗ Circular imports between modules/packages — detect and eliminate
+- ! When circular dependency exists, resolve by extracting shared types/interfaces to a lower-level module, not by restructuring import order
+- ~ Enforce layered architecture: high-level modules depend on low-level ones, never the reverse
+- ! Use dependency inversion (interfaces/protocols) to break necessary coupling across layers
+- ~ Use language-specific tools to detect cycles:
+  - Python: `pydeps` or `importlab` for full cycle detection
+  - Go: the compiler rejects import cycles — trust the error; fix by extracting shared packages
+  - TypeScript/JS: `madge` — visualises and detects circular dependencies
+- ~ For large codebases, add `madge --circular --exit-code` (or equivalent) as a CI check
+
+---
+
+## Error Handling: No Hiding
+
+Try/catch and equivalent constructs serve a legitimate purpose at **API/input boundaries** — sanitizing unknown or untrusted input. Everywhere else, they should propagate errors explicitly.
+
+**Legitimate uses:**
+- Parsing external input (JSON, user input, file content)
+- Third-party SDK calls that may throw undocumented errors
+- Top-level process handlers (recover from unexpected crashes with logging)
+
+**Illegitimate uses (remove these):**
+
+- ⊗ Empty catch/except/recover blocks that swallow errors silently
+- ⊗ `except Exception: pass` or equivalent — log at minimum, re-raise if appropriate
+- ⊗ Returning neutral/zero values (None, {}, [], 0, false, "") to mask an error — propagate explicitly
+- ⊗ 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
+- ⊗ Fallback patterns that hide failures from callers (e.g. "if this fails, return cached/stale data" without surfacing the error)
+- ! When removing a try/catch, confirm the error propagates to a caller that can handle it — do not simply delete
+
+---
+
+## Legacy and Deprecated Code
+
+Legacy accumulation makes codebases fragile and hard to reason about. Code should have one active path, not a graveyard of old approaches alongside new ones.
+
+- ⊗ Parallel implementations: old approach and new approach coexisting without a migration path
+- ⊗ Feature flags or toggle branches where the flag is always-on or always-off — collapse to the live path
+- ⊗ Compatibility shims maintained beyond their stated removal date
+- ! When replacing an implementation: delete the old one in the same commit, not "after testing"
+- ~ Scan for these markers as legacy indicators:
+  - Comments: `# deprecated`, `// TODO: remove`, `LEGACY`, `COMPAT`, `OLD_`, `# old way`
+  - Python decorators: `@deprecated`
+  - Go: `// Deprecated:` godoc marker (legitimate when part of a public API — remove the symbol if internal)
+- ~ When encountering legacy code during unrelated work, file a hygiene task rather than ignoring it
+- ⊗ 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
+
+---
+
+## Surface Conflicts: Pick One, Explain, Flag the Other (#1005)
+
+When 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.**
+
+- ! 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
+- ! 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)
+- ! 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
+- ⊗ MUST NOT blend the two patterns -- doubled error handlers, dual validation paths, parallel state stores, or any other "satisfy both" shape
+- ⊗ 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
+- ? 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
+
+This 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.
+
+**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).
+
+---
+
+## DRY: Don't Repeat Yourself
+
+Duplication is the root cause of inconsistent behaviour and maintenance burden.
+
+- ~ Extract shared abstractions when logic is duplicated across 2+ call sites
+- ⊗ Copy-paste logic with minor variations — parameterise instead
+- ! When deduplicating, verify the abstraction is actually shared behaviour, not coincidental similarity
+- ≉ Premature abstraction — only extract when the duplication is real and the shared contract is clear
+
+---
+
+## Comments: Signal vs. Noise
+
+Comments should explain **why**, not **what**. Remove noise; keep signal.
+
+- ⊗ Comments describing what the code does (the code itself shows this)
+- ⊗ In-motion commentary: "replaced X with Y", "temporarily disabled", "new approach below"
+- ⊗ Commented-out code — delete it; version control preserves history
+- ⊗ Section dividers and banners that add no information (e.g. `# --- helpers ---`)
+- ! When editing a file, remove stale comments as you go — do not leave them for later
+- ~ When a comment is needed, be concise: one line explaining the non-obvious reason, not a paragraph