arcane-cli 0.34.2 → 0.35.1

package/README.md

@@ -116,7 +116,7 @@ Arcane isn't a prompt snippet — it's a full framework. Everything installs int
 | 📜 **Spells** | **<!--count:spells-->41<!--/count:spells-->** prompt-driven workflows spanning the entire lifecycle — planning, architecture, implementation, testing, review, shipping, session management, and ops. |
 | ⚖️ **Governance** | **<!--count:governance-->25<!--/count:governance-->** battle-tested standards as drop-in templates: git conventions, testing standards, CI/CD, threat model, ADR format, naming, security hardening, and more. |
 | 🤖 **Agents** | **<!--count:agents-->12<!--/count:agents-->** ready-made agent personas with roles, clusters, and a gamified autonomy model — assign work and power levels per repo. |
-| 🛠️ **CLI** | `spell init / add / update / status / uninstall` — install by profile or à la carte, and keep everything in sync as new versions ship. |
+| 🛠️ **CLI** | `spell init / add / update / status / uninstall` — install by profile or à la carte, and keep everything in sync as new versions ship. `spell report` turns a program's `PLAN.md` into a Show Report — a generated completion page — offline. |
 
 <!-- arcane:start -->
 <details>
@@ -195,6 +195,9 @@ spell agents init
 # Keep your installed governance current
 spell status     # what's installed + available updates
 spell update     # pull the latest
+
+# When a program in docs/plans/<slug>/ has shipped, generate its Show Report -- offline
+spell report     # writes docs/plans/<slug>/show-report.{json,html}
 ```
 
 > **`spell` or `arcane`?** Both commands invoke the same CLI. `spell` ties to the Spell Loop; `arcane` is there for when you reach for the brand name. Use whichever you like.

package/dist/assets/.github/prompts/spell-close-session.prompt.md

@@ -71,6 +71,8 @@ Workflow:
 
 4c. **Follow-up promotion sweep (LH-09; only when this repo has its own `scripts/check-followups.ts` — Arcane's own repo, or one that adopted the same convention; skip gracefully otherwise).** Run `npm run check:followups` (or the closest journal-scoped equivalent) and check whether this session's own journal entry or closure notes contain a deferral phrase ("filed as a separate", "follow-up", "out of scope", "not fixed here", "left open", "deferred", "revisit", "future work") with no tracker token nearby (`TODO`, `IDEAS`, `Q-NNN`, `ARC-NNN`, `EF-NN`, `RCA-NNN`, a PR URL) and no explicit `(untracked: <reason>)` opt-out. Promote each real hit to `TODO.md`/`IDEAS.md` before writing the handoff, or add the opt-out inline. Report-only tool — a hit is a prompt to check, not proof of an untracked gap; skip anything that's already tracked elsewhere in the same document.
 
+4d. **Record the epic's reader-facing line (only when this session shipped an epic of a tracked program — one with a `docs/plans/<slug>/PLAN.md`; skip entirely otherwise).** Copy the `## For the record` sentence from the epic's own PR description verbatim into that epic's `PLAN.md` entry as its `**Report:**` line, in the format `**Report:** <sentence> · category: <spell|feature|governance|decision|fix|process|docs|platform> · glyph: <emoji>`, alongside the PR number the epic ticked with. Authored at PR time (see `spell-create-pull-request` Step 4) and copied here — never re-invented at close, and never substituted with the commit subject, which describes the change to an engineer rather than to the program's reader. **If the PR carried no such section**, leave the line absent rather than writing one from memory: the generator renders a missing description visibly as `unwritten`, and a visible gap someone can fill later is worth more than a plausible sentence nobody verified. Where a completion report is generated (`npm run check:report` / `spell report`), regenerate it after this edit so the committed artifact matches its sources.
+
 5. **Update [ai-context/system-prompt-context.md](../../ai-context/system-prompt-context.md).**
    - If priorities, environment state, or agent rules changed during the session, update the file to reflect current reality.
    - If no changes are needed, skip this step.

package/dist/assets/.github/prompts/spell-commit-work.prompt.md

@@ -205,6 +205,12 @@ Workflow:
    - Structured `###` sections for each logical change area.
    - A `### Testing` checklist (`- [x]` / `- [ ]`).
    - Tables/code blocks where they improve clarity.
+   - `## For the record` — **only when this PR is one epic of a tracked program** (one with a
+     `docs/plans/<slug>/PLAN.md`); omit the heading entirely otherwise. One plain sentence a
+     non-engineer reading the finished program would understand, plus `· category: <…> · glyph: <…>`.
+     It is copied verbatim into the epic's `PLAN.md` entry as its `**Report:**` line when the epic
+     is recorded. See `spell-create-pull-request`'s Step 4 for the full convention — defined there,
+     referenced here.
 
    g. Capture PR ID/URL from command output.
    - Always render PRs as clickable markdown links with the full URL.

package/dist/assets/.github/prompts/spell-create-pull-request.prompt.md

@@ -125,6 +125,12 @@ Standard template:
 ## Testing
 
 - <coverage / test status if known, else "See CI pipeline results.">
+
+## For the record
+
+<One plain sentence a non-engineer reviewing the finished program would read — what changed for
+them, not how it was built. Omit this section entirely when the PR is not one epic of a tracked
+program.> · category: <spell|feature|governance|decision|fix|process|docs|platform> · glyph: <emoji>
 ```
 
 `--docs-only` template (skip Testing):
@@ -138,8 +144,22 @@ Standard template:
 
 ## Notes
 Documentation-only PR. No functional code changed.
+
+## For the record
+
+<Same as above — include only when this PR is one epic of a tracked program.> · category: docs · glyph: <emoji>
 ```
 
+**About `## For the record`** — include it **only when this PR is one epic of a tracked program**
+(one with a `docs/plans/<slug>/PLAN.md`); omit the heading entirely otherwise, since an empty
+section is worse than none. Write the sentence that program's completion report will show for this
+epic, in the reader's language rather than the implementation's — what changed for someone reading
+the finished program, not how it was built. Authoring it here, while the work is fresh, is the
+point: it is copied verbatim into the epic's `PLAN.md` entry as its `**Report:**` line when the
+epic is recorded (`spell-close-session` step 4d). An epic that never gets one renders visibly as
+**unwritten** in the report — never as a pasted commit subject — so a missing line stays a visible
+gap rather than a silently fabricated one.
+
 ## Step 5 — Create the PR
 
 - **GitHub:**

package/dist/assets/report/show-report.template.html

@@ -0,0 +1,382 @@
+<!doctype html>
+<!--
+  show-report template v0 (interim) -- SR-02.
+  The hand-written completion-ledger CSS/markup from this repository's own
+  two prior programs, converted to the Mustache grammar so the data contract
+  and the --check/--fix automation are real today. The v0 look is a
+  placeholder: the shipped design comes from arcane-ui's static-export
+  build (SR-05b) and drops into this same file slot in SR-06, at which point
+  the header below records the arcane-ui version and license notice it was
+  compiled from. Nothing here is arcane-ui source; this CSS was authored in
+  this MIT repository.
+  Rendered by: src/modules/show-report/render.ts (mustache). Zero runtime JS.
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{masthead.title}}</title>
+<style>
+  :root {
+    --bg: #eef0f4;
+    --surface: #ffffff;
+    --ink: #1a1d2b;
+    --ink-soft: #565b72;
+    --ink-faint: #8a8fa3;
+    --accent: #b8802e;
+    --accent-2: #3e7a72;
+    --line: #dadde3;
+    --row-alt: #f6f7f9;
+    --shadow: rgba(26, 29, 43, 0.06);
+    --needs: #a6503a;
+    --needs-bg: #f7e6e1;
+
+    --cat-spell: #b8802e;      --cat-spell-bg: #f6ead6;
+    --cat-feature: #3e7a72;    --cat-feature-bg: #dcede9;
+    --cat-governance: #7a5c8a; --cat-governance-bg: #ece2f0;
+    --cat-decision: #4a5d8a;   --cat-decision-bg: #e0e4f0;
+    --cat-fix: #a6503a;        --cat-fix-bg: #f3ded8;
+    --cat-process: #6b7a3f;    --cat-process-bg: #e6ead9;
+    --cat-docs: #6b7290;       --cat-docs-bg: #e6e7ee;
+    --cat-platform: #39525a;   --cat-platform-bg: #dde4e5;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --bg: #12141c;
+      --surface: #181b26;
+      --ink: #ede9e0;
+      --ink-soft: #9da3b8;
+      --ink-faint: #6c728a;
+      --accent: #d9a44e;
+      --accent-2: #6fafa5;
+      --line: #2a2e3d;
+      --row-alt: #1d202c;
+      --shadow: rgba(0, 0, 0, 0.35);
+      --needs: #e08a71;
+      --needs-bg: #3a2620;
+
+      --cat-spell: #e0b064;      --cat-spell-bg: #3a2e1a;
+      --cat-feature: #7fc2b8;    --cat-feature-bg: #17322e;
+      --cat-governance: #c19bd4; --cat-governance-bg: #2f2438;
+      --cat-decision: #8fa3d6;   --cat-decision-bg: #202942;
+      --cat-fix: #e08a71;        --cat-fix-bg: #3a2620;
+      --cat-process: #a3b876;    --cat-process-bg: #2a3020;
+      --cat-docs: #adb2c9;       --cat-docs-bg: #262a38;
+      --cat-platform: #7fa3ac;   --cat-platform-bg: #1c2c2f;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --bg: #12141c;
+    --surface: #181b26;
+    --ink: #ede9e0;
+    --ink-soft: #9da3b8;
+    --ink-faint: #6c728a;
+    --accent: #d9a44e;
+    --accent-2: #6fafa5;
+    --line: #2a2e3d;
+    --row-alt: #1d202c;
+    --shadow: rgba(0, 0, 0, 0.35);
+    --needs: #e08a71;
+    --needs-bg: #3a2620;
+
+    --cat-spell: #e0b064;      --cat-spell-bg: #3a2e1a;
+    --cat-feature: #7fc2b8;    --cat-feature-bg: #17322e;
+    --cat-governance: #c19bd4; --cat-governance-bg: #2f2438;
+    --cat-decision: #8fa3d6;   --cat-decision-bg: #202942;
+    --cat-fix: #e08a71;        --cat-fix-bg: #3a2620;
+    --cat-process: #a3b876;    --cat-process-bg: #2a3020;
+    --cat-docs: #adb2c9;       --cat-docs-bg: #262a38;
+    --cat-platform: #7fa3ac;   --cat-platform-bg: #1c2c2f;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    margin: 0;
+    background: var(--bg);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", -apple-system, "Segoe UI", sans-serif;
+    line-height: 1.5;
+  }
+
+  a { color: var(--accent-2); }
+  a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 3px; }
+  code { font-family: "IBM Plex Mono", monospace; font-size: 0.92em; }
+
+  .page { max-width: 920px; margin: 0 auto; padding: 3rem 1.5rem 5rem; }
+
+  header.masthead { margin-bottom: 2.25rem; }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin: 0 0 0.6rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 600;
+    font-size: clamp(2rem, 5vw, 2.85rem);
+    letter-spacing: -0.01em;
+    margin: 0 0 0.5rem;
+    text-wrap: balance;
+    color: var(--ink);
+  }
+
+  .dek { font-size: 1.02rem; color: var(--ink-soft); max-width: 62ch; margin: 0 0 1.5rem; }
+
+  dl.stat-rail {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem 1.75rem;
+    margin: 0;
+    padding: 1rem 1.25rem;
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    box-shadow: 0 1px 2px var(--shadow);
+  }
+
+  .stat { display: flex; flex-direction: column; gap: 0.15rem; margin: 0; }
+
+  .stat dd {
+    margin: 0;
+    font-family: "IBM Plex Mono", monospace;
+    font-variant-numeric: tabular-nums;
+    font-size: 1.3rem;
+    font-weight: 600;
+    color: var(--ink);
+  }
+
+  .stat dt { font-size: 0.72rem; letter-spacing: 0.06em; text-transform: uppercase; color: var(--ink-faint); }
+
+  .needs-you {
+    margin-top: 1.25rem;
+    padding: 0.9rem 1.1rem;
+    border-radius: 10px;
+    border: 1px solid var(--needs);
+    background: var(--needs-bg);
+  }
+  .needs-you h2 { margin: 0 0 0.4rem; font-size: 0.95rem; color: var(--needs); font-family: "IBM Plex Sans", sans-serif; }
+  .needs-you ul { margin: 0; padding-left: 1.1rem; font-size: 0.88rem; }
+  .needs-you li { margin: 0.2rem 0; }
+  .needs-you.none { border-color: var(--line); background: var(--surface); color: var(--ink-soft); }
+  .needs-you.none h2 { color: var(--accent-2); }
+
+  .outcome { margin: 1rem 0 0; font-size: 0.92rem; color: var(--ink-soft); }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem 1rem;
+    margin: 1.75rem 0 0.25rem;
+    padding: 1.5rem 0 0;
+    border-top: 1px solid var(--line);
+    list-style: none;
+  }
+  .legend-item { display: inline-flex; align-items: center; gap: 0.4rem; font-size: 0.76rem; color: var(--ink-soft); }
+  .swatch { width: 0.6rem; height: 0.6rem; border-radius: 50%; flex: none; }
+
+  section.phase { margin-top: 2.5rem; }
+
+  .phase-label { display: flex; align-items: baseline; gap: 0.75rem; margin-bottom: 0.9rem; }
+  .phase-label h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 600;
+    font-size: 1.15rem;
+    color: var(--ink);
+    margin: 0;
+    white-space: nowrap;
+  }
+  .phase-label .rule { flex: 1; height: 1px; background: var(--line); }
+  .phase-note { font-size: 0.82rem; color: var(--ink-faint); margin: -0.4rem 0 0.9rem; }
+
+  ol.ledger {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    overflow: hidden;
+    box-shadow: 0 1px 2px var(--shadow);
+  }
+
+  .row {
+    display: grid;
+    grid-template-columns: minmax(180px, 26%) 1fr auto;
+    gap: 1rem;
+    padding: 0.85rem 1.1rem;
+    border-top: 1px solid var(--line);
+    align-items: center;
+  }
+  .row:first-child { border-top: none; }
+  .row:nth-child(even) { background: var(--row-alt); }
+
+  .item-title { display: flex; align-items: flex-start; gap: 0.55rem; font-weight: 600; font-size: 0.94rem; color: var(--ink); }
+  .item-title .emoji { font-size: 1.05rem; line-height: 1.3; flex: none; }
+  .item-title a { color: inherit; text-decoration: none; }
+  .item-title a:hover { text-decoration: underline; }
+  .item-id { font-family: "IBM Plex Mono", monospace; font-size: 0.7rem; color: var(--ink-faint); margin-left: 0.4rem; font-weight: 500; }
+
+  .item-desc { font-size: 0.87rem; color: var(--ink-soft); max-width: 58ch; }
+  .item-desc.unwritten { color: var(--ink-faint); font-style: italic; }
+
+  .pill {
+    justify-self: end;
+    font-size: 0.7rem;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 999px;
+    white-space: nowrap;
+  }
+  .pill.spell      { color: var(--cat-spell);      background: var(--cat-spell-bg); }
+  .pill.feature    { color: var(--cat-feature);    background: var(--cat-feature-bg); }
+  .pill.governance { color: var(--cat-governance); background: var(--cat-governance-bg); }
+  .pill.decision   { color: var(--cat-decision);   background: var(--cat-decision-bg); }
+  .pill.fix        { color: var(--cat-fix);        background: var(--cat-fix-bg); }
+  .pill.process    { color: var(--cat-process);    background: var(--cat-process-bg); }
+  .pill.docs       { color: var(--cat-docs);       background: var(--cat-docs-bg); }
+  .pill.platform   { color: var(--cat-platform);   background: var(--cat-platform-bg); }
+
+  .parked-list, .cast-list { margin: 0; padding-left: 1.1rem; font-size: 0.87rem; color: var(--ink-soft); }
+  .parked-list li, .cast-list li { margin: 0.3rem 0; }
+  .parked-list strong { color: var(--ink); }
+
+  footer.colophon {
+    margin-top: 3rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--line);
+    font-size: 0.8rem;
+    color: var(--ink-faint);
+  }
+
+  @media (max-width: 640px) {
+    .row { grid-template-columns: 1fr; gap: 0.4rem; }
+    .pill { justify-self: start; }
+  }
+
+  @media print {
+    body { background: #fff; color: #000; }
+    .page { padding: 0; max-width: none; }
+    ol.ledger, dl.stat-rail, .needs-you { box-shadow: none; }
+    a { color: inherit; }
+  }
+</style>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;9..144,600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@500;600&display=swap">
+</head>
+<body>
+<div class="page">
+<main>
+
+  <header class="masthead">
+    <p class="eyebrow">{{masthead.eyebrow}}</p>
+    <h1>{{masthead.title}}</h1>
+    <p class="dek">{{masthead.dek}}</p>
+
+    <dl class="stat-rail">
+      {{#stats}}
+      <div class="stat"><dd>{{value}}</dd><dt>{{label}}</dt></div>
+      {{/stats}}
+    </dl>
+
+    {{#needsYouCount}}
+    <section class="needs-you" aria-labelledby="needs-you-heading">
+      <h2 id="needs-you-heading">Needs you: {{needsYouCount}}</h2>
+      <ul>
+        {{#needsYou}}
+        <li><strong>{{id}}</strong> — {{title}}{{#href}} · <a href="{{href}}">open</a>{{/href}}</li>
+        {{/needsYou}}
+      </ul>
+    </section>
+    {{/needsYouCount}}
+    {{^needsYouCount}}
+    <section class="needs-you none" aria-labelledby="needs-you-heading">
+      <h2 id="needs-you-heading">Nothing needs you</h2>
+    </section>
+    {{/needsYouCount}}
+
+    {{#hasOutcome}}<p class="outcome">{{outcome}}</p>{{/hasOutcome}}
+
+    <ul class="legend" aria-label="Category legend">
+      {{#legend}}
+      <li class="legend-item"><span class="swatch" style="background:var(--cat-{{key}})" aria-hidden="true"></span>{{label}}</li>
+      {{/legend}}
+    </ul>
+  </header>
+
+  {{#sections}}
+  <section class="phase" aria-labelledby="{{id}}-heading">
+    <div class="phase-label"><h2 id="{{id}}-heading">{{title}}</h2><span class="rule" aria-hidden="true"></span></div>
+    {{#hasNote}}<p class="phase-note">{{note}}</p>{{/hasNote}}
+    <ol class="ledger">
+      {{#rows}}
+      <li class="row">
+        <div class="item-title">{{#hasGlyph}}<span class="emoji" aria-hidden="true">{{glyph}}</span>{{/hasGlyph}}<span>{{#hasHref}}<a href="{{href}}">{{title}}</a>{{/hasHref}}{{^hasHref}}{{title}}{{/hasHref}}<span class="item-id">{{id}}</span></span></div>
+        {{#isUnwritten}}<div class="item-desc unwritten">unwritten</div>{{/isUnwritten}}
+        {{^isUnwritten}}<div class="item-desc">{{{descriptionHtml}}}</div>{{/isUnwritten}}
+        <span class="pill {{category}}">{{categoryLabel}}</span>
+      </li>
+      {{/rows}}
+    </ol>
+  </section>
+  {{/sections}}
+
+  {{#hasCorrections}}
+  {{#corrections}}
+  <section class="phase" aria-labelledby="corrections-heading">
+    <div class="phase-label"><h2 id="corrections-heading">Calibration</h2><span class="rule" aria-hidden="true"></span></div>
+    <p class="phase-note">{{checked}} claims checked · {{corrected}} corrected · {{unverifiable}} unverifiable. {{scopeNote}}</p>
+    <ol class="ledger">
+      {{#highlights}}
+      <li class="row">
+        <div class="item-title"><span>{{title}}</span></div>
+        {{#isUnwritten}}<div class="item-desc unwritten">unwritten</div>{{/isUnwritten}}
+        {{^isUnwritten}}<div class="item-desc">{{{descriptionHtml}}}</div>{{/isUnwritten}}
+        <span class="pill {{category}}">{{categoryLabel}}</span>
+      </li>
+      {{/highlights}}
+    </ol>
+  </section>
+  {{/corrections}}
+  {{/hasCorrections}}
+
+  {{#hasParked}}
+  <section class="phase" aria-labelledby="parked-heading">
+    <div class="phase-label"><h2 id="parked-heading">Parked — needs operator</h2><span class="rule" aria-hidden="true"></span></div>
+    <ul class="parked-list">
+      {{#parked}}
+      <li><strong>{{title}}</strong> — {{reason}}</li>
+      {{/parked}}
+    </ul>
+  </section>
+  {{/hasParked}}
+
+  {{#hasCast}}
+  <section class="phase" aria-labelledby="cast-heading">
+    <div class="phase-label"><h2 id="cast-heading">Cast</h2><span class="rule" aria-hidden="true"></span></div>
+    <p class="phase-note">Self-reported from commit trailers in this program's version window.</p>
+    <ul class="cast-list">
+      {{#cast}}
+      <li>{{name}} — {{commits}} commits</li>
+      {{/cast}}
+    </ul>
+  </section>
+  {{/hasCast}}
+
+</main>
+
+  <footer class="colophon">
+    Compiled {{compiledAtDate}} from <code>{{sourcesJoined}}</code>. Program <code>{{program.slug}}</code>, status <code>{{program.status}}</code>{{#hasVersionSpan}}, <code>{{program.versionSpan.from}}</code> → <code>{{program.versionSpan.to}}</code>{{/hasVersionSpan}}. Template <code>{{colophon.templateVersion}}</code>. Every stat above is derived, never hand-typed.
+  </footer>
+
+</div>
+</body>
+</html>