arcane-cli 0.35.0 → 0.36.0

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>`, 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: <…>`.
+     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>
 ```
 
 `--docs-only` template (skip Testing):
@@ -138,8 +144,29 @@ 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
 ```
 
+**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.
+
+The line ends at `category:`. It carried a trailing `· glyph: <emoji>` until ARC-043, which
+dropped it: `category` is a closed set of eight and already selects the mark the report draws, so a
+per-epic emoji was a second, redundant decision on every line — and an emoji renders differently on
+every platform, prints badly, and cannot take the report's own colour. Do **not** author one.
+Lines written before ARC-043 still carry theirs; the parser reads past it and the report ignores it,
+so they need no edit.
+
 ## Step 5 — Create the PR
 
 - **GitHub:**

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

@@ -180,7 +180,6 @@
     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; }
 
@@ -219,7 +218,18 @@
   .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; }
+  /* One icon per category, drawn from the sprite below and coloured by the
+     same token as the row's pill. Decorative: the pill carries the category in
+     text, so the icon is aria-hidden and never the sole carrier of meaning. */
+  .cat-icon { width: 1rem; height: 1rem; flex: none; margin-top: 0.12rem; }
+  .cat-icon.spell      { color: var(--cat-spell); }
+  .cat-icon.feature    { color: var(--cat-feature); }
+  .cat-icon.governance { color: var(--cat-governance); }
+  .cat-icon.decision   { color: var(--cat-decision); }
+  .cat-icon.fix        { color: var(--cat-fix); }
+  .cat-icon.process    { color: var(--cat-process); }
+  .cat-icon.docs       { color: var(--cat-docs); }
+  .cat-icon.platform   { color: var(--cat-platform); }
   .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; }
@@ -273,6 +283,22 @@
 <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>
+<!-- Category icon sprite. Eight symbols, one per ReportCategory, referenced by
+     `<use href="#cat-<category>">` from each row and from the legend. Inline
+     rather than an emoji per row: an emoji renders differently on every
+     platform, often falls back to a box or a monochrome outline in print, and
+     cannot take the report's own category colour. All eight together are about
+     2 KB, and the file stays self-contained with no network fetch. -->
+<svg width="0" height="0" style="position:absolute" aria-hidden="true" focusable="false"><defs>
+  <symbol id="cat-spell" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 1.75v3.5M8 10.75v3.5M1.75 8h3.5M10.75 8h3.5M3.6 3.6l2.4 2.4M10 10l2.4 2.4M12.4 3.6 10 6M6 10l-2.4 2.4"/></symbol>
+  <symbol id="cat-feature" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2.25" y="2.25" width="11.5" height="11.5" rx="1"/><path d="M8 5.25v5.5M5.25 8h5.5"/></symbol>
+  <symbol id="cat-governance" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 1.75 13.25 3.75v4.2c0 3.05-2.2 5.3-5.25 6.3-3.05-1-5.25-3.25-5.25-6.3v-4.2z"/></symbol>
+  <symbol id="cat-decision" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 1.75 14.25 8 8 14.25 1.75 8z"/></symbol>
+  <symbol id="cat-fix" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 1.75 13.4 4.9v6.2L8 14.25 2.6 11.1V4.9z"/><circle cx="8" cy="8" r="2.25"/></symbol>
+  <symbol id="cat-process" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M13 8a5 5 0 0 1-8.65 3.45M3 8a5 5 0 0 1 8.65-3.45"/><path d="M11.65 2.15v2.4h-2.4M4.35 13.85v-2.4h2.4"/></symbol>
+  <symbol id="cat-docs" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.75 1.75h5.75l2.75 2.75v9.75h-8.5z"/><path d="M9.5 1.75v3h3M6 8h4M6 10.75h4"/></symbol>
+  <symbol id="cat-platform" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2.25" y="2.25" width="11.5" height="3.75" rx=".75"/><rect x="2.25" y="8.25" width="11.5" height="3.75" rx=".75"/><path d="M4.75 4.1h.01M4.75 10.1h.01M8 12v2.25"/></symbol>
+</defs></svg>
 <div class="page">
 <main>
 
@@ -307,7 +333,7 @@
 
     <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>
+      <li class="legend-item"><svg class="cat-icon {{key}}" aria-hidden="true" focusable="false"><use href="#cat-{{key}}"></use></svg>{{label}}</li>
       {{/legend}}
     </ul>
   </header>
@@ -319,7 +345,7 @@
     <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>
+        <div class="item-title"><svg class="cat-icon {{category}}" aria-hidden="true" focusable="false"><use href="#cat-{{category}}"></use></svg><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>
@@ -337,7 +363,7 @@
     <ol class="ledger">
       {{#highlights}}
       <li class="row">
-        <div class="item-title"><span>{{title}}</span></div>
+        <div class="item-title"><svg class="cat-icon {{category}}" aria-hidden="true" focusable="false"><use href="#cat-{{category}}"></use></svg><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>

package/dist/index.js

@@ -5123,7 +5123,7 @@ function parseFrontmatter(content) {
 var EPIC_START = /^- \[([ x])\] \*\*([A-Z]+-\d+) — /gm;
 var EPIC_TITLE = /^- \[[ x]\] \*\*[A-Z]+-\d+ — ([\s\S]+?)\.\*\*/;
 var HEADING_LINE = /^(#{2,3}) (.+)$/gm;
-var REPORT_LINE = /\*\*Report:\*\*\s*([\s\S]*?)\s*·\s*category:\s*(\S+)\s*·\s*glyph:\s*(\S+)/;
+var REPORT_LINE = /\*\*Report:\*\*\s*([\s\S]*?)\s*·\s*category:\s*([a-z]+)/;
 var TITLE_OVERRIDE_LINE = /^\s*title:\s*(.+)$/m;
 var PR_LINK = /\[PR #(\d+)\]\((https:\/\/github\.com\/[^)\s]+\/pull\/\d+)\)/g;
 function parseEpics(content) {
@@ -5173,7 +5173,6 @@ function parseEpics(content) {
       report: reportMatch ? {
         description: reportMatch[1].replace(/\s+/g, " ").trim(),
         category: reportMatch[2],
-        glyph: reportMatch[3],
         titleOverride: titleOverrideMatch ? titleOverrideMatch[1].trim() : void 0
       } : null,
       prLinks,
@@ -5205,11 +5204,32 @@ function parseParkedSection(content) {
       reason: stripMarkdown(m[3].trim())
     }));
   }
-  const bulletItems = [...body.matchAll(/^- \*\*(.+?)\*\*\s*(?:\([^)]*\))?\s*—\s*(.+)$/gm)];
-  return bulletItems.map((m) => ({
-    title: stripMarkdown(m[1].trim()),
-    reason: stripMarkdown(m[2].trim())
-  }));
+  return unwrapBullets(body).flatMap((bullet) => {
+    const match = /^\*\*(.+?)\*\*(.*?)\s*—\s*(.+)$/.exec(bullet);
+    if (!match) return [];
+    const tail = match[2].replace(/\([^)]*\)/g, "").replace(/\s+/g, " ").trim();
+    const title = tail ? `${match[1].trim()} ${tail}` : match[1].trim();
+    return [{ title: stripMarkdown(title), reason: stripMarkdown(match[3].trim()) }];
+  });
+}
+function unwrapBullets(body) {
+  const bullets = [];
+  let current = null;
+  const flush = () => {
+    if (current) bullets.push(current.join(" ").replace(/\s+/g, " ").trim());
+    current = null;
+  };
+  for (const line of body.split(/\r?\n/)) {
+    if (/^- /.test(line)) {
+      flush();
+      current = [line.slice(2).trim()];
+    } else if (current !== null) {
+      if (/^\s+\S/.test(line)) current.push(line.trim());
+      else flush();
+    }
+  }
+  flush();
+  return bullets;
 }
 function computeCoverageOutcome(content) {
   const body = extractSection(content, "## Coverage Map");
@@ -5377,7 +5397,6 @@ function epicToRow(epic) {
     href: epic.prLinks.length > 0 ? epic.prLinks[epic.prLinks.length - 1] : void 0,
     refs: epic.prLinks
   };
-  if (epic.report?.glyph) row.glyph = epic.report.glyph;
   return row;
 }
 function buildSections(epics) {
@@ -5424,13 +5443,20 @@ function buildNeedsYou(queueEntries) {
     return entry;
   });
 }
+function truncateAtWord(text, limit) {
+  if (text.length <= limit) return text;
+  const window = text.slice(0, limit - 1);
+  const lastSpace = window.lastIndexOf(" ");
+  const head = lastSpace > 0 ? window.slice(0, lastSpace) : window;
+  return `${head.replace(/[\s,;:.—-]+$/, "")}\u2026`;
+}
 function buildCorrections(ledgerRows, programName) {
   if (ledgerRows.length === 0) return void 0;
   const corrected = ledgerRows.filter((r) => r.result === "corrected");
   const unverifiable = ledgerRows.filter((r) => r.result === "unverifiable").length;
   const highlights = corrected.slice(0, 3).map((row, i) => ({
     id: `correction-${i + 1}`,
-    title: row.claim.length > 80 ? `${row.claim.slice(0, 77)}...` : row.claim,
+    title: truncateAtWord(row.claim, 80),
     description: row.correction,
     descriptionState: row.correction ? "authored" : "unwritten",
     category: "fix",
@@ -5556,8 +5582,7 @@ function toRowView(row) {
     categoryLabel: CATEGORY_LABELS[row.category] ?? row.category,
     descriptionHtml: row.description === null ? null : inlineMarkupToHtml(row.description),
     isUnwritten: row.descriptionState === "unwritten",
-    hasHref: typeof row.href === "string" && row.href.length > 0,
-    hasGlyph: typeof row.glyph === "string" && row.glyph.length > 0
+    hasHref: typeof row.href === "string" && row.href.length > 0
   };
 }
 function buildShowReportView(model) {
@@ -5675,8 +5700,11 @@ async function runReportGeneration(options) {
   const templateHtml = await readFile13(options.templatePath, "utf8");
   const drifted = [];
   const repaired = [];
+  const unwritten = [];
   for (const program2 of options.programs) {
     const generated = await generateReport(options.rootDir, program2, templateHtml);
+    const missing = JSON.parse(generated.json).sections.flatMap((section) => section.rows).filter((row) => row.descriptionState === "unwritten").map((row) => row.id);
+    if (missing.length > 0) unwritten.push({ slug: program2.slug, ids: missing });
     const outAbs = options.outDir ? isAbsolute(options.outDir) ? options.outDir : resolve3(options.rootDir, options.outDir) : resolve3(options.rootDir, dirname4(program2.planRelPath));
     const outRel = toPosix(relative3(options.rootDir, outAbs));
     const outputs = [
@@ -5695,7 +5723,7 @@ async function runReportGeneration(options) {
       }
     }
   }
-  return { drifted, repaired };
+  return { drifted, repaired, unwritten };
 }
 
 // src/commands/report.ts
@@ -5746,6 +5774,11 @@ async function runReport(targetDir, options = {}, assetsDir) {
     programs,
     outDir: options.out
   });
+  for (const u of result.unwritten) {
+    console.warn(
+      `\u26A0 arcane: ${u.slug} has ${u.ids.length} epic(s) with no \`**Report:**\` line in PLAN.md -- they render as "unwritten": ${u.ids.join(", ")}.`
+    );
+  }
   if (result.repaired.length === 0) {
     console.log(`Show report: ${programs.length} program(s) already up to date.`);
     return;