# Harden > Hardens post-validation defects and missed gates. Use for bugs; use adjust for deliberate redesign. - Skill: `telum-ai/harden` (Agent Skill) - Install (CLI): `npx skillmds@latest add telum-ai/harden` - Raw SKILL.md: https://api.skillmd.com/api/skills/telum-ai/harden/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: telum-ai (https://skillmd.com/u/telum-ai) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/telum-ai/harden --- # harden > ๐Ÿšฆ **METHODOLOGY INTENT SPLIT**: > - Use `/harden` when something you previously validated/shipped is **broken** (defect, bug, incident). > - Use `/adjust --level story` or `/adjust --level epic` when you have **deliberately changed** what you specified/shipped (redesign, visual overhaul, scope pivot) at the story or epic level. > - Use `/adjust --level project` when you have a **deliberate directional or strategic intent change** (such as pivoting a product contract or strategic vision) at the project level. ## Step 0: Read Template First **Before any other action** โ€” read this template now: ``` .speck/templates/project/harden-template.md ``` --- ## The Harden Flow (/harden scope) When a bug is found post-validate or post-ship, do NOT spin up a full-ceremony story with spec, plan, and tasks unless the feature requires brand-new functionality. Instead, use the **Harden Flow**: 1. **Investigate & Diagnose**: - Determine what broke, how it was discovered (e.g. founder walkthrough, user report), and identify the technical root cause. - Run `/speck-debug` or equivalent debugging scripts if necessary. 2. **Root Cause Analysis (RCA)**: - Critically evaluate why the existing safety nets (tests, linters, audit, validation) missed this bug โ€” **and whether one of them REQUIRED it.** - Do NOT just patch the code โ€” find the systemic testing or specification gap. 2b. **Counter-test sweep โ€” BEFORE you write the fix** (fills ยง2b of the template): - Every defect has a shadow: the tests written against the buggy code. They name the defect as the *expected value*, so they are honest, well-named and green forever โ€” and the truthful change is the failing one. The cheapest misreading of a red suite is "my fix broke a test" rather than "the suite agreed with the bug". - **Grep the suite for assertions naming the OLD behaviour** and record the query verbatim. Search the behaviour, not the identifier (`rg -n 'fail-open|renders ONLY|deliberate claim' --glob '**/__tests__/**'`). - **After the fix, list every PRE-EXISTING test that went red**, and classify each โ€” never delete one to get green: - `DEFECT-PINNING` โ€” the assertion encodes the bug. It is **its own finding**, with its own remediation line in ยง3 and its own severity; on a safety, authorization or disclosure surface it inherits the severity of the defect it pinned. - `DECISION-RECORD` โ€” the assertion encodes a deliberate choice the fix reverses. Cite the decision-log entry and re-decide there. - `SCOPE-NARROWING` โ€” it was true of a narrower case. Rewrite it. - **If nothing went red, say why.** A fix that turns nothing red is suspect: "the path was genuinely uncovered" and "the fix does not do what I think it does" look identical in a report. The honest exception is the first โ€” and an uncovered path is a coverage finding of its own. If no reason can be given, the fix is unproven: mutate it (step 3) before claiming anything. The requirement is the **sentence**, never a hunt for something to break. - For a copy / disclosure / claims defect, also check the guard's DIRECTION: a blacklist of phrasings is never complete and does not cross locales. The load-bearing assertion must be **positive** (the required fact is PRESENT), parametrized over **every** locale bundle. A blacklist-only guard is secondary evidence. 3. **Implement Fix & Systemic Guardrail**: - Write the fix for the bug. - **Crucial**: Implement a regression guardrail. If it was a mock issue, fix the mock; if it was a UI-bypass issue, add a test that drives the real UI DOM. - If applicable, add a lint check, template check, or prime utility to prevent recurrence across the codebase. - **Then mutation-prove the guardrail** โ€” a guard is not evidence until someone watched it fail, and the highest-yield suspect is the guard authored in the *same increment* as the fix, because it was designed against the same model of the defect that produced a wrong fix once: ``` .speck/scripts/validation/mutate-guard.sh \ --file --pattern '' --replacement '' \ --red '' --green '' \ [--expect-count N] ``` It runs inside a **throwaway worktree**, so there is nothing to revert and an interrupted run cannot leave a mutated production file behind. It refuses a pattern that does not match exactly once, a comment or docstring line, and a test or fixture path โ€” the three ways a mutation is silently a no-op. **Transcribe its `SPECK_MUTATION_*` output into ยง3; never type a verdict by hand.** - A guard cited as evidence must **import and call the shipped function or the shipped SQL literal**, not a transcription of it โ€” a guard that re-derives its own predicate cannot observe its own removal. For a **drop / filter / redact** guardrail the required control is that **legitimate content survives**; proving bad content is caught is satisfied by a guard that drops everything, and over-removal is the bug that actually ships. - If the mutation comes back **`GUARD_MUTATION_GREEN.P2`, record it green** and write the honest scope onto the test ("this guard does not observe X"). **Never tune the mutation until it reddens** โ€” that manufactures exactly the evidence the field exists to prevent. - **Class recurrence (ยง3, required).** Ask "is this an instance of a class?" and answer it by searching for the syntactic **shape**, not for the identifier that happened to be wrong. On the **second** instance the required deliverable stops being another instance fix and becomes a **gate at the chokepoint** every reader routes through โ€” with inverted polarity, so the registry enumerates *exceptions* rather than instances. The bound: `>=2 instances AND a syntactically decidable shape`. Where the shape is not decidable, a named in-file declination plus the chokepoint refactor beats a scanner that flags correct code. 3b. **Observation licensing โ€” when an OBSERVATION is what closes the fire** (record in ยง3, cite in ยง4): - Step 3 mutation-proves a **test**. This step is its counterpart for an **observation** โ€” a grep of a log, a CI verdict, a dashboard, a quiet inbox, a count that did not move. Those close fires and justify REFUTED in exactly the same way, and they carry a defect tests do not: **a green reports its verdict and never its exposure** โ€” whether the occasion it ran on contained the failing case at all. A hard-won pass and a pass that *could not have failed* are byte-identical in the report, so confidence accumulates on **run count** rather than on **chances to fail**. - **This is not the shadowed/vacuous/forged class.** The check is correct, executed, and truthful about itself. What is missing is the occasion. Keep them apart mechanically: re-run the check against a **real failing case** โ€” RED means the guard is broken (that is the other class, and it is a ยง2b finding); GREEN means nothing is broken and this run simply had nothing to catch (this class). - **Ask the two questions, in order:** 1. **Can the failing case be manufactured cheaply?** Yes โ†’ manufacture it before the green counts. Two legs, and neither substitutes for the other. *The instrument:* confirm it can show the thing AT ALL before believing it showed nothing (a positive control). *The invocation:* run the **shipped** one. Diff the local flags and env against the `Dockerfile` CMD / `Procfile` / deploy command โ€” the canonical instance is a secret in a URL path segment that was invisible locally under `uvicorn --log-level warning` and reproduced in one request under the container's own invocation, which defaults to INFO. **The observation was real; the configuration it was made under was the lie.** 2. **If it cannot be exposed, what does this green license?** Only *waiting* โ†’ the unexposed run is harmless and chasing exposure is waste. Something **accumulating or irreversible** โ€” closing this fire, exiting a shadow period, re-stamping a readiness state, writing REFUTED on a live credential โ†’ **the unexposed run must not count toward it.** - Run it, and **transcribe the `SPECK_OBSERVATION_*` block; never type a verdict by hand**: ``` .speck/scripts/validation/observe-guard.sh \ --subject '' \ --observe '' \ --expect-absent '' \ --licenses waiting|accumulating|irreversible \ [--positive-control ''] [--no-lever] \ [--shipped-from Dockerfile|Procfile] [--shipped-cmd ''] \ [--env ] [--accept-divergence ] ``` `--licenses` is **required and has no default** โ€” it is question 2, and nothing else in the toolchain expresses it. Verdicts: `OBSERVATION_EXPOSED` (the green counts) ยท `OBSERVATION_UNEXPOSED.P2` (waiting-only; honest, non-blocking) ยท `OBSERVATION_UNEXPOSED_BLOCKING.P1` (the run does not count toward what it was cited for) ยท `OBSERVATION_NOT_GREEN.P1` (the observation did not hold โ€” that is the real finding, route it to ยง1) ยท `OBSERVATION_UNMEASURED.P2`. - **The three bounds โ€” they are what keep this from being tyrannical:** - **Some subjects have no lever.** A guard reconciling inbound mail cannot make mail arrive. Declare `--no-lever`; it does not excuse the run, it routes straight to question 2. *Two static passes in a row prove only that neither number moved* โ€” the guard's per-subject ledger reports `SPECK_OBSERVATION_STATIC=true` when it sees exactly that. - **Exposure is bought, not free.** Buy it where the green authorises something that cannot be walked back, not everywhere. `--accept-divergence ` is that dial, and it is **counted in the record**, so a purchase decision is auditable rather than invisible. - **A disclosed gap beats a fabricated proof.** If no shipped-invocation source exists, the tool says `SHIPPED_SOURCE=none` and names `--shipped-cmd` as the repair. Leave that sentence in the report. 4. **Document the Hardening**: - Create a dated hardening report using the template: `specs/projects//project-harden-report-.md` - Fill in all sections (Defect, Root Cause, Guardrails, Readiness Re-assessment). 5. **Re-Stamp & Re-Assess State**: - If the bug affected an already-validated story/epic, update its `validation-report.md` with the new re-assessed readiness state. - Run `.speck/scripts/stamp-truth.sh` against the report and the updated validation reports. - Trigger `/project-state` to regenerate and update active status. --- ## Behavior Rules - NEVER just patch the bug without documenting why the gates missed it. - NEVER cite a guardrail as evidence without a mutation record produced by `mutate-guard.sh`. - NEVER close a fire on an OBSERVATION without answering what its green licenses (step 3b). An observation that closes a fire, exits a shadow period, or re-stamps a readiness state licenses something irreversible: it needs `OBSERVATION_EXPOSED`, and `OBSERVATION_UNEXPOSED_BLOCKING.P1` means the run does not count toward that claim. An observation that licenses only *waiting* needs nothing โ€” record `OBSERVATION_UNEXPOSED.P2` and move on. - NEVER tune an observation until it is exposed, and never adjust a mutation until it reddens โ€” both manufacture exactly the evidence the field exists to prevent. Record the honest verdict and write the scope down. - NEVER close a harden without ยง2b answered โ€” including the zero-red sentence. - NEVER delete a pre-existing test to get green. Classify it; a `DEFECT-PINNING` test is its own finding. - ALWAYS add a systemic guardrail (linter, regression test, or primitive check) to ensure it can never recur. - ALWAYS re-assess the readiness state of the affected stories. - BLOCK subsequent releases if the defect is a P0 blocker until the `/harden` flow report is stamped and green.