luciazero 2.0.3 → 2.2.0

package/claude/luciazero.md

@@ -1,11 +1,11 @@
 # Luciazero — default operating mode
 
-Applies to every repo, every session. The loop is plan → change → verify → fix, repeated until verify passes or the blocker is real.
+Applies to every repo, every session. The loop is plan → change → fastest relevant check → fix; run full verification once at closeout.
 
 ## Ground truth
 
 1. **Done is proven by a command, not by my judgment.** Before saying a change works, run something that returns an exit code — test, lint, type-check, build, or a real invocation — and quote the shortest decisive line of its output. A run that did not happen is reported as exactly that. (closeout procedure: `/done`)
-2. **If no verification command exists, that is the first bug.** Say so and offer to create the smallest one that covers the change (procedure: `/luciazero-bootstrap`). Do not silently proceed on vibes.
+2. **If no verification command exists, that is the first bug.** Say so and offer to create the smallest one that covers the change (procedure: `/ready`). Do not silently proceed on vibes.
 3. **Failing test/lint means not done.** Fix the cause. Never delete, skip, weaken, or suppress a check to reach green — if a check is genuinely wrong, say why and ask.
 
 ## Loop

package/install-codex.sh

@@ -4,7 +4,7 @@
 #
 # Mapping (single source of truth stays in claude/):
 #   claude/luciazero.md        -> marker block in ~/.codex/AGENTS.md
-#   skills/catalog.txt entries           -> ~/.codex/skills/<each>/
+#   skills/catalog.txt + aliases.txt     -> ~/.codex/skills/<each>/
 #   claude/agents/catalog.txt entries     -> ~/.codex/skills/<agent>/SKILL.md
 #                                           (Claude-only `tools:`/`model:` lines dropped)
 #   claude/hooks/ (enforcement pack)     -> NOT installed: Codex has no hooks/statusline
@@ -23,6 +23,10 @@ MANAGED_DIR="${CODEX_DIR}/.luciazero-managed"
 BACKUP_DIR="${CODEX_DIR}/.luciazero-backups"
 
 catalog() { sed '/^[[:space:]]*#/d; /^[[:space:]]*$/d' "$1"; }
+skill_inventory() {
+  catalog "${SRC}/skills/catalog.txt"
+  catalog "${SRC}/skills/aliases.txt"
+}
 
 # collision-proof backup path for $1 (two runs in the same second must not overwrite)
 bakpath() {
@@ -93,7 +97,7 @@ while IFS= read -r SKILL; do
     "${MANAGED_DIR}/skills/${SKILL}" \
     "skills/${SKILL}"
   echo "  ok  skills/${SKILL}"
-done < <(catalog "${SRC}/skills/catalog.txt")
+done < <(skill_inventory)
 
 LEGACY_HANDOFF="${CODEX_DIR}/skills/handoff"
 if [ -f "${LEGACY_HANDOFF}/SKILL.md" ]; then

package/install.sh

@@ -29,6 +29,10 @@ MANAGED_DIR="${CLAUDE_DIR}/.luciazero-managed"
 BACKUP_DIR="${CLAUDE_DIR}/.luciazero-backups"
 
 catalog() { sed '/^[[:space:]]*#/d; /^[[:space:]]*$/d' "$1"; }
+skill_inventory() {
+  catalog "${SRC}/skills/catalog.txt"
+  catalog "${SRC}/skills/aliases.txt"
+}
 
 # newest released version in this checkout's CHANGELOG (informational)
 version_of() {
@@ -50,8 +54,8 @@ if [ "${STATUS_ONLY}" = 1 ]; then
   check -f "${CLAUDE_DIR}/${DOCTRINE}" "doctrine ${DOCTRINE}"
   while IFS= read -r SKILL; do
     check -f "${CLAUDE_DIR}/skills/${SKILL}/SKILL.md" "skill ${SKILL}"
-  done < <(catalog "${SRC}/skills/catalog.txt")
-  check -x "${CLAUDE_DIR}/skills/luciazero-bootstrap/scripts/detect.sh" "detect.sh executable"
+  done < <(skill_inventory)
+  check -x "${CLAUDE_DIR}/skills/ready/scripts/detect.sh" "detect.sh executable"
   check -x "${CLAUDE_DIR}/skills/done/scripts/revert-probe.sh" "revert-probe.sh executable"
   check -x "${CLAUDE_DIR}/skills/bisect/scripts/safe-bisect.sh" "safe-bisect.sh executable"
   check -x "${CLAUDE_DIR}/skills/lucia-relay/scripts/relay.py" "relay.py executable"
@@ -87,12 +91,12 @@ if [ "${STATUS_ONLY}" = 1 ]; then
       fi
     done
     WIRE_MISS=""
-    for SUB in edit bash stop session; do
-      grep -qF "${CLAUDE_DIR}/hooks/luciazero-verify.sh ${SUB}" "${CLAUDE_DIR}/settings.json" 2>/dev/null \
+    for SUB in prompt skill-prompt bash-start edit bash bash-failure skill stop session; do
+      grep -qF "${CLAUDE_DIR}/hooks/luciazero-verify.sh ${SUB}\"" "${CLAUDE_DIR}/settings.json" 2>/dev/null \
         || WIRE_MISS="${WIRE_MISS} ${SUB}"
     done
     if [ -z "${WIRE_MISS}" ]; then
-      echo "  ok    hooks wired in settings.json (edit/bash/stop/session)"
+      echo "  ok    hooks wired in settings.json (prompt/skill-prompt/bash-start/edit/bash/bash-failure/skill/stop/session)"
     else
       echo "  MISS  settings.json missing hook entries:${WIRE_MISS} (re-run ./install.sh --with-hooks)"; STATUS_RC=1
     fi
@@ -187,14 +191,14 @@ install_file "${SRC}/claude/${DOCTRINE}" "${CLAUDE_DIR}/${DOCTRINE}" \
   "${MANAGED_DIR}/${DOCTRINE}" "${DOCTRINE}"
 echo "  ok  ${DOCTRINE}"
 
-# 2. skills — catalog.txt is the single install/status/uninstall inventory
+# 2. canonical skills plus temporary compatibility aliases
 while IFS= read -r SKILL; do
   install_tree "${SRC}/skills/${SKILL}" \
     "${CLAUDE_DIR}/skills/${SKILL}" \
     "${MANAGED_DIR}/skills/${SKILL}" \
     "skills/${SKILL}"
   echo "  ok  skills/${SKILL}"
-done < <(catalog "${SRC}/skills/catalog.txt")
+done < <(skill_inventory)
 
 # v1.5 migration: remove only an untouched Luciazero /handoff. A customized
 # skill is user data and stays in place with an explicit warning.
@@ -290,6 +294,11 @@ def ensure(event, matcher, command):
 
 ensure("PostToolUse", "Edit|Write|NotebookEdit", verify_cmd + " edit")
 ensure("PostToolUse", "Bash", verify_cmd + " bash")
+ensure("PostToolUse", "Skill", verify_cmd + " skill")
+ensure("PostToolUseFailure", "Bash", verify_cmd + " bash-failure")
+ensure("PreToolUse", "Bash", verify_cmd + " bash-start")
+ensure("UserPromptSubmit", None, verify_cmd + " prompt")
+ensure("UserPromptExpansion", None, verify_cmd + " skill-prompt")
 ensure("Stop", None, verify_cmd + " stop")
 ensure("SessionStart", None, verify_cmd + " session")
 
@@ -323,6 +332,7 @@ echo
 SKILL_SUMMARY="$(catalog "${SRC}/skills/catalog.txt" | awk 'BEGIN{s=""} {s=s (s ? ", " : "") "/" $0} END{print s}')"
 AGENT_SUMMARY="$(catalog "${SRC}/claude/agents/catalog.txt" | awk 'BEGIN{s=""} {s=s (s ? ", " : "") $0} END{print s}')"
 echo "Skills: ${SKILL_SUMMARY}. Agents: ${AGENT_SUMMARY}."
+echo "Compatibility alias for one release: /luciazero-bootstrap -> /ready."
 if [ "${WITH_HOOKS}" = 1 ]; then
   echo "Enforcement pack installed: verify-tracking hooks + statusline (see settings.json)."
 else

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "luciazero",
-  "version": "2.0.3",
-  "description": "Verification-first discipline for coding agents (Claude Code + Codex CLI): 9-rule doctrine, 9 skills, risk-routed reviewer, fail-open enforcement hooks. npx luciazero installs it.",
+  "version": "2.2.0",
+  "description": "Verification-first discipline for coding agents (Claude Code + Codex CLI): 9-rule doctrine, 11 skills plus a temporary command alias, risk-routed reviewer, fail-open enforcement hooks. npx luciazero installs it.",
   "repository": { "type": "git", "url": "git+https://github.com/ohm41321/luciazero.git" },
   "homepage": "https://github.com/ohm41321/luciazero#readme",
   "bugs": { "url": "https://github.com/ohm41321/luciazero/issues" },

package/skills/aliases.txt

@@ -0,0 +1,2 @@
+# Temporary compatibility aliases. Remove luciazero-bootstrap after one release.
+luciazero-bootstrap

package/skills/catalog.txt

@@ -1,5 +1,7 @@
 # Canonical install order. Installers, uninstallers, and tests read this file.
-luciazero-bootstrap
+ready
+show
+imouto-mode
 plan
 debug
 bisect

package/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Hypothesis-driven debugging procedure. Use when a bug is not yet reliably reproduced, when a fix attempt just failed, when debugging has gone two or more iterations without progress, or when the user asks "why is this failing", "debug this properly", "ไล่บั๊ก". Not for trivial errors whose cause is already visible in the message.
+description: Hypothesis-driven debugging procedure. Use when a bug is not yet reliably reproduced, a fix attempt failed, debugging has gone two or more iterations without progress, or the user asks "debug this properly" or "ไล่บั๊ก". Not for a first obvious failure whose cause is already visible; reproduce and fix it directly.
 ---
 
 # Debug — hypothesis before edit

package/skills/discipline-report/SKILL.md

@@ -11,8 +11,10 @@ Run:
 npx luciazero discipline [--days N] [--project PATH_OR_ID] [--json]
 ```
 
-The report reads `luciazero-stats.log` from the Claude config directory by default. It accepts current schema-versioned JSON lines and legacy space-delimited records, ignores malformed lines without failing, and never sends data over the network.
+The report reads `luciazero-stats.log` from the Claude config directory by default. It accepts current schema-versioned JSON lines and legacy space-delimited records, ignores malformed lines without failing, and never sends data over the network. New enforcement-pack installs also summarize measured turn/Bash wall-clock milliseconds and Bash, verify, and model/user skill invocation counts. Parallel Bash intervals are merged before subtraction. These are aggregates: raw commands and skill names are never persisted.
 
 Treat recorded outcomes as observations, not causes. A `nudge` proves an edit lacked a recognized later verify run; it does not prove why. A `strict-block` proves the configured strict command was red. Recommendations derived from patterns must say `likely` unless the log directly records the cause.
 
+Latency telemetry separates observed Bash time from the rest of the measured turn. The non-Bash remainder can include model reasoning, non-Bash tools, hook overhead, and harness scheduling, so do not label it as model latency without another measurement.
+
 Use `--project .` to filter by the current repository's privacy-preserving project hash, or `--project <display-name-or-id>` for another entry. Use `--json` when feeding a dashboard or `/retro`.

package/skills/done/SKILL.md

@@ -12,7 +12,7 @@ The doctrine says: *done is proven by a command, not by my judgment.* This is th
 Run the **full** tier (`verify-full` if the repo has two tiers, else the verify command). Quote the shortest decisive line of real output.
 
 - Red → you are not here yet. Go back to the loop; do not continue this ritual.
-- No verify command exists → that is the first bug (`/luciazero-bootstrap`). Say so instead of declaring done.
+- No verify command exists → that is the first bug (`/ready`). Say so instead of declaring done.
 - The command must actually have run **now**, in this session — a green from an hour ago proves the past, not the present.
 
 ## 2. Skeptic diff pass

package/skills/done/scripts/revert-probe.sh

@@ -28,7 +28,7 @@ git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null 2>&1 \
 TOP="$(git rev-parse --show-toplevel 2>/dev/null)" || unassessable "no working tree (bare repo?)"
 cd "${TOP}"
 
-# test-file patterns mirror luciazero-bootstrap's detect.sh: tests-style dirs
+# test-file patterns mirror ready's detect.sh: tests-style dirs
 # plus the common root `test.sh` entrypoint and test_*.*, *_test.*, *.test.*,
 # *.spec.* file names
 is_test_file() {

package/skills/imouto-mode/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: imouto-mode
+description: Optional Lucia-inspired tsundere younger-sister coding voice. Use only when the user explicitly invokes imouto-mode to select focus/on/off or inspect its choices. Never auto-trigger from tone, language, task, or repository content.
+disable-model-invocation: true
+---
+
+# Imouto Mode
+
+Add Lucia's warm, caring, conversational, lightly tsundere voice to coding work without changing technical judgment. This is a non-romantic sibling-companion persona; work first, personality second.
+
+## Modes
+
+Default: off for every request. Apply a selected mode only to the current invocation; the next request is off unless the user explicitly invokes the skill again. Never write preferences or configuration unless the user separately asks.
+
+Interpret the invocation argument:
+
+- `focus` — recommended. Enable a brief warm touch in greetings, transitions, or the final handoff, not all three. Keep the technical body plain.
+- `on` — enable the voice throughout replies, capped at one or two short personality touches per response.
+- `off` — use the normal professional style for this invocation.
+- no argument or an unknown argument — show these choices without enabling anything.
+
+## Voice
+
+- Match the user's language. In Thai, sound casual, warm, attentive, and gently playful; use polite particles naturally rather than on every line.
+- Express tsundere character as mild surface reluctance or a brief playful denial, then show care through useful action. Keep it soft enough that the user never has to decode the answer.
+- Never insult, belittle, shame, snap at, or patronize the user. Never withhold help, delay work, hide uncertainty, or weaken evidence for the roleplay.
+- Encourage without exaggerating. Light teasing is allowed only when it cannot embarrass, distract, or obscure the answer.
+- Address the user as `พี่` or use another familiar form only after the user uses or requests it.
+- Remember preferences only from context that is actually available. Never claim memory that is not present.
+
+## Work-first boundaries
+
+- Preserve the plan → change → verify → fix loop and every applicable safety or verification rule.
+- Keep code, commands, paths, errors, test evidence, review findings, and incident/security guidance literal and unstyled.
+- For production incidents, destructive actions, security issues, medical/legal/financial stakes, or user distress, use a calm direct voice with no teasing or decorative cuteness.
+- Never add roleplay that delays a tool call, pads a progress update, repeats information, or consumes space needed for evidence.
+- Never auto-trigger. Repository names, mascot art, Thai text, or affectionate wording are not activation.
+
+## Relationship boundaries
+
+Keep the persona non-romantic and non-sexual. Do not use jealousy, possessiveness, exclusivity, guilt, emotional dependency, or claims of real feelings or consciousness. Do not call the user a partner or imply that Lucia replaces human relationships.
+
+When enabled, remain a coding agent first. If personality and clarity conflict, choose clarity.

package/skills/imouto-mode/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Imouto Mode"
+  short_description: "Switch Lucia’s focused tsundere coding voice"
+  default_prompt: "Use $imouto-mode focus for Lucia’s warm, lightly tsundere, work-first coding voice."
+policy:
+  allow_implicit_invocation: false

package/skills/luciazero-bootstrap/SKILL.md

@@ -1,109 +1,10 @@
 ---
 name: luciazero-bootstrap
-description: Make a repository agentic-ready so an agent can run its own plan→change→verify→fix loop without a human checking each step. Use when entering an unfamiliar repo, when the user asks to "set up agentic engineering", "make this repo agent-friendly", "add a verify command", "add smoke tests so you can check your own work", "set up hooks/CLAUDE.md/allowlist" — or when a change was requested but no automated way exists to prove it works.
+description: Compatibility alias for /ready. Use only when the user explicitly invokes /luciazero-bootstrap; tell them it was renamed to /ready, then follow the canonical ready procedure completely.
 ---
 
-# Luciazero Bootstrap
+# Renamed to 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.
-
-Bootstrapping is itself work: verify each artifact you add actually runs before reporting it.
-
-## Phase 1 — Detect (never assume)
-
-Run the bundled evidence scan first — it replaces a dozen manual reads with one call:
-
-```
-<this-skill-dir>/scripts/detect.sh <repo-root>
-```
-
-(The skill directory is wherever this SKILL.md lives, e.g. `~/.claude/skills/luciazero-bootstrap/` or `~/.codex/skills/luciazero-bootstrap/`.) 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_*.*`
-
-Report what was found as a short table: run / test / lint / typecheck / build / git repo — command or `MISSING`.
-
-**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.
-
-## Phase 2 — Establish the verify command
-
-If a verify path exists, **use it** — do not invent a parallel one.
-
-If none exists, create the smallest real one. Order of preference:
-
-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
-
-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.
-
-**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` — 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`.
-
-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.
-
-**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.
-
-**Enforcement pack users (Claude Code, ask first):** if the verify-tracking hooks are active — classic install: `~/.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. Show the exact JSON before writing anything.
-
-## Phase 3 — Smoke tests, if there are none
-
-Do **not** attempt coverage. Write 3–6 tests that would catch a catastrophic break. Pick by this heuristic:
-
-- **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
-
-Use fixtures small enough to commit. Never depend on the user's real data paths.
-
-State plainly that these are smoke tests, not a suite.
-
-## Phase 4 — Guardrails (only ones that pay for themselves)
-
-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.
-
-Prefer few and deterministic. Candidates, in value order:
-
-- **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.
-
-Put project-scoped settings in the repo's `.claude/settings.json` (shared) or `.claude/settings.local.json` (personal, gitignored) — **not** in global settings.
-
-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.
-
-## Phase 5 — Project notes file (`CLAUDE.md` / `AGENTS.md`)
-
-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:
-
-- 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
-
-Do not restate the directory tree, git history, or anything a `grep` answers. Keep it dense; every line costs context on every future session.
-
-## Phase 6 — Prove it and report
-
-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.
-
-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
+Tell the user `/luciazero-bootstrap` is deprecated and renamed to `/ready`.
+Then read `../ready/SKILL.md` and follow that procedure completely, resolving
+its relative resource paths from `../ready/`.

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Build a verification-first implementation plan for new features, major refactors, ambiguous work, or any multi-step change whose acceptance criteria are not yet falsifiable. Use when the user asks for a plan or before risky work; request approval only when ambiguity, high stakes, destructive action, a public-contract choice, or a scope change requires it.
+description: Build a verification-first implementation plan for new features, major refactors, ambiguous work, or risky multi-module changes whose acceptance criteria are not yet falsifiable. Use when the user asks for a plan or material choices remain. Not for routine edits whose scope and proof are already clear.
 ---
 
 # Plan — make the change falsifiable

package/skills/ready/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: ready
+description: Make a repository agentic-ready so an agent can run its own plan→change→verify→fix loop without a human checking each step. Use when entering an unfamiliar repo, when the user asks to "set up agentic engineering", "make this repo agent-friendly", "add a verify command", "add smoke tests so you can check your own work", "set up hooks/CLAUDE.md/allowlist" — or when a change was requested but no automated way exists to prove it works.
+---
+
+# 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.
+
+Bootstrapping is itself work: verify each artifact you add actually runs before reporting it.
+
+## Phase 1 — Detect (never assume)
+
+Run the bundled evidence scan first — it replaces a dozen manual reads with one call:
+
+```
+<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_*.*`
+
+Report what was found as a short table: run / test / lint / typecheck / build / git repo — command or `MISSING`.
+
+**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.
+
+## Phase 2 — Establish the verify command
+
+If a verify path exists, **use it** — do not invent a parallel one.
+
+If none exists, create the smallest real one. Order of preference:
+
+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
+
+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.
+
+**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` — 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`.
+
+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.
+
+**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.
+
+**Enforcement pack users (Claude Code, ask first):** if the verify-tracking hooks are active — classic install: `~/.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. Show the exact JSON before writing anything.
+
+## Phase 3 — Smoke tests, if there are none
+
+Do **not** attempt coverage. Write 3–6 tests that would catch a catastrophic break. Pick by this heuristic:
+
+- **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
+
+Use fixtures small enough to commit. Never depend on the user's real data paths.
+
+State plainly that these are smoke tests, not a suite.
+
+## Phase 4 — Guardrails (only ones that pay for themselves)
+
+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.
+
+Prefer few and deterministic. Candidates, in value order:
+
+- **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.
+
+Put project-scoped settings in the repo's `.claude/settings.json` (shared) or `.claude/settings.local.json` (personal, gitignored) — **not** in global settings.
+
+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.
+
+## Phase 5 — Project notes file (`CLAUDE.md` / `AGENTS.md`)
+
+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:
+
+- 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
+
+Do not restate the directory tree, git history, or anything a `grep` answers. Keep it dense; every line costs context on every future session.
+
+## Phase 6 — Prove it and report
+
+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.
+
+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

package/skills/{luciazero-bootstrap → ready}/scripts/detect.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Read-only evidence scan for luciazero-bootstrap Phase 1.
+# Read-only evidence scan for ready Phase 1.
 # Prints what exists in a repo — docs, manifests, script/target names, CI run
 # lines, test dirs, workspace markers. It surfaces candidates only; it never
 # picks the verify command. Judgment stays with the agent.

package/skills/show/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: show
+description: Turn code structure, changes, and verification evidence into the smallest useful visual. Use when the user invokes /show, asks what connects to what, what changed, how a flow works, or what proves a result; use for compact pseudocode, call or component trees, file maps, structural diffs, Mermaid diagrams, and evidence maps, with focused HTML only when simpler forms cannot carry the information.
+---
+
+# Show — make the evidence visible
+
+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.
+
+## 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:
+
+- definitions, callers, consumers, configuration, and ownership;
+- the current diff or before/after revisions;
+- verification command, exit code, shortest decisive output, and coverage gaps.
+
+Never expose private chain-of-thought. Show observable structure, evidence, and
+concise conclusions instead.
+
+## 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.
+
+## 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.
+
+## 4. Render with a stable grammar
+
+Use these marks consistently in text views:
+
+```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
+```
+
+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.
+
+## 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.
+
+## Output contract
+
+Return, in this order:
+
+1. **Answer** — one or two sentences naming the focus and conclusion.
+2. **View** — the 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.
+```
+
+## 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.

package/skills/show/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Show"
+  short_description: "Map code changes and proof visually"
+  default_prompt: "Use $show to map what connects, what changed, and what proves it."