luciazero 2.3.0 → 2.4.2

package/skills/plan/SKILL.md

@@ -3,26 +3,30 @@ name: plan
 description: Build a falsifiable implementation plan for new features, major refactors, ambiguous work, or risky multi-module changes. Use when the user asks for a plan or material choices remain; skip routine edits with clear scope and proof.
 ---
 
-# Plan — make the change falsifiable
+# Plan
 
-Use the lightest plan that removes uncertainty. Planning is a design protocol, not a mandatory pause before every edit.
+Use the lightest plan that removes uncertainty; do not pause by default.
 
 ## 1. Bound the work
 
-State the goal, non-goals, affected modules, public interfaces, and configuration keys. Mark assumptions separately from known facts. Inspect the repository before treating a guessed interface or command as real.
+State goal/non-goals, modules, public interfaces, and config keys. Separate
+assumptions/facts. Inspect repository before trusting guesses.
 
 ## 2. Define proof
 
-For every requirement, name an observable pass/fail condition and the command or inspection that can test it. Do not invent an exact output line before the check exists; define the decisive signal precisely enough that success and failure cannot both satisfy it.
-
-If coverage is missing, plan the smallest red-before-green test or fixture first. Include the full verification tier for closeout.
+For every requirement, name an observable pass/fail condition and the command
+or inspection that tests it. Never invent exact output. Add the smallest
+red-before-green test for missing coverage; include full verification at
+closeout.
 
 ## 3. Choose reversible steps
 
-Break the work into independently checkable edits. Name compatibility risks, data or contract migrations, rollback points, and any state that cannot be recovered automatically.
+Use independently checkable edits; name compatibility risks, data or contract
+migrations, rollback points, and unrecoverable state.
 
 ## 4. Decide whether to pause
 
-Ask for approval before editing only when the remaining choice is ambiguous and materially changes the result, or when the next action is high-stakes, destructive, changes a public contract, expands scope, deploys, spends money, or affects production. Ask one decision-shaped question.
-
-Otherwise, show the concise plan and proceed. Update it when evidence invalidates a step; do not preserve a stale plan for ceremony.
+Ask for approval only if ambiguity changes the result or the action is
+high-stakes, destructive, changes a public contract, expands scope, deploys,
+spends money, or affects production. Ask one decision-shaped question.
+Otherwise, show the concise plan and proceed. Update it when evidence changes.

package/skills/ready/SKILL.md

@@ -5,105 +5,121 @@ description: Make an unfamiliar repository agent-ready with a verify command, sm
 
 # Ready
 
-Goal: leave the repo with **one command that returns an exit code** and enough guardrails that future agent work self-verifies. Nothing here is language-specific — detect, don't assume.
+Leave the repository with one unattended command that returns a meaningful exit
+code, plus only the guardrails needed for future agents to self-verify. Detect
+the stack; do not assume it. Run every artifact you add.
 
-Bootstrapping is itself work: verify each artifact you add actually runs before reporting it.
+## 1. Detect
 
-## Phase 1 — Detect (never assume)
-
-Run the bundled evidence scan first — it replaces a dozen manual reads with one call:
+Run the bundled scan first:
 
 ```
 <this-skill-dir>/scripts/detect.sh <repo-root>
 ```
 
-(The skill directory is wherever this SKILL.md lives, e.g. `~/.claude/skills/ready/` or `~/.codex/skills/ready/`.) The script surfaces candidates — **you still decide**. It cannot parse CI matrices or exotic build systems; open anything it flags and read the CI config yourself.
-
-Sources, in order of trust:
-
-1. CI config — the most honest source of truth: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/`. **Whatever CI runs is the verify command.**
-2. Manifests: `package.json` scripts, `pyproject.toml` / `tox.ini` / `noxfile.py`, `Makefile`, `justfile`, `Cargo.toml`, `go.mod`, `build.gradle`, `composer.json`
-3. Repo docs: `README*`, `CONTRIBUTING*`, `AGENTS.md`, `CLAUDE.md`, `docs/` — docs go stale; cross-check any doc-claimed command against CI when CI exists. A docs/CI mismatch is itself a finding to record in Phase 5.
-4. Existing test dirs: `tests/`, `test/`, `spec/`, `__tests__/`, `*_test.*`, `test_*.*`
+It finds candidates, not truth; open flagged files and interpret CI matrices or
+unusual build systems yourself. Inspect in this order:
 
-Report what was found as a short table: run / test / lint / typecheck / build / git repo — command or `MISSING`.
+1. CI config: use what CI runs.
+2. Manifests and runners: package scripts, pyproject/tox/nox, Make/just,
+   Cargo/go/Gradle/composer.
+3. README, CONTRIBUTING, CLAUDE.md, AGENTS.md, and docs; record docs/CI drift.
+4. Existing test directories and naming conventions.
 
-**If the directory is not under version control**, propose `git init` early (ask first — some dirs are deliberately not repos): without git there is no smallest reversible step, no safe break-and-restore in Phase 6, and no bisect.
+Report run/test/lint/typecheck/build/git as command or `MISSING`. If this is not
+a Git repository, propose `git init` but ask first.
 
-## Phase 2 — Establish the verify command
+## 2. Establish verification
 
-If a verify path exists, **use it** — do not invent a parallel one.
+Reuse the existing verify path. If none exists, create the smallest entrypoint
+in the repository's native convention.
 
-If none exists, create the smallest real one. Order of preference:
+The command must:
 
-1. The project's native runner, already installed (`pytest`, `vitest`, `go test`, `cargo test`, `dotnet test`)
-2. A single entrypoint that chains them, matching the repo's existing convention (`Makefile` target, `package.json` script, `justfile` recipe) — e.g. `make verify` running lint then tests
+- exit non-zero on failure and run unattended;
+- work offline without credentials, GPU, network, or secrets;
+- use installed project tooling and avoid watch mode;
+- stay quiet on success and be documented for humans.
 
-Rules:
-- Must exit non-zero on failure. A script that always exits 0 is worse than nothing.
-- Must run to completion unattended: disable watch/interactive modes (e.g. `CI=1`, `--run`, `--watch=false`) — a command that waits for input or watches files hangs the loop.
-- Must run offline, with no credentials. Anything needing GPU/network/secrets belongs in a separate slow target.
-- Time the suite once (`time <cmd>`); the measurement, not a guess, decides one tier or two.
-- On success, output should be near-silent — prefer quiet flags in the fast tier so failures, not progress spam, fill the context.
-- Add it to the repo's own docs so humans find it too.
+Time it once. Use one tier when the suite is already quick. When slow checks
+would cripple the edit loop, define:
 
-**Two tiers when the repo has slow checks.** One `verify` command forces a bad trade: either the loop crawls or coverage gets cut. Split it:
+- `verify`: lint/typecheck/unit or smoke coverage, normally under ~60 seconds;
+- `verify-full`: integration/build/slow coverage, required at closeout and PR.
 
-- `verify` — fast (<~60s), offline: lint, typecheck, unit/smoke tests. Run on **every** loop iteration.
-- `verify-full` — everything else: full suite, integration, build, slow checks. Run **before declaring done** and before a PR — "done" means `verify-full` green, not just `verify`.
+Run `verify` on every edit loop; run `verify-full` at closeout and before a PR.
 
-Name them by the repo's convention (`make verify` / `make verify-full`, npm scripts, just recipes). A small repo whose whole suite runs in seconds needs only the single tier — do not add ceremony it does not need.
+For monorepos, prefer a repo-owned `verify-changed` backed by the workspace
+dependency graph, with the root full suite as fallback. Read
+[references/smart-verification.md](references/smart-verification.md) before
+creating it and document its base revision and fallback.
 
-**Monorepos:** detect the workspace layout (`package.json` `workspaces`, `pnpm-workspace.yaml`, turbo/nx config, `go.work`, Cargo `[workspace]`). Prefer a repo-owned `verify-changed` target backed by the workspace's native dependency graph; `verify-full` remains the root suite. Never make a global hook guess package mappings from path prefixes. Read [references/smart-verification.md](references/smart-verification.md) before creating the target, and record its base-revision/fallback contract in Phase 5 notes.
+For Claude Code enforcement-pack users, ask first before offering exact-match
+tracking in the personal, gitignored `.claude/settings.local.json`:
 
-**Enforcement pack users (Claude Code, ask first):** if the verify-tracking hooks are active — classic install: `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/luciazero-verify.sh` exists; plugin install: the `luciazero` plugin is enabled — offer to record the established command in the repo's *personal* settings so the tracker matches it exactly instead of by broad regex — `.claude/settings.local.json` (gitignored, never committed): `{"env": {"LUCIAZERO_VERIFY_CMD": "<the fast-tier command>"}}`. Derive it from CI (the honest source); it is a cache of that truth, so note it must be updated if CI changes. Never put this variable in committed `.claude/settings.json`: the hook cannot distinguish settings scopes, so a repository can control it; treat a repository that ships it as hostile. Show the exact JSON before writing anything.
-
-## Phase 3 — Smoke tests, if there are none
+```json
+{"env":{"LUCIAZERO_VERIFY_CMD":"<fast command derived from CI>"}}
+```
 
-Do **not** attempt coverage. Write 3–6 tests that would catch a catastrophic break. Pick by this heuristic:
+Show the JSON before writing it. Never commit this variable in
+`.claude/settings.json`; repository-controlled hook configuration is hostile.
+This setting caches CI truth; update it whenever CI's verify command changes.
+Skip hook setup on harnesses without hooks.
 
-- **Contract shape** — the core data structure in/out: dimensions, keys, types, no NaN/null where impossible
-- **Round trip** — serialize→deserialize, encode→decode, save→load returns equal
-- **Import/boot** — every package imports, the app answers one request, the CLI runs `--help`. Prefer the framework's test client over binding a real port; any test that starts a process needs a hard timeout and must kill what it started.
-- **Artifact loads** — trained model / migration / config parses and does one forward pass or one query
-- **The bug you were sent to fix** — a regression test reproducing it, written *before* the fix
+## 3. Add smoke tests only when absent
 
-Use fixtures small enough to commit. Never depend on the user's real data paths.
+Add 3–6 small tests for catastrophic failures, not pretend coverage. Choose the
+most relevant:
 
-State plainly that these are smoke tests, not a suite.
+- core input/output shape and impossible null/NaN values;
+- serialize/deserialize or save/load round trip;
+- import, CLI `--help`, or one request through a framework test client;
+- model/config/migration load plus one operation;
+- the reported bug as a red-before-fix regression.
 
-## Phase 4 — Guardrails (only ones that pay for themselves)
+Use commit-sized fixtures, never the user's real data paths. Avoid real ports;
+if a process is unavoidable, enforce a hard timeout and cleanup. Label these as
+smoke tests.
 
-Hooks, `.claude/settings.json`, and `/fewer-permission-prompts` are **Claude Code mechanisms**. On a harness without them (Codex CLI), skip the hook items and encode the same guardrails as instructions in the project's `AGENTS.md` instead: which files are untouchable, which derived file must be regenerated after editing which source.
+## 4. Add only paying guardrails
 
-Prefer few and deterministic. Candidates, in value order:
+Claude hooks/settings are not portable; on Codex or another harness, put
+necessary constraints in AGENTS.md instead.
 
-- **Auto-format/lint on write** — `PostToolUse` hook matching `Edit|Write`, running the repo's own formatter. Only if the repo already has one configured.
-- **Regenerate derived files** — if editing source X requires regenerating Y (protobuf, OpenAPI clients, migrations, lockfiles), hook it, scoped inside the command to the relevant paths. This is the highest-value hook in most repos because humans forget it.
-- **Protect the untouchables** — `PreToolUse` deny on production config, secrets, live model/deploy pointers.
-- **Permission allowlist** — put the repo's read-only and verify commands into `.claude/settings.json` so the loop is not interrupted. `/fewer-permission-prompts` derives this from real transcripts.
+Prefer existing deterministic tools:
 
-Put project-scoped settings in the repo's `.claude/settings.json` (shared) or `.claude/settings.local.json` (personal, gitignored) — **not** in global settings.
+1. formatter/linter after writes;
+2. source-to-derived regeneration;
+3. denial for secrets, production config, and live deploy/model pointers;
+4. allowlisting read-only and verify commands.
 
-Hooks execute automatically on the user's machine. Show the exact command before installing it, and never install one that pushes, deploys, deletes, or writes outside the repo.
+Keep shared settings project-scoped and personal settings gitignored. Show the
+exact hook command before installation. Never add a hook that deploys, pushes,
+deletes, or writes outside the repository.
 
-## Phase 5 — Project notes file (`CLAUDE.md` / `AGENTS.md`)
+## 5. Record project knowledge
 
-Extend the notes file the repo already uses; if neither exists, create the one matching the current harness and add a one-line pointer from the other name so both find it. Write only what reading the code cannot tell you:
+Extend the notes file already used; if neither exists, create the current
+harness's file and point the other name to it. Record only facts code search
+cannot reveal:
 
-- How to run / test / verify — the commands from Phase 2
-- Architecture facts that are load-bearing and non-obvious (what serves what, which file is source of truth)
-- **Footguns and null results**: "X looks right but breaks Y", "tried A, measured no gain, do not retry", "always rebuild Z after W"
-- Where the real docs live
+- verify commands and coverage;
+- non-obvious source-of-truth or architecture constraints;
+- footguns, measured null results, and required regeneration;
+- the location of deeper documentation.
 
-Do not restate the directory tree, git history, or anything a `grep` answers. Keep it dense; every line costs context on every future session.
+Do not duplicate the tree, history, or grep-able facts. Every line becomes
+future context cost.
 
-## Phase 6 — Prove it and report
+## 6. Prove the loop
 
-1. **Flake check** — run the fast verify tier twice. A green that does not repeat is a flake, and a flaky verify makes every future red ambiguous; fixing or quarantining the flake comes before relying on the loop. (Skip the double run only when the repo has a single slow tier — say so.)
-2. **Red check** — break a line a smoke test actually covers (flip an expected value or a return), confirm verify goes red, then restore. The break is one deliberate edit: **record file, line, and original text before making it, and restore by reverting exactly that edit.** Only use `git checkout -- <file>` if the file was committed before the break — on a file carrying uncommitted work it silently discards that work too, and it cannot restore the untracked test files this skill just wrote. Never use bare `git stash` here (it sweeps the whole tree and skips untracked files). Breaking an uncovered line and staying green proves nothing. A verify command that cannot fail is not a verify command.
+- **Flake check:** run the fast tier twice. If only one slow tier exists, run it
+  once and state that limitation. A non-repeatable green is not trusted.
+- **Red check:** record a covered file, line, and original text; make one
+  deliberate break, prove verify fails, then restore exactly that edit. Do not
+  use `git checkout` on a file with user changes, and never use broad
+  `git stash`. New untracked tests require explicit restoration too.
+- Run the final full tier after restoration.
 
-Report:
-- The one command to run (both tiers if split)
-- What it does and does not cover
-- What was added, and what was deliberately left out
+Report the command(s), what each covers and does not cover, files added, and
+anything deliberately left out.

package/skills/retro/SKILL.md

@@ -3,72 +3,79 @@ name: retro
 description: Record durable lessons, null results, and footguns after hard work or debugging. Use when the user asks for a retro, dead ends need preserving, a task disproves an approach, or "จดบทเรียน". Keep repo knowledge separate from machine-local memory.
 ---
 
-# Retro — turn experience into recorded knowledge
+# Retro
 
-The doctrine says: *never re-derive a dead end twice.* This skill is the procedure that makes it actually happen. A team that logs its null results stops paying for the same experiment twice — that is the cheapest intelligence upgrade available.
+Never re-derive a dead end twice. Record only knowledge future work cannot
+recover cheaply.
 
 ## 1. Scan the session
 
-Walk back through the work just finished and list candidates:
+Ask:
 
-- What took the longest, and was the time spent where you first expected?
-- Which attempts **failed**, and what was the real cause once found?
-- What looked like the right approach but was wrong — and why exactly?
-- What surprised you: environment quirks, undocumented behavior, a flag or version that mattered?
-- What did you have to re-discover that should already have been written down?
+- What took the longest?
+- Which attempts **failed**, and why?
+- What plausible approach was wrong?
+- What environment/version/flag surprised us?
+- What had to be rediscovered?
 
-**Also read the discipline report**, if the enforcement pack is installed: use `/discipline-report`, or run the first available local form — `luciazero discipline --project . --json` when `luciazero` is on PATH, or `node <this-skill-dir>/../../bin/luciazero.js discipline --project . --json` from a source checkout/npm package. If neither exists, report that the report is unavailable offline; use `npx` only when package resolution is explicitly allowed. Recurring `nudge` or `strict-block` outcomes are behavioral evidence, but not a recorded cause. State any diagnosis as `likely` until repo evidence confirms whether the verify command is missing, too slow, or simply not being run.
+Also read the discipline report when installed: prefer local
+`luciazero discipline --project . --json`, then the checkout/package CLI.
+Use `npx` only when package resolution is explicitly allowed. A nudge or block
+is evidence, not cause; state any diagnosis as `likely` until repo evidence
+confirms it.
 
 ## 2. Filter hard
 
-Record only what **reading the code cannot tell a future agent**:
+Keep only what reading the code cannot tell a future agent:
 
-- ✅ Null results: "tried X, measured no gain / broke Y — do not retry without new evidence"
-- ✅ Footguns: "A looks correct but silently breaks B"
-- ✅ Environment facts: version pins, platform quirks, commands that must follow other commands
-- ✅ Why a tempting approach is wrong (with the one-line evidence)
-- ❌ What the diff/git history already says
-- ❌ Anything a `grep` or `--help` answers
-- ❌ Session-only details (temp paths, one-off values)
+- **Null results**: measured no gain or broke another property.
+- **Footguns**: an apparently correct action silently breaks something.
+- Environment facts, ordering constraints, and why a tempting path is wrong.
 
-A null result is worth exactly as much as a success. If the session proved nothing new, say so and stop — an empty retro is a valid result; padding it with restated code facts makes every future session pay for noise.
+Reject diff/history summaries, session-only values, and Anything a `grep` or
+`--help` answers. If nothing qualifies, stop: an empty retro is a valid result.
 
 ## 3. Route it, then write it
 
-**First decide who the lesson is true for:**
-
-- **Anyone who clones the repo** — code behavior, build quirks, disproven approaches → the committed notes below. A **debugged failure** specifically goes to the repo's lesson ledger `docs/lessons.md` in this fixed shape, so `/debug` can seed its hypothesis ledger from it next time:
+- **Anyone who clones the repo:** code/build behavior and disproven approaches.
+  A debugged failure goes to `docs/lessons.md`:
 
   ```
-  ## <one-line symptom, greppable — include the error string>
+  ## <greppable symptom; include exact error string>
   cause: <root cause> | proven-by: `<command>` | fix: <what fixed it> | date: YYYY-MM-DD
   ```
 
-- **True in every repository** — engineering lessons not tied to this codebase ("intermittent async test: check timezone pinning before touching the test") → append one line to `luciazero-heuristics.md` in the configured harness directory (`${CLAUDE_CONFIG_DIR:-$HOME/.claude}` or `${CODEX_HOME:-$HOME/.codex}`). Hard rules: one line per lesson, same update-in-place/dedup discipline, **cap the file at 100 lines** — when full, drop the weakest entry rather than growing (an unbounded heuristics file becomes context tax, the exact failure this pack exists to prevent). Never personal paths or secrets, even here.
-- **Only this machine or this user** — local paths, installed tool versions, personal preferences, credential locations → must **never** be committed. If the harness provides a persistent memory directory (Claude Code announces its per-project `memory/` dir and `MEMORY.md` index in context when enabled), write it there and update the index, applying the same format, dedup, and prune rules. If no memory system exists (Codex CLI, or memory disabled), keep only the generalization that is true for anyone who clones the repo — never personal preferences or credential locations, even generalized; if nothing repo-true remains, state the lesson in the retro report instead of writing it anywhere — an honest gap beats a note no harness will ever load.
+- **True in every repository:** append one deduplicated line to configured
+  `luciazero-heuristics.md` under `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` or
+  `${CODEX_HOME:-$HOME/.codex}` for the active harness. Never include secrets
+  or personal paths; cap the file at 100 lines and drop the weakest entry when
+  full.
+
+- **Only this machine or this user:** local paths, versions, preferences, and
+  credential locations must **never** be committed. Use announced harness
+  memory and update its `MEMORY.md` index when available. If no memory system
+  exists, keep only a repo-true generalization; otherwise report the lesson
+  without writing it.
 
-Format, one entry per lesson:
+Entry format:
 
 ```
-- **<topic>** — tried <X>; failed because <Y>; do <Z> instead. (evidence: <shortest decisive line>, <date>)
+- **<topic>** — tried <X>; failed because <Y>; do <Z> instead. (evidence: <line>, <date>)
 ```
 
-Committed destinations:
-
-- **Project notes file** (`CLAUDE.md` / `AGENTS.md` — extend the one the repo uses) — if the lesson is load-bearing for most future sessions and fits in 1–2 lines.
-- **`docs/<topic>.md`** — if it needs detail (measurements, alternatives tried, tables); then put a one-line pointer in the notes file.
-- Follow the project's existing convention if it already has an experiments log or notes dir — extend it, do not invent a parallel one.
+Use the existing Project notes file (`CLAUDE.md`/`AGENTS.md`) for 1–2
+load-bearing lines. Use `docs/<topic>.md` for detail and link it once. Follow
+existing conventions; do not create a parallel notes system.
 
 ## 4. Dedup and prune
 
-Before writing, read the existing notes (and `MEMORY.md` when routing to harness memory):
-
-- If a note on the topic exists, **update it in place** — do not append a duplicate.
-- If the session **disproved** an existing note, correct or delete it and say so in the report.
-- The same two rules govern `docs/lessons.md` and `luciazero-heuristics.md`: a ledger entry whose cause this session disproved gets corrected or deleted — a stale lesson mis-seeds every future `/debug`.
+Read destinations first. For an existing topic, update it in place. If evidence
+disproves an entry, correct or delete it. Apply this to project notes,
+`docs/lessons.md`, heuristics, and memory; a stale lesson mis-seeds future
+debugging.
 
 ## 5. Verify as a future reader
 
-Re-read each entry pretending it is six months later and context is gone. Would you know what to do differently? If an entry needs this session's context to make sense, rewrite it with the missing facts inline.
-
-Report what was recorded, where, and what was deliberately not recorded (and why).
+Read each entry as if six months later with no session context. Add the missing
+action/evidence or delete it. Report what was recorded, where, and what was
+deliberately not recorded and why.

package/skills/show/SKILL.md

@@ -3,131 +3,80 @@ name: show
 description: Visualize code structure, changes, and verification evidence in the smallest useful view. Use for connections, flows, diffs, file maps, Mermaid diagrams, evidence maps, or focused HTML; show facts and label unknowns.
 ---
 
-# Show — make the evidence visible
+# Show
 
-Answer three questions at a glance:
-
-1. What connects to what?
-2. What changed?
-3. What proves it?
-
-Build an evidence view, not a decorative diagram. The view summarizes reality;
-source files, diffs, and command results remain the ground truth.
+Answer at a glance: What connects to what? What changed? What proves it? Build
+an evidence view, not a decorative diagram; source, diff, and command output
+remain ground truth.
 
 ## 1. Set the focus
 
-Use the user's question and current task context as the input. Do not ask for
-details that can be discovered from the repository. Narrow broad requests to
-the smallest boundary that answers the question, and state that boundary.
-
-Gather only the relevant evidence:
+Use the request and repository context. Do not ask for details that can be
+discovered from the repository. State the smallest boundary that answers the
+question. Gather only:
 
 - definitions, callers, consumers, configuration, and ownership;
-- the current diff or before/after revisions;
-- verification command, exit code, shortest decisive output, and coverage gaps.
+- current diff or before/after revisions;
+- verify command, exit code, decisive output, and coverage gaps.
 
-Never expose private chain-of-thought. Show observable structure, evidence, and
-concise conclusions instead.
+Never expose private chain-of-thought. Show observable evidence and conclusions.
 
 ## 2. Normalize the evidence
 
-Reduce what was found to five kinds of information:
-
-- **Entities** — files, functions, components, services, states, or commands;
-- **Relations** — calls, owns, reads, writes, emits, depends on, or verifies;
-- **Changes** — added, removed, or modified entities and relations;
-- **Proof** — commands and observations that confirm or refute a claim;
-- **Gaps** — unknown, inferred, or unverified parts.
-
-Label inference as `? inferred`; never draw a guessed edge as fact.
+Keep five kinds: **Entities**, **Relations**, **Changes**, **Proof**, and
+**Gaps**. Label inference as `? inferred`; never draw a guessed edge as fact.
 
 ## 3. Choose the smallest useful view
 
 Prefer the first form that carries the relationship clearly:
 
-| Question | View |
-|---|---|
-| What does this logic decide? | Compact pseudocode |
-| Who calls what at runtime? | Call tree |
-| Who owns or contains what? | Component or shallow file tree |
-| How do 3+ parts exchange control or data? | Mermaid flow or sequence |
-| What changed structurally? | Before/after structural diff |
-| Why is this considered complete? | Requirement-to-proof evidence map |
-| Is prose already clearer? | One sentence or a short list; draw nothing |
-
-Use one primary view. Add a second only when it answers a different question.
-Use focused HTML only for dense UI, layout, or interactive state that text and
-Mermaid cannot show clearly. Keep HTML temporary unless the user asks to keep
-it, and open it only when the harness and user permissions allow.
+- decision → compact pseudocode;
+- runtime calls → call tree;
+- ownership → shallow tree;
+- 3+ interacting parts → Mermaid flow/sequence;
+- structural change → before/after diff;
+- completion → requirement-to-proof map;
+- clear prose → one sentence or short list.
 
-## 4. Render with a stable grammar
+Use one primary view. Add another only for a different question. Reserve focused
+HTML for dense UI or interactive state. Keep HTML temporary unless the user asks
+to keep it, and open it only with permission.
 
-Use these marks consistently in text views:
+## 4. Render with a stable grammar
 
 ```text
-A --> B              calls or moves data to
-A --owns--> B        named relationship
-+ item               added
-- item               removed
-~ item               changed
-[+] proven           verification passed
-[x] disproven        verification failed
-[?] unknown          not verified
-[path/to/file:line]  source pointer
+A --> B             calls or moves data
+A --owns--> B       named relation
++ / - / ~ item      added / removed / changed
+[+] proven
+[x] disproven
+[?] unknown
+[path/file:line]    source
 ```
 
-Keep labels concrete and short. Omit unrelated files, helper calls, props,
-states, and branches. A reader should not need a legend beyond the grammar
-above.
-
-For Mermaid, keep node IDs simple, quote labels containing punctuation, and
-put source pointers outside the diagram when they would make nodes noisy.
+Keep labels concrete and short. Omit unrelated detail. For Mermaid, keep node IDs
+simple, quote punctuation-heavy labels, and put noisy source pointers outside.
 
 ## 5. Attach evidence
 
-Every important node or edge must be traceable to at least one of:
-
-- `path/to/file:line` for source structure;
-- a diff hunk or revision for a change;
-- an exact command, exit code, and shortest decisive output for proof.
-
-Do not use a green-looking diagram as verification. If no command ran, write
-`not run`. If a check does not cover a shown claim, mark that claim `[?]` and
-name the missing coverage. Failed proof remains visible as `[x]`; do not hide it
-to make the view look complete.
+Every important node or edge must be traceable to source, a diff/revision, or
+an exact command, exit code, and shortest decisive output. A green-looking view
+is not verification. If no command ran, write `not run`. If proof misses a
+claim, mark that claim `[?]` and name the gap; keep failed proof visible.
 
 ## Output contract
 
-Return, in this order:
+Return in order:
 
-1. **Answer** — one or two sentences naming the focus and conclusion.
-2. **View** — the smallest useful visual.
+1. **Answer** — focus and conclusion in 1–2 sentences.
+2. **View** — smallest useful visual.
 3. **Sources** — compact file/line or revision pointers.
-4. **Proof** — command, exit code, and decisive output; or `not run`.
-5. **Unknowns** — uncovered or inferred parts; omit only when there are none.
-
-For a completed change, an evidence map may look like:
-
-```text
-request
-  --> ~ skills/catalog.txt
-  --> + skills/show/SKILL.md
-  --> ~ README.md / README.th.md
-        |
-        +--verified by--> [+] ./test.sh (exit 0)
-                           `PASS  all checks green`
-
-[?] Real invocation in a fresh agent session was not exercised.
-```
+4. **Proof** — command, exit code, decisive output; or `not run`.
+5. **Unknowns** — omit only when none exist.
 
 ## Fit into the Luciazero loop
 
-- With `/ready`, show the path from CI to the repository verify command.
-- With `/plan`, show the proposed before/after boundary and acceptance proof.
-- With `/debug`, show hypothesis → observation → conclusion without replacing
-  the reproduction or hypothesis ledger.
-- With `/done`, show requirement → changed artifact → verification evidence.
-- With `/lucia-relay`, show current state → next action → blocker.
-
-The lifecycle skill owns the work and verification. `/show` only makes its
-structure and evidence easier to inspect.
+Lifecycle skills own work and proof: `/ready` CI→verify, `/plan` boundary,
+`/debug` hypothesis→observation, `/done` requirement→proof, and
+`/lucia-relay` state→next action. The lifecycle skill owns the work and
+verification. `/show` only exposes its structure.