mixdog 1.4.1 → 1.4.2

package/src/defaults/skills/skill-creator/references/design.md

@@ -1,203 +1,111 @@
 # Skill design
 
-Use this reference after deciding that the requested outcome belongs in a
-skill.
+## One owner
 
-## Start from behavior
+Before writing, name the result the skill makes more reliable, the decisions
+the agent misses without it, the evidence that proves completion, the failures
+that need recovery, and the nearby request it must leave alone.
 
-Define the behavior before naming files:
+Extend an existing skill that owns the outcome; create a new one only for a
+distinct trigger, workflow and verification. Avoid skills that redirect to
+other skills, several skills competing for one request, one skill covering a
+whole technology, and product features written as prose.
 
-- What recurring result should become more reliable?
-- Which decisions does the agent currently miss?
-- What evidence proves completion?
-- Which failures need recovery rather than a hard stop?
-- Which adjacent task must remain outside this skill?
-
-A skill earns its context cost by supplying judgement or procedure that changes
-results. Generic encouragement and tool documentation do not qualify.
-
-## Pick one owner
-
-Prefer extending an existing skill when it already owns the outcome. Create a
-new skill when it has a distinct trigger, workflow, and verification boundary.
-
-Avoid:
-
-- umbrella skills that merely redirect to narrower skills;
-- several skills competing for the same user intent;
-- one skill that attempts to cover an entire profession or technology family;
-- product features represented as prose because implementing code is harder.
-
-## Choose where it lives
-
-| Scope | Use when |
-|---|---|
-| Machine-global | The user wants the workflow available across Projects |
-| Plugin | The workflow depends on and ships with an extension |
-| Built-in | The workflow is broadly useful, stable, and inexpensive to expose |
-
-A workflow specific to one repository may be better owned by project
-documentation than by a machine-global skill.
+System instructions and tool schemas outrank a skill: it explains when and how
+to use tools, never redefines their arguments or permissions.
 
 ## Frontmatter
 
-Required:
+- `name`: lowercase letters, digits and hyphens, no leading, trailing or
+  repeated hyphen, at most 64 characters, equal to the folder name.
+- `description`: one plain capability sentence for the UI, at most 100
+  characters. The model never sees it.
+- `when_to_use`: the trigger (Listing line below).
+- `dependencies.tools`: tools loaded with the skill. `type: tool` takes an
+  exact tool name, `type: mcp` a connected server's name. A missing or
+  disabled tool is reported, never installed or enabled, and nothing grants
+  permissions. Leave optional tools out.
 
-- `name`: lowercase letters, digits, and hyphens; no edge or repeated hyphen;
-  at most 64 characters; identical to the parent directory.
-- `description`: one sentence naming the capability.
+  ```yaml
+  dependencies:
+    tools:
+      - type: tool
+        value: office
+  ```
 
-Recommended:
+- `metadata.requires`: a Mixdog built-in feature the skill cannot work without.
 
-- `when_to_use`: the trigger line — phrases and situations that should select
-  the skill, then the boundary against the nearest neighbour.
-
-Optional portable fields include `license`, `compatibility`, `metadata`, and
-`allowed-tools`. A parsed field is not automatically an implemented feature.
-Confirm runtime support before assigning it operational meaning.
-
-Declare mandatory tools in `dependencies.tools`, either in `SKILL.md`
-frontmatter or an imported `agents/openai.yaml`:
-
-```yaml
-dependencies:
-  tools:
-    - type: tool
-      value: office
-    - type: mcp
-      value: existing-server
-```
-
-`mcp` resolves the available tools of an already connected server. Missing,
-disabled, and policy-blocked tools are reported, never installed or enabled.
-
-The skill editor keeps tool-link overrides in Mixdog's data directory so
-updating a downloaded skill does not erase local links or rewrite its source.
-An empty override disconnects all tools; restoring the declaration removes
-the override. Changing the instruction text still requires an editable skill.
+Other fields have no effect in Mixdog.
 
 ## Listing line
 
-The model never sees the body until it calls `Skill()`. Selection happens on
-one listing line per skill:
+The model sees one line per skill and loads the body only by calling `Skill`:
 
 ```text
 - <name>: <when_to_use> [tools: <linked tool names>]
 ```
 
-The runtime cuts the trigger at 100 characters on a word boundary, and when
-many skills share the listing budget it shrinks every trigger evenly toward
-60; text past the cut never routes the skill. The tool suffix comes from effective dependencies, not
-handwritten trigger text; `mcp:<server>` denotes a server's tools. Keep these
-three responsibilities separate:
-
-| Field | Job | Budget | Write | Avoid |
-|---|---|---|---|---|
-| `description` | UI-only summary | ≤ 100 chars | One plain capability sentence | Operating rules or selection conditions found nowhere else |
-| `when_to_use` | When to load the skill | ≤ 100 chars, core in the first 60 | English descriptions of user intents across languages, implicit situations, then `not …` naming the neighbouring owner | How to use it — procedures, rules, constraints, commands, tool arguments; translated keyword lists |
-| Body | Loaded operating instructions | As needed | Capability, prerequisites, procedure, constraints, recovery, and verification | Depending on UI copy to supply an instruction |
+The trigger is cut at 100 characters on a word boundary, and shrinks evenly
+toward 60 when many skills share the listing; text past the cut never selects
+the skill. The tool suffix comes from `dependencies`, never from the trigger.
 
-Put the strongest trigger first in `when_to_use`. A boundary is worth writing
-only when a neighbouring skill or plain tool could plausibly win the request.
+| Field | Job | Write | Avoid |
+|---|---|---|---|
+| `when_to_use` | When to load the skill; core in the first 60 characters | The user intents and situations, strongest first, in English for every language, then `not …` naming the nearest other owner | How to do it: steps, rules, commands, tool arguments; translated keyword lists |
+| Body | Everything after selection | Capability, prerequisites, procedure, recovery, verification | Relying on the trigger or the UI description for an instruction |
 
-Example:
+Never summarise the procedure in the trigger: a model that reads a workflow
+there may follow it instead of loading the body. Add the `not …` boundary only
+when a nearby skill or a plain tool could plausibly win the request.
 
 ```yaml
-description: Deploy Mixdog to the installed app, VPS, or a live release.
-when_to_use: 'Deploy, redeploy, or update the installed app, VPS, or a live release; not builds or tests alone.'
+when_to_use: 'Deploy or update the installed app or a live release; not builds or tests alone.'
 ```
 
 ## Body
 
-The body loads once, after selection, so it owns everything the listing line
-left out. Use only the sections the workflow needs, in this order:
+Only the sections the workflow needs, in this order:
 
-1. **Intro** — two or three sentences: what the skill produces, what it does
-   not do, and the key dependency stance.
+1. **Intro** — two or three sentences: what it produces and what it does not.
 2. **Boundary or mode selection** — the decision that picks a path or hands
    the request to another owner.
-3. **Prerequisites** — exact tools, features, environment, and approvals.
+3. **Prerequisites** — exact tools, environment and approvals.
 4. **Procedure** — numbered steps; each important step ends with the
-   observable result that proves it is done, and an irreversible step names
-   the user checkpoint before it.
+   observable result that proves it, and an irreversible step names the user
+   checkpoint before it.
 5. **Pitfalls** — observed failures and their recovery, not generic caution.
 6. **Verification** — the check that proves the outcome.
-7. **Resource links** — each `references/` or `scripts/` file with the
-   condition for reading or running it.
+7. **Resource links** — each file with the condition for reading or running it.
 
-Write in the imperative. Explain why a rule exists when the reason changes
-behaviour; drop rules the model already follows without being told.
+Write in the imperative; give a reason only when it changes behaviour, and drop
+rules the model already follows. About 100 lines for a simple workflow, about
+200 for a complex one, never over 500. Split by loading condition, not by
+length.
 
-Size: about 100 lines for a simple workflow, about 200 for a complex one, and
-below 500 in every case. Split content because it has a different loading
-condition, not simply because the file became long.
+## Resources
 
-## Bundled resources
-
-### References
-
-Put detailed rules or domain material in `references/`. Link each file directly
-from `SKILL.md` and state the condition for reading it. Do not create chains in
-which one reference points the agent to another.
-
-### Scripts
-
-Use `scripts/` for deterministic repeated work. Every executable should:
-
-- validate inputs before side effects;
-- operate on explicit paths;
-- bound time, memory, retries, and output;
-- return actionable errors and a non-zero failure status;
-- avoid hidden network, installation, deletion, or credential behavior;
-- work on every claimed platform or declare the limitation;
-- have a behavioral test separate from the prose.
-
-Reference executable paths through `${MIXDOG_SKILL_DIR}` so installation
-location does not matter.
-
-### Assets
-
-Use `assets/` for templates and static material consumed by outputs. Guidance
-belongs in Markdown, not in files that the agent will not load as instructions.
-
-## Portability audit
-
-Inspect prose and scripts for:
-
-- POSIX-only commands or paths on Windows;
-- Windows-only shell syntax on other platforms;
-- machine-specific absolute paths;
-- undeclared external programs and environment variables;
-- assumptions about a vendor CLI, model, or authentication state;
-- output paths that overwrite user files by default.
-
-Prefer portable implementation first. Restrict compatibility only when the
-dependency cannot reasonably be removed.
-
-## Editing discipline
-
-- Preserve identity and public behavior unless change is requested.
-- Replace outdated guidance instead of appending exceptions.
-- Keep safety and recovery behavior during simplification.
-- Do not duplicate a rule across the body, reference, script help, and tool
-  schema; choose the component that owns it.
-- End with a pass that removes instructions that did not influence outcomes.
+- `references/` — detailed rules read only in some cases. Link each directly
+  from `SKILL.md` with its read condition; no file points to another.
+- `scripts/` — deterministic work that would otherwise be redone each time.
+  Validate inputs before side effects, use explicit paths, bound time, output
+  and retries, fail with an actionable message and a non-zero status, and do
+  no hidden network, installs, deletion or credential access. Give it a
+  behavioural test, and call it through `${MIXDOG_SKILL_DIR}`.
+- `assets/` — templates and static material the output uses; guidance stays
+  in Markdown.
 
 ## Audit checklist
 
-Apply to every skill when asked to audit, review, or tidy the skill set.
-
 | Check | Failure looks like | Fix |
 |---|---|---|
-| Field separation | UI `description` over 100 chars, `when_to_use` over 100, or operating details present only in metadata | Keep the UI summary short, selection conditions in the trigger, and all execution details in the body |
-| Trigger presence | `when_to_use` empty while a neighbour competes | Add the phrases users actually write and the `not …` boundary |
-| Trigger content | `when_to_use` says how rather than when: rules, constraints, commands, tool names or arguments | Move them to the body; keep the request situations and the `not …` boundary |
-| Body order | Sections out of the order above, a `When to use` section in the body, steps without a completion result | Reorder; delete body triggers (they never route); add the observable result |
-| Resources | A referenced file missing, a chain of references, a script without an input check | Fix the path, flatten the chain, add validation |
-| Duplication | The same rule in the body, a reference, and a script help text | Keep it in the owner; delete the copies |
-| Staleness | Paths, tools, or flags that no longer exist | Replace or remove; never leave an instruction that cannot succeed |
-
-Run `scripts/validate-skill.mjs` on each directory; it reports the listing-line,
-code-fence, and resource checks mechanically, and the rest is a read of the body against
-this reference.
-
+| Fields | `description` or `when_to_use` over 100 characters; an instruction found only in metadata | Short UI summary, selection in the trigger, execution in the body |
+| Trigger | Empty while a neighbour competes; says how instead of when | The phrases users write plus the `not …` boundary; move the how to the body |
+| Body | Out of order, a "when to use" section, steps without a result | Reorder, delete body triggers, add the observable result |
+| Resources | A missing file, a chain of references, a script without input checks | Fix the path, flatten, validate inputs |
+| Side effects | External programs, network, secrets or irreversible steps (commit, deploy, publish, restart) not visible or not waiting for the user | Name them in prerequisites; checkpoint before the step |
+| Duplication | One rule in the body, a reference and a script's help | Keep it in its owner, delete the copies |
+| Staleness | Paths, tools or flags that no longer exist | Replace or remove |
+| Value | A rule or section that no scenario needed | Delete it |
+
+The validator checks fields, fences and resource paths; the rest is a read
+against this table.

package/src/defaults/skills/skill-creator/references/evaluation.md

@@ -1,111 +1,52 @@
 # Evaluating a skill
 
-Use this reference after a draft exists or when a current skill has a reported
-defect.
+Use after a draft exists or when a skill misbehaves. A passing validator
+proves structure only, never behaviour.
 
-## Separate the questions
+## Scenarios
 
-A complete evaluation asks:
+Two to five realistic requests, with the context a real user would give:
 
-| Area | Question |
-|---|---|
-| Selection | Does the description attract relevant requests and reject close alternatives? |
-| Execution | Does the loaded workflow produce the required outcome? |
-| Integration | Do resources, paths, tools, and feature gates resolve? |
-| Recovery | Do failures remain bounded and actionable? |
-| Efficiency | Does the skill remove repeated work without adding ritual? |
-
-Passing a frontmatter check proves none of the execution questions.
-
-## Scenario set
-
-Use two to five realistic requests:
-
-1. a normal request that names the intent;
+1. a request that names the intent;
 2. an implicit request that should still select the skill;
-3. an important edge or failure condition;
-4. a close negative request owned elsewhere;
-5. a subjective artifact case when human judgement matters.
+3. an edge or failure condition that matters;
+4. a near-miss negative: shares the skill's words but belongs to another
+   owner;
+5. a subjective artifact, when taste or domain judgement decides.
 
-Do not use “load this skill” as a positive test. Include concrete context, files,
-or constraints that a real user would provide.
-
-An optional record shape:
-
-```json
-{
-  "id": "short-purpose",
-  "prompt": "Realistic user request",
-  "expected_owner": "skill-name or none",
-  "observable_result": "What must become true",
-  "inputs": []
-}
-```
-
-Keep evaluation artifacts outside the distributable directory unless the
-packaging process explicitly excludes them.
+Never use "load this skill" as a positive case. Keep scenario files outside
+the skill's folder.
 
 ## Baseline
 
-Before improving a skill, preserve its exact prior behavior through existing
-version history or a read-only evaluation snapshot. Compare identical prompts,
-inputs, model class, tool availability, and environment.
-
-For a new skill, compare against no skill only when the runner can isolate the
-draft from the baseline. Otherwise report a smoke test rather than implying a
-controlled A/B result.
-
-The evaluation harness must remain uniform. Do not add task-specific routing,
-timeouts, prompt clues, retries, or scoring exceptions to make one version win.
+Before changing a skill, keep a copy of the prior version and run the same
+prompts, inputs, model and tools against both. A new skill with no runnable
+baseline gets a smoke test, not a claimed comparison. Keep the harness the
+same for both: no task-specific hints, retries, timeouts or scoring
+exceptions.
 
 ## Evidence
 
-Use deterministic checks for mechanical outcomes:
-
-- required files exist and open;
-- structured fields and values are valid;
-- references resolve;
-- malformed input fails with useful guidance;
-- resource and retry limits hold;
-- an irreversible action waits for approval;
-- prohibited side effects do not occur.
-
-Do not test exact prose, source strings, internal algorithms, or snapshots whose
-expected behavior has intentionally changed.
-
-Use user review for clarity, visual quality, writing taste, and domain
-judgement. Present the full-size persisted output rather than a description of
-it.
+- Mechanical outcomes get deterministic checks: files exist and open, fields
+  are valid, references resolve, bad input fails with useful guidance, an
+  irreversible step waits for approval, no forbidden side effect happens.
+- Never assert exact prose or internal steps.
+- Clarity, taste and domain judgement go to the user, shown the real output.
 
 ## Diagnose before revising
 
-Classify a failure:
-
-- **selection** — description signal or neighboring boundary;
-- **instruction** — missing decision, sequence, or completion evidence;
-- **resource** — broken script, reference, asset, or path;
-- **integration** — unavailable tool, feature, dependency, or platform;
-- **harness** — invalid comparison or test infrastructure;
-- **underlying capability** — the tool or product cannot deliver the outcome.
-
-Edit the component that owns the failure. More prompt text does not repair a
-broken tool, and body changes cannot fix a description that never selects the
-skill.
+| Class | Where the fix goes |
+|---|---|
+| Selection | Trigger or the neighbour's boundary |
+| Instruction | A missing decision, step order or completion result in the body |
+| Resource | The broken script, reference, asset or path |
+| Integration | The unavailable tool, feature or dependency |
+| Harness | The test setup, not the skill |
+| Capability | The tool or product; the skill cannot deliver it |
 
 ## Improve without sediment
 
-After each revision:
-
-1. rerun affected scenarios;
-2. validate structure and resource paths;
-3. retain safety, recovery, and bounded execution;
-4. remove rules superseded by the fix;
-5. check whether the change generalizes beyond the failing example.
-
-Look for tests that always pass, high variance, repeated helper work, excessive
-token or time cost, and rules that change no outcome. Those are signals to
-improve the evaluation or simplify the skill.
-
-Stop when required behavior passes, subjective review is accepted, and further
-edits no longer produce meaningful gains.
-
+After each revision, rerun the affected scenarios, validate, keep safety and
+recovery, delete the rules the fix superseded, and check that the fix is not
+tailored to one example. Stop when the required behaviour passes, the user
+accepts the subjective parts, and further edits stop paying off.

package/src/defaults/skills/test-suite/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: test-suite
+description: Write, run, diagnose, prune and audit a project's tests without overloading the machine.
+when_to_use: 'Write, fix, run, diagnose, prune or audit tests, flaky failures, suite health; not live UI checks.'
+dependencies:
+  tools:
+    - type: tool
+      value: read
+    - type: tool
+      value: shell
+---
+
+# Test suite
+
+Owns how tests in any project are written, run during a change, diagnosed when
+they fail intermittently, pruned and audited. The project's own
+commands, lanes and conventions win over every default here; this skill
+supplies the judgement and procedure around them. Driving a running app or
+device by hand is outside it.
+
+## Pick the mode
+
+| Request | Mode |
+|---|---|
+| Add a test, fix a bug test-first | Write |
+| Check a change while editing | Run |
+| A test fails sometimes, only in a full run, only in CI, only on this machine | Diagnose |
+| Duplicate, dead, obsolete or worthless tests | Prune |
+| Review the suite's health or a whole area | Audit |
+
+## Prerequisites: find the project's own way
+
+Before the first run, look for the project's focused test command in this
+order, and stop at the first source that gives it plus any constraint that
+affects the change (lane, setup, needed service): `AGENTS.md` or `CLAUDE.md`,
+`docs/testing*`, `CONTRIBUTING*`, package scripts (`package.json`, `Makefile`,
+`pyproject.toml`, `Cargo.toml`), then CI workflows. Do not survey every
+manifest or CI lane. Result: one focused command, copied from the project,
+never invented; a broader command only when the change is broad. When nothing
+is documented, fall back to the
+runner's own selection: `node --test <file>`, `vitest run <file>`,
+`jest <file>`, `pytest <file>::<test>`, `go test -run <Name> ./<pkg>`,
+`cargo test <name>`.
+
+## Machine rules
+
+Tests run on the user's working machine. These hold in every mode.
+
+- The Verification section of your system rules owns the evidence budget,
+  reruns, fix attempts, heavy runs and stopping what you started; follow it.
+- Never loop a test to "reproduce" flakiness here, and never shard in
+  parallel locally; repetition belongs to CI history.
+- Confirm by PID or command line that detached processes you started are gone.
+
+## Write
+
+What a change gets:
+
+| Change | New tests |
+|---|---|
+| Bug fix | One regression test for the reported behaviour |
+| New behaviour | One per observable behaviour the requirement names (its success and its stated rejections) |
+| Refactor, rename, move | None; the existing tests must still pass unchanged |
+| Removal | None; delete the removed behaviour's tests, never assert the absence |
+| Docs, copy, style, config values | None |
+
+Only a test owning a lasting contract joins the suite and its CI lane.
+Reproductions, probes and one-off checks are scratch: they live in a temp
+directory outside the repository, are never committed, and are deleted when
+the task ends. A scratch reproduction that proves a bug becomes the
+regression test above or is deleted, never both kept.
+
+1. Name the behaviour and its owner: the one contract this test owns, beside
+   the code it exercises. If a test already owns it, extend that test
+   (`references/suite-design.md`). Result: one file and test name chosen.
+2. Name the production change that would make the test fail; if you cannot,
+   redesign it around an observable behaviour (`references/suite-design.md`).
+   Write the test through the user's interface (caller, CLI,
+   HTTP, rendered output) with the expected value from the requirement, not
+   from running the code. For a new regression test, show it failing first:
+   the failure names the missing behaviour. An existing failing test already
+   counts as that evidence.
+3. Apply `references/reliability.md` for any time, process, port, file,
+   environment, locale or platform dependency. Result: no fixed sleep, no
+   fixed port, no unrestored global, no host-locale assumption.
+4. Make it pass with the smallest change, then rerun the same file. Result:
+   a new regression test's fail-before and pass-after pair goes into the
+   report. Add no further
+   tests unless the user asks.
+5. Put it in the lane its duration and needs call for (`suite-design.md`).
+
+## Run
+
+1. Run the covering file(s) only. Result: the selected count matches the files
+   you meant.
+2. On failure read the full log before editing; do not rerun to see if it
+   passes.
+3. Run a broader lane once after the last edit only if the change touches a
+   shared contract or an integration point; otherwise stop at the covering
+   file. Reuse an earlier pass only when no later edit touched the code it
+   checks.
+4. After two evidence-backed fix attempts, report what was tried and the log.
+
+## Diagnose
+
+An intermittent failure is a defect in the test or the product, never noise
+(`references/flaky-policy.md`).
+
+1. Collect evidence without reruns: the failing assertion, the full log, what
+   else was running, the OS and locale. Result: the failing line and the
+   condition it waited on.
+2. Classify the cause with the table in `references/reliability.md`. Result:
+   one named cause with the line that assumes it.
+3. Propose the fix: in the test, or in the product when real users can hit
+   the same race. A longer timeout, a retry or a skip is not a fix.
+
+Diagnose ends at a report: cause, evidence, proposed fix. Only when the user
+asked for a fix, apply it and prove it with the focused file plus a
+deterministic trigger of the cause (a held promise, a fake clock, a localized
+fixture), not by looping. It never becomes an open-ended fix loop. Never
+skip or disable a failing test; when the fix cannot land now, report it and
+leave that decision to the user. Only a capability skip (a platform or tool
+the test needs is absent) is allowed, and its reason names that capability.
+
+## Prune
+
+First tell redundant coverage from removing a supported behaviour, and keep
+distinct observable success, rejection, error and compatibility cases.
+Removing a behaviour with its tests needs evidence independent of those tests
+(current requirements, real callers, a specification); a test existing only
+for a branch, or a fallback and test justifying each other, is no evidence,
+and unresolved intent blocks deletion.
+
+- Delete a test only when it is dominated (same branch and result as a
+  stronger test), tautological (cannot fail), a permutation crossing no new
+  branch, or verification theater (verifier and producer share one failure
+  domain). Name the test that still owns the contract.
+- Deleting a contract test needs the user's approval.
+- Same contract owned twice → merge the unique cases into the owner at the
+  user's interface.
+- Asserts that something was removed, restates a constant, copies production
+  logic or source text into the test, or pins internals no user observes →
+  delete it, or rewrite it at the interface when a real contract is behind it.
+- Passes only alone → Diagnose; never mark it serial to hide it.
+
+Prune as you go: a change that touches a test file applies these rules to that
+file only. A whole-suite sweep is an Audit the user asked for.
+
+Result: each removal names the owning test that still covers the contract, or
+states that the contract is gone.
+
+## Audit
+
+1. Run `node ${MIXDOG_SKILL_DIR}/scripts/inventory.mjs <project-root>`
+   (`--json` for data). Result: per-area counts, lanes, languages, risk
+   markers, and defect skips for JS/TS, Python, Go and Rust.
+2. Read `references/case-management.md` and rank findings by impact: defect
+   skips, risky markers in the fast lane, duplicate owners.
+3. Report one table (area, finding, count, proposed action) and wait for the
+   user's choice of batches. Audit ends at this report; fix only the batches
+   the user picks, one or two at a time, each verified by its covering files.
+
+## Pitfalls
+
+- Parsing localized tool output (a console in another language, a busy host
+  dropping rows) passed on the author's machine and failed elsewhere. Query a
+  structured source.
+- Fixed sleeps passed alone and failed in bulk when other work ran.
+- A load generator or server started by an agent was detached, outlived the
+  agent and froze the machine. Nothing detached survives a report.
+- Render tests passed while the real screen hid a row: assert the rendered
+  output, not the inputs.
+- Full lanes that take many minutes fail under load; selection, not more
+  retries, fixes that.
+
+## Verification
+
+- Write/fix: the focused file passes; a new regression test also failed
+  before, and the report quotes both.
+- Diagnose: the named cause and its evidence. Only when the user asked for a
+  fix: the deterministic trigger and its passing run.
+- Every mode: no process you started is still running.
+
+## Resources
+
+- `references/reliability.md` — read when a test touches time, processes,
+  ports, files, environment, locale or the platform, or when diagnosing.
+- `references/flaky-policy.md` — read when a failure is intermittent.
+- `references/suite-design.md` — read when writing a test, choosing its lane
+  or file, or reviewing how a suite is organized.
+- `references/case-management.md` — read for Audit, or when adding a new
+  area.
+- `scripts/inventory.mjs` — run for Audit; read-only, bounded, Markdown or
+  `--json`.