@alecsibilia/luca 13.0.0-alpha.1

package/dist/claude/skills/gh-prepare/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: gh-prepare
+description: "Ship committed work: ensure a changeset, push the feature branch, open a draft PR. Works standalone (outside the Luca pipeline) or within it. Use when user says \"prepare\", \"ship this\", \"open a PR\", \"push and PR\", or invokes /gh-prepare."
+---
+
+# GH Prepare
+
+Ship committed work to GitHub. Handles the mechanical steps between "code is done" and "PR is open": branch hygiene, changeset, push, and PR creation. No issue creation — that's external ideation handled by `gh-issue-triage`.
+
+## Process
+
+### 1. Detect context
+
+```bash
+git remote -v                  # confirm GitHub remote exists
+git branch --show-current      # current branch
+git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo main  # default branch
+git status --porcelain         # dirty tree check
+git log --oneline origin/<defaultBranch>..HEAD 2>/dev/null  # commits ahead of default branch
+```
+
+Gather:
+- `currentBranch` — the branch we're on
+- `defaultBranch` — usually `main`
+- `hasDirtyTree` — uncommitted changes exist
+- `commitsAheadOfDefault` — commits ahead of `origin/<defaultBranch>`
+- `hasUpstream` — whether the current branch has a tracking upstream (`git rev-parse --abbrev-ref @{u}`)
+- `hasRemote` — GitHub remote exists
+
+If no GitHub remote is detected, stop and tell the user.
+
+If the working tree is dirty, warn: "You have uncommitted changes. Commit or stash them first." Do not proceed with a dirty tree — changeset and PR diffs will be wrong.
+
+If `hasUpstream` is true and there are no unpushed commits relative to the upstream (`@{u}..HEAD` is empty) AND the branch is already pushed, stop: "Nothing to ship — branch is up to date with its upstream."
+
+If on the default branch and `commitsAheadOfDefault` is empty (HEAD matches `origin/<defaultBranch>`), stop: "Nothing to ship — HEAD is up to date with origin/<defaultBranch>."
+
+### 2. Branch hygiene
+
+**If on `main` or `defaultBranch`:**
+
+The commits shouldn't have been made directly to main. Create a feature branch and move the commits onto it:
+
+```bash
+# Determine branch name from commit messages
+# Parse type from conventional commit prefix (feat, fix, refactor, chore)
+# Slugify the first commit's subject for the branch name
+git checkout -b <type>/<slug>
+# The commits are now on the new branch; move local defaultBranch back to origin
+git branch -f <defaultBranch> origin/<defaultBranch>
+# This only rewrites the local branch ref; do not force-push
+```
+
+Check whether the branch name already exists on the remote:
+```bash
+git ls-remote --heads origin <branch-name>
+```
+If it exists, warn and ask the user whether to reuse it or pick a different name.
+
+**If already on a feature branch:**
+
+Use the current branch as-is. No action needed.
+
+### 3. Consult preferences
+
+**At skill start**, read project preferences once and reuse the result:
+
+```
+luca preferences read
+```
+
+This prints the project's `ProjectPreferences` object (`.luca/config.json#preferences`, with `ProjectPreferencesSchema` defaults applied to unset sections). Destructure `{ release, pr, tracker, commits, branching }` and reuse them throughout this skill.
+
+### 4. Changeset (if applicable)
+
+Check whether the repo uses changesets (`release.tool === 'changesets'` AND `.changeset/config.json` exists):
+```bash
+test -f .changeset/config.json
+```
+
+If yes:
+1. Check whether a changeset already exists for this work:
+   ```bash
+   find .changeset -maxdepth 1 -type f -name '*.md' ! -name 'README.md'
+   ```
+2. **Before writing a new changeset**, recall MuninnDB for changeset-authoring learnings (frontmatter conventions, package-name canonicalisation, per-package release-note patterns) — supplements the structured `release` preferences with historical pitfalls:
+
+   ```
+   mcp__muninn__muninn_recall({
+     vault: "<repo_vault>",
+     context: ["changeset format", "release-note pitfalls"],
+     mode: "semantic",
+     limit: 5
+   })
+   ```
+
+   Resolve `<repo_vault>` from `.luca/config.json` → `muninn.vault`, falling back to `"default"`. Apply directly relevant findings. If MuninnDB is unreachable, log and continue — never block.
+3. If no changeset exists, create one:
+   - Determine the bump level from `release.versionBump[<commit-type>]`. The commit type comes from the branch prefix or the dominant commit type.
+   - Read package names from `.changeset/config.json` `"fixed"` groups or workspace `package.json` files
+   - Write `.changeset/<slug>.md` with the resolved bump level and summary
+   - `git add .changeset/<slug>.md && git commit -m "chore: add changeset"`
+4. If a changeset already exists, verify it looks correct (right packages, right bump level). Don't duplicate.
+
+Skip if `--no-changeset` is provided or if no `.changeset/config.json` exists.
+
+### 5. Push branch
+
+```bash
+git push -u origin <branch-name>
+```
+
+If the push fails (e.g. the branch already exists with divergent history), report the error and stop. Do not force-push.
+
+### 6. Discover the linked issue
+
+Check whether this work originated from a triaged GitHub issue:
+
+1. **From the todo backlog**: run `luca todo list`, execute the printed `mcp__muninn__muninn_recall` instruction, and look for a todo whose work matches the current branch. If that todo has `source: "gh-issue-#<N>"`, that's the linked issue.
+2. **From MuninnDB**: recall recent `gh-prepare` memories or pipeline state that reference an issue number for this branch.
+3. **From the branch name**: if the branch is named `feat/42-something`, extract `#42` as a candidate and verify it exists: `gh issue view 42 --json state`.
+4. **From commit messages**: scan for `#N` references.
+
+If an issue is found, build the issue-link line from `tracker.linkFormat` (e.g. `Closes #{issue}` → `Closes #42`). If no issue is found, that's fine — not all work originates from an issue. Omit the line.
+
+### 7. Create the draft PR
+
+Render the PR title from `pr.titleTemplate ?? pr.titleFormat`. Substitute the project's tokens (`{type}`, `{scope}`, `{version}`, `{issue}`, `{description}`) with values derived from the branch and commits. If `pr.forbidden[]` is set, reject any title matching one of those patterns.
+
+The `--draft` flag is governed by `pr.draftByDefault`:
+
+```bash
+DRAFT_FLAG=""
+if [ "<pr.draftByDefault>" = "true" ]; then DRAFT_FLAG="--draft"; fi
+gh pr create $DRAFT_FLAG \
+  --title "<rendered title>" \
+  --body "<body>"
+```
+
+PR body template (rendered from `pr.bodyTemplate` when present; default template below):
+
+```markdown
+<tracker.linkFormat-rendered line, if a linked issue was found>
+
+## What
+
+<summary derived from commit messages — what changed>
+
+## Why
+
+<problem being solved, derived from commit messages and branch context>
+
+## How
+
+<brief technical approach, derived from diff stats>
+
+## Test Plan
+
+<how to verify — inferred from test files changed, or "Manual verification" if none>
+```
+
+Derive `type` from the branch prefix or dominant commit type (validated against `commits.types ?? branching.types`). Derive `scope` from the primary package or area changed. Apply scope-allowlist validation only when `commits.scopes.length > 0` — an empty array means "no allowlist enforced" (any scope permitted), not "no scopes allowed".
+
+### 8. Store in MuninnDB
+
+Remember the result for later recall (by the pipeline, other sessions, or dedup). The `gh-prepare` concept is project-scoped — it routes to the **repo** vault:
+
+```
+mcp__muninn__muninn_remember({
+  vault: "<repo_vault>",
+  concept: "gh-prepare",
+  content: "Shipped: branch <name>, PR #<M> (<url>). <Closes #N if linked.> Work: <description>",
+  tags: ["gh-prepare", "branch", "pr"],
+  entities: [
+    { name: "pr-<M>", type: "github-pr" },
+    { name: "<branch-name>", type: "git-branch" }
+  ]
+})
+```
+
+### 9. Pipeline integration
+
+Run `luca state read`. If a Luca pipeline is active (`pipelineStep` is not `idle`/`complete`), later pipeline steps discover this PR by recalling the `gh-prepare` memory from Step 8 — no separate workflow-state write is needed. If no pipeline is active, skip — the skill works standalone.
+
+### 10. Report
+
+Print a clean summary:
+
+```
+Branch: feat/42-add-webhook-support (pushed)
+PR:     #43 (draft) — https://github.com/<owner>/<repo>/pull/43
+Issue:  Closes #42 on merge
+```
+
+Or, if no linked issue:
+
+```
+Branch: feat/add-webhook-support (pushed)
+PR:     #43 (draft) — https://github.com/<owner>/<repo>/pull/43
+```
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--no-changeset` | Skip changeset creation even if `.changeset/config.json` exists |
+| `--no-pr` | Push the branch only, skip PR creation |
+| `--title="..."` | Override the PR title |
+| `--issue=<N>` | Explicitly link to issue #N instead of auto-discovering |

package/dist/claude/skills/grill-me/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: grill-me
+description: "Interview the user relentlessly about a plan or design until reaching shared understanding. Walks each branch of the decision tree, resolving dependencies one-by-one. Updates docs/context.md and offers ADRs when decisions crystallize. Use when user says \"grill me\", \"stress-test this plan\", \"poke holes\", \"challenge my design\", or invokes /grill-me."
+---
+
+# Grill Me
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions **one at a time**, waiting for feedback before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead of asking.
+
+## During the Session
+
+### Challenge against the glossary
+
+If a `docs/context.md` exists, read it first — it is the project's domain glossary. (Check the repo root for a legacy `context.md` as a fallback.) When the user uses a term that conflicts with the existing language, call it out immediately: "Your glossary defines 'X' as Y, but you seem to mean Z — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code does X, but you just said Y — which is right?"
+
+### Update the glossary inline
+
+When a term is resolved, update `docs/context.md` right there — don't batch these up. Create the file lazily at `docs/context.md` if it doesn't exist. The glossary is a plain project doc, not a `.luca/` pipeline artifact — `docs/` keeps it out of the strict `.luca/` contract and out of repo-root markdown debris.
+
+Don't couple the glossary to implementation details. Only include terms meaningful to domain experts.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when **all three** are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR.

package/dist/claude/skills/lu/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: lu
+description: Unified entry point for all Luca workflows with cognitive pre-flight and complexity routing.
+---
+
+<main>
+The single entry point for the Luca pipeline. This SKILL is the long-form companion to the modernized `/lu` slash command — it drives the pipeline loop end-to-end: triage → research → discuss → architect → plan → plan-review → execute → checks → verify → review → learn → milestone.
+
+**Arguments:** `<task-description> [--complexity=TRIVIAL|SIMPLE|MODERATE|COMPLEX|CRITICAL] [--force-complex] [--skip-memory] [--skip-branch]`
+
+**CRITICAL:** You are the **orchestrator**. You do not write code or planning artifacts directly — you read state, run each step (delegating to its skill or subagent), and advance the pipeline via `luca state advance`.
+
+</main>
+
+<sub-agent_delegation_requirements>
+This skill uses TWO delegation mechanisms:
+
+**Skill tool** — for workflow sub-skills (phase-discuss, phase-plan, phase-execute, etc.)
+
+- Invoke: `Skill(skill: "skill-name", args: "...")`
+- Each invoked skill loads its own SKILL.md with full instructions
+- Users see visual skill headers for each step
+
+**Task tool** — for specialized subagents (luca-researcher, luca-plan-reviewer, luca-verifier, luca-reviewer, luca-learner)
+
+- Invoke: `Task(agent: "agent-name", prompt: "...")`
+- Subagents run inside a fresh sub-context
+
+### Model Resolution
+
+Models are resolved at runtime via `resolveModelForAgent(agentName, complexity)` from the centralized routing table (`src/complexity/__helpers/model-routing.ts`). The skill does not pick model strings — it spawns the named agent and the routing layer handles tier selection.
+
+</sub-agent_delegation_requirements>
+
+<workflow>
+Execute these steps in order. Each step is either a Task tool call (for subagents) or a Skill tool call (for sub-skills).
+
+### Step 0: Read state
+
+Run `luca state read`. Branch on `pipelineStep`:
+
+- `idle` or `complete` → fresh start. Go to **Triage**.
+- anything else → the pipeline is mid-flight. Skip triage, go straight to **Pipeline loop** and resume from the current step.
+
+If the user passed a request but the pipeline is already mid-flight, surface that to the user and ask whether to resume the current run or finish it first — do NOT silently discard either.
+
+### Triage
+
+Triage runs once, at the start of a run. It is inline here — there is no separate triage skill.
+
+1. **Classify complexity.** Read the request. Pick one of `TRIVIAL | SIMPLE | MODERATE | COMPLEX | CRITICAL` based on file count, scope, and risk. There is no CLI command to persist complexity — record it in your reasoning and pass it to every subagent you spawn (the model-routing table keys off it). If `--complexity=<level>` or `--force-complex` was passed, use that directly.
+2. **Build the roadmap.** Decompose the request into ordered phases. Each phase is one deliverable unit. Stage the phases array in a JSON file, then run `luca roadmap create --file`:
+   ```
+   # /tmp/luca-roadmap.json:
+   # [
+   #   { "name": "<kebab-or-prose name>", "deps": [], "complexity": "<level>" },
+   #   ...
+   # ]
+   luca roadmap create --file /tmp/luca-roadmap.json
+   ```
+   For a single-deliverable request, that is a one-phase roadmap. `luca roadmap create` is only legal in `idle`/`triage` — it resets `currentPhase` to 0.
+3. **Advance** `idle → triage → research` via two `luca state advance --to-step <step>` calls.
+
+### Pipeline loop
+
+Repeat until `pipelineStep` is `complete`:
+
+1. Run `luca state read` to get the current `pipelineStep`.
+2. Run the step using the table below.
+3. Advance to the next step with `luca state advance --to-step <step>`. Transitions are validated against the pipeline-transitions table — illegal jumps are rejected.
+
+| Step          | How to run it                                                              |
+|---------------|----------------------------------------------------------------------------|
+| `research`    | Spawn `luca-researcher` (Agent tool). Persist its output by writing `research.md` with the `Write` tool to the canonical phase path (get the dir from `luca phase current`). |
+| `discuss`     | Invoke `Skill(skill: "phase-discuss")`.                                    |
+| `architect`   | Lightweight synthesis: read research + context, confirm the plan-ready brief. Advance to `plan`. |
+| `plan`        | Invoke `Skill(skill: "phase-plan")`.                                       |
+| `plan-review` | Spawn `luca-plan-reviewer` (Agent tool). On `NEEDS_REVISION`, loop back to `plan`. |
+| `execute`     | Invoke `Skill(skill: "phase-execute")`.                                    |
+| `checks`      | Run `luca checks run --file <commands.json>` with the project's typecheck (and tests, if present). On failure, loop back to `execute`. |
+| `verify`      | Spawn `luca-verifier` (Agent tool). On `recommendation: fix`, loop back to `checks`; on `escalate`, stop and surface to the user. |
+| `review`      | Spawn `luca-reviewer` (Agent tool) — one per perspective, in parallel.     |
+| `learn`       | Spawn `luca-learner` (Agent tool). Then: more phases remain → advance to `plan` for the next phase; last phase → advance to `milestone`. |
+| `milestone`   | Invoke `Skill(skill: "milestone-new")` to close out, or advance to `complete` if no milestone bookkeeping is needed. |
+
+### Oversight
+
+Read `oversight` from `luca state read`:
+
+- `full-auto` — run the whole loop without pausing.
+- `checkpoint` — pause after `plan-review`, `verify`, and `learn` for user confirmation.
+- `human-in-loop` — pause after every step.
+
+### What you must NOT do
+
+- Do NOT write code directly. Phase artifact files are written with the `Write` tool to their canonical path by a subagent or `/phase-*` skill; structured `.luca/` mutations go through the `luca` CLI. The stage-gate hook blocks any other direct write.
+- Do NOT skip steps. The pipeline-transitions table is the contract; `luca state advance` enforces it. There is no bypass.
+- Do NOT re-triage a mid-flight pipeline. Resume from the current step instead.
+- Do NOT commit. Commits happen only in the finalizing flow, never inside `/lu`.
+
+### Other entry points (alternatives to /lu)
+
+- New project initialization: `Skill(skill: "project-new", args: "<project description>")`
+- New milestone: `Skill(skill: "milestone-new", args: "<milestone description>")`
+- Quick / ad-hoc task that doesn't need a roadmap: `Skill(skill: "quick", args: "<task-description>")`
+- Progress check: `Skill(skill: "progress")`
+- Session planning: `Skill(skill: "session-plan")`
+- Autonomous execution across multiple phases: `Skill(skill: "autopilot", args: "<flags>")`
+
+PR-review and debug workflows are not bundled with the v13 Luca skill set; reach for the user's own `gh-pr-address` / `bug-diagnose` skills (under `~/.claude/skills/`) when present.
+
+</workflow>

package/dist/claude/skills/lu-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: lu-review
+description: Re-enter the Luca pipeline at the review step to audit completed work.
+---
+
+# /lu-review
+
+Run the **review** step against the active phase — a structured multi-perspective audit of executed code. Use this after `/phase-execute` + verification, or to re-audit a phase before closing it.
+
+You are orchestration only: read state, run the reviewers, let them persist their audits with the `Write` tool.
+
+## Step 0 — Read state
+
+Run `luca state read`. The review step has exactly one legal entry: `verify → review`. There is no bypass — `luca state advance` rejects illegal jumps.
+
+- `pipelineStep === "verify"` → run `luca state advance --to-step review`, then proceed.
+- `pipelineStep === "review"` → already there, proceed.
+- anything else → STOP. Tell the user the pipeline must reach `verify` before review can run, and point them at `/lu` to drive it there. Do not attempt to force the transition.
+
+Run `luca phase current` to get the active slug. If no phase is active, abort.
+
+## Run the reviewers
+
+Spawn the `luca-reviewer` subagent via the `Agent` tool — once per perspective, in parallel:
+
+- `architect` — structural correctness, dependency direction, API surface
+- `dx` — readability, error messages, ergonomics
+- `security` — input validation, injection, secret handling
+- `simplification` — unnecessary complexity, dead code
+- `test-quality` — vacuous mocks, presence-only assertions, coverage-by-existence
+
+Pass each reviewer its assigned perspective and the active phase slug. Each reviewer persists its own audit by writing `audits/<reviewer>.md` with the `Write` tool to the canonical phase path (the stage-gate hook only permits that write in the `review` step).
+
+Scale the perspective set to complexity: TRIVIAL/SIMPLE may run only `architect` + `security`; MODERATE+ runs the full set.
+
+## Aggregate
+
+When all reviewers return, summarize for the user:
+
+- Total MUST-FIX / SHOULD-FIX / NOTE counts across audits
+- Whether any reviewer returned `REQUEST_CHANGES`
+
+If there are MUST-FIX findings, the phase is not ready to advance — direct the user back to `/phase-execute` to address them (the `verify → checks → execute` loop-back path). If all reviewers APPROVE, advance with `luca state advance --to-step learn`.
+
+## What you must NOT do
+
+- Do NOT force a transition into `review` from a non-`verify` state. Honor the no-bypass policy.
+- Do NOT write audit files yourself — the reviewers write `audits/<reviewer>.md` with the `Write` tool to the canonical path; the hook blocks any other write.
+- Do NOT fix the findings yourself in this skill. Review reports; execute fixes.
+
+$ARGUMENTS

package/dist/claude/skills/luca-init/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: luca-init
+description: |-
+  Repo-probing wizard that seeds project preferences into .luca/config.json. Detects branching conventions, commit format, PR title format, release tooling, and issue tracker from the local repo, confirms with the user, then writes the preferences section via the `luca preferences write` CLI.
+
+  Use when the user says "init luca", "set up preferences", "luca-init", "configure conventions", or invokes /luca-init.
+---
+
+# luca-init Skill
+
+Seed repo-level project conventions so the Luca pipeline branches, commits, and ships PRs the way this team already does.
+
+This skill manages the `preferences` section of `.luca/config.json`. It does not wire hooks or write the project skeleton — that is the `luca init` CLI's job, run earlier.
+
+## When to run
+
+- The user explicitly invokes `/luca-init` or asks to set up / reset preferences.
+- After `luca init` (CLI) succeeds and the user wants to capture conventions next.
+
+## Phase 1 — Probe
+
+Read existing repo signal **before** asking any questions. Explore first; ask only for what cannot be inferred.
+
+Run each heuristic, failing soft if a signal is unavailable:
+
+1. **Branching**
+   - `git branch -r --no-color | head -50` → detect prefix patterns (`feat/`, `feature/`, `fix/`, `ENG-*`, `PT-*`, etc.).
+   - `git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null` → default branch (fallback `main`).
+2. **Commits**
+   - `git log --oneline -50` → conventional-commit prefixes (`feat:`, `fix:`, `chore:`, etc.).
+   - Recurring scopes (e.g. `feat(api):`) → suggested `commits.scopes`.
+3. **PR title format**
+   - `gh pr list --state merged --limit 20 --json title -q '.[].title' 2>/dev/null` (skip on auth failure).
+   - Pattern-match against `{type}({scope}): {description}`.
+4. **Release tooling**
+   - `.changeset/config.json` exists → `release.tool = "changesets"`.
+   - `.releaserc*` / `release.config.*` → `"semantic-release"`.
+   - Otherwise `"none"`.
+5. **Tracker**
+   - Issue refs in commits (`#123`, `ENG-456`, `PROJ-789`) → infer `github` / `linear` / `jira`.
+   - `gh repo view --json owner,name 2>/dev/null` → confirms GitHub.
+
+Build a candidate preferences object from the probe results. Leave any field you cannot infer unset — `ProjectPreferencesSchema` fills it with a safe default.
+
+The candidate must respect the schema's free-form character allowlist: branch/commit/PR template strings permit letters, digits, spaces/tabs, and `{}/#,.():-` only. No quotes, backticks, or newlines. Regex fields (`branchTypes[].match`) must not contain nested quantifiers. `luca preferences write` rejects violations — surface any rejection to the user rather than working around it.
+
+## Phase 2 — Confirm
+
+Run `luca state read` and read `oversight`.
+
+### Headless path
+
+If `oversight === "full-auto"`, skip the question. Proceed directly to Phase 3 with the probed candidate. Log one line summarising the auto-seeded values.
+
+### Interactive path
+
+Otherwise, show the detected values and ask once with `AskUserQuestion`:
+
+- **Approve** — seed these preferences as-is → Phase 3.
+- **Edit a section** — ask which section (branching, commits, pr, release, tracker), collect new values, re-confirm. Up to 2 iterations; if still unresolved, treat as Abort.
+- **Abort** — write nothing, stop. The pipeline proceeds with `ProjectPreferencesSchema` defaults (a `luca preferences read` with no stored preferences returns the defaults).
+
+## Phase 3 — Seed
+
+Write the approved candidate. Stage the partial preferences object in a JSON file, then run `luca preferences write --file`:
+
+```
+# /tmp/luca-preferences.json holds the approved candidate preferences object
+luca preferences write --file /tmp/luca-preferences.json
+```
+
+This validates the merged result against `ProjectPreferencesSchema` and atomically rewrites `.luca/config.json`, preserving every other config key (`lucaVersion`, `vault`, `oversight`, …). `.luca/config.json#preferences` is the single source of truth — `luca preferences read` reads it deterministically, so no separate MuninnDB registration is needed.
+
+If `luca preferences write` exits non-zero, surface the validation message verbatim. The most common cause is an unsafe free-form value picked up from git history in a cloned repo — re-probe or ask the user for a clean value.
+
+## Phase 4 — Confirm to user
+
+Print a one-line confirmation:
+
+```
+Project preferences seeded — branching=<types>, commits=<convention>, release=<tool>, tracker=<kind>.
+Edit later with /luca-init.
+```
+
+## Failure modes
+
+| Signal | Action |
+|---|---|
+| `git` unavailable | Use schema defaults for branching/commits; warn the user. |
+| `gh` not authenticated | Skip the PR-title probe; the schema default `{type}({scope}): {description}` applies. |
+| `luca preferences write` rejects the payload | Surface the validation error verbatim; re-probe or ask for a corrected value. Nothing is written on rejection. |

package/dist/claude/skills/luca-telemetry-report/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: luca-telemetry-report
+description: |-
+  Cross-run aggregator over `.luca/telemetry/*.jsonl`. Reads per-run JSONL telemetry records (phase/wave/step/subagent/recall/review events), aggregates streaming-style, and emits a markdown report inline. Read-only over the telemetry dir; no MuninnDB writes, no state mutation.
+
+  Use when user says "telemetry report", "aggregate telemetry", "show telemetry summary", "luca-telemetry-report", or invokes `/luca-telemetry-report`.
+
+  Arguments: `--runs <N>` (default 10), `--since <ISO-date>`, `--vault <name>`.
+---
+
+# luca-telemetry-report Skill
+
+Aggregate Luca pipeline telemetry across recent runs. Emits a single markdown report covering: run inventory, step durations, subagent costs, recall hit/miss, review-iteration convergence, cross-run trends.
+
+## Scope guard — read first
+
+This skill is **read-only over the telemetry directory**. It does not mutate workflow state and does not call any MuninnDB write API — it aggregates telemetry already on disk.
+
+The following operations are FORBIDDEN inside this skill. Do not perform them under any circumstance:
+
+- Any `luca` CLI write/mutation command (`luca state advance`, `luca roadmap create`, `luca workflow reset`, `luca confidence log`, `luca todo add/update`, `luca repo cleanup-apply`, `luca preferences write`, `luca checks run`)
+- Any `Write` to a `.luca/` phase artifact file (research, context, plan, plan-review, summary, wave, verify, audit, learn)
+- `mcp__muninn__muninn_remember`, `mcp__muninn__muninn_remember_batch`
+- `mcp__muninn__muninn_forget`, `mcp__muninn__muninn_evolve`
+- `mcp__muninn__muninn_state`, `mcp__muninn__muninn_consolidate`
+
+If a record is malformed, log it in the report's "Failure Modes" section and continue.
+
+## TelemetryRecord v:1 contract (canonical)
+
+Every JSONL line conforms to the v:1 contract:
+
+```
+{ v:1, ts:ISO8601, runId, kind, phase, slug, wave, complexity, oversight, durationMs:number|null, meta:{} }
+```
+
+Known `kind` values:
+
+- `phase.start` / `phase.end` — outer-loop phase boundaries
+- `wave.start` / `wave.end` — inner-loop wave boundaries (execute step)
+- `mode.start` / `mode.end` — pipeline step transitions
+- `subagent.invoke` / `subagent.complete` — subagent dispatch boundaries
+- `recall.hit` / `recall.miss` — MuninnDB recall outcomes
+- `review.iteration` — review-step emit
+
+Treat the union as **open**: the aggregator must tolerate unknown kinds (count them under "Unknown kinds" rather than crash).
+
+## Arguments + pre-flight validation
+
+| Flag | Type | Default | Validation |
+|---|---|---|---|
+| `--runs N` | integer | 10 | `N >= 1 && N <= 1000` |
+| `--since <ISO>` | string | unset | `^\d{4}-\d{2}-\d{2}` (date-only or full ISO accepted) |
+| `--vault <name>` | string | unset | `^[a-z0-9_-]+$`, max 64 chars |
+
+If validation fails, abort with a clear error message — do not silently continue with defaults.
+
+## Step 1: Pre-flight + scope resolve
+
+1. Parse and validate the arguments above.
+2. Read `.luca/config.json` if present. If `--vault` was supplied, override the config value; otherwise use the `muninn.vault` field, fallback `"default"`.
+3. Resolve the telemetry dir as `.luca/telemetry/`. **`existsSync` guard**: if the dir is absent (no runs yet), short-circuit to Step 7 and emit an empty report citing "no telemetry recorded yet".
+
+## Step 2: Enumerate JSONL files
+
+The `.luca/` contract stores telemetry as flat per-run files (`.luca/telemetry/<runId>.jsonl`, no subdirectories). Enumerate them with:
+
+```bash
+find .luca/telemetry -maxdepth 1 -name '*.jsonl' -print 2>/dev/null
+```
+
+Use `find`, NOT a shell glob — it handles an empty dir gracefully. Each file is one run.
+
+Sort by file mtime descending. Take the first `--runs N` files. If `--since <ISO>` is supplied, filter further by reading the first non-empty JSONL line and dropping files whose first `ts` is older than the threshold.
+
+## Step 3: Streaming aggregation pass
+
+For each selected file, stream lines (small files, ≤ a few MB each — a full read is fine). For each line:
+
+1. `JSON.parse` defensively. On a parse error: increment `failures.parse++`, continue.
+2. Validate the line has `v:1` and a `kind` string. On a miss: `failures.schema++`, continue.
+3. Dispatch to the per-kind accumulator:
+   - `phase.*` / `wave.*`: sum `durationMs` into `byPhase[phase]` / `byWave[wave]` buckets
+   - `mode.*`: sum into `byStep[from|to]`
+   - `subagent.*`: tally `byRole[role]` with input/output token sums; pair `invoke`/`complete` by `meta.correlationId` for orchestrator-side duration (preferred over a null harness `durationMs`)
+   - `recall.*`: tally hit/miss/verifiedCount per `meta.callerMode`
+   - `review.iteration`: collect the verdict/mustFixCount/perspectives series
+4. If `durationMs === null` for a `*.end` record, attempt a **ts-gap fallback** — find the matching `*.start` event with the same phase/slug/wave/runId, compute `Date.parse(end.ts) - Date.parse(start.ts)`. Only apply when both `Date.parse` calls return finite non-negative deltas. If the fallback fails, leave `null` and tally under `failures.unknownDuration`.
+
+Memory note: aggregators are **per-run scoped** — release per-run accumulators between files. Cross-run totals are written to a separate top-level accumulator.
+
+## Step 4: Build the markdown report
+
+Render 6 sections:
+
+### Run Inventory
+Table: runId | start ts | end ts | complexity | oversight | total durationMs | phases | waves
+
+### Step Durations
+Per-step totals across the pipeline (`triage` / `research` / `discuss` / `architect` / `plan` / `plan-review` / `execute` / `checks` / `verify` / `review` / `learn` / `milestone`). Show mean + p50 + p95 across the selected runs. Flag any step where >20% of records have `durationMs:null`.
+
+### Subagent Costs
+Per-role breakdown: invocations, input/output token sums, mean tokens/call. List the top 5 most expensive single calls. Flag rows where `success:false` or `outcome` is in `{crashed, killed, timeout, completed_no_usage, completed_partial_parse}` (any non-clean terminal state — only `completed` is fully successful). When grouping, treat `crashed`/`killed`/`timeout` as hard failures and `completed_no_usage`/`completed_partial_parse` as soft failures (the subagent finished but usage telemetry is missing or malformed).
+
+### Recall Stats
+Per-mode hit-rate (hit / (hit+miss)). Verified-tier hit-rate (sum(verifiedCount) / sum(resultCount)). Flag modes with a hit-rate < 0.4.
+
+### Review Convergence
+Per-run review-iteration count, mustFixCount trajectory, time-to-APPROVED (sum of `review.iteration` durationMs). Flag runs that hit `maxReviewIterations`.
+
+### Cross-Run Trends
+For each numeric metric above, compute the trend over the selected runs (oldest first, newest last). Use delta arrows: up, down, flat.
+
+End with a "Failure Modes" subsection enumerating parse/schema/unknownDuration counts and listing any unknown `kind` values seen.
+
+## Step 5: Emit the report
+
+Emit the markdown report **inline** in your response to the user. Do NOT write a file — the `.luca/` contract permits only `<runId>.jsonl` files under `telemetry/`, so a report `.md` there would violate the contract. The skill is read-only; the report is its output, not an artifact.
+
+## Step 6: Summary to caller
+
+After the report, print:
+
+- Counts: runs aggregated, total records parsed, failures (parse/schema/unknownDuration)
+- A one-line headline, e.g. `"10 runs, 7 phases avg, p95 step.execute=18m"`
+
+## Step 7: Done
+
+The skill exits. No further actions. The user invokes it again with different `--runs` / `--since` / `--vault` to explore.
+
+## Failure Modes
+
+| Failure | Cause | Skill behavior |
+|---|---|---|
+| `.luca/telemetry/` absent | No pipeline runs yet | Short-circuit to Step 7 with an empty report |
+| JSONL parse error on a line | Corrupted record (mid-write crash) | Increment `failures.parse`, continue |
+| Schema mismatch (`v` field missing) | Pre-v:1 record (none expected; v:1 is current) | Increment `failures.schema`, continue |
+| `durationMs:null` on a `*.end` record | Aborted run or NaN guard fired | Attempt the ts-gap fallback (Step 3); else tally and continue |
+| `--vault` unresolvable | Vault not in `.luca/config.json` | Continue with the supplied vault name; the report uses it as-is |
+| Unknown `kind` value | Future telemetry kind added post-skill | Tally under "Unknown kinds" in the Failure Modes section; do not crash |
+
+## Notes
+
+- The skill does **not** write any state file. Re-runs are idempotent over the same input set (deterministic).
+- The skill is external to the pipeline — it records nothing.