@azure-id/orc 2.0.2 → 2.1.0

package/templates/commands/orc-wiki.md

@@ -1,64 +1,64 @@
----
-description: Build/maintain the project knowledge base (wiki) — Opus 4.8 high, expensive, multi-session, warns before scanning
----
-
-Use the **orc-wiki** skill. Start at Phase 0: auto-detect whether this is a
-repair of an unregistered wiki, a fresh build, a resume of an in-progress scan,
-or a refresh of an existing wiki, and branch accordingly. On a fresh build, show
-the cost warning and scan NOTHING until the user explicitly confirms. Refreshes
-also sweep for coverage gaps (changed files no doc covers → propose new areas)
-and dead docs (covered files gone → archive/delete, user decides). Every run
-registers via `orc wiki sync` and ends with the integrity self-check. Follow the
-skill's SKILL.md exactly.
-
-**Crosslink is always on.** Plain `/orc-wiki` — every scan, resume, incremental,
-full regenerate, or selective refresh — publishes/updates this repo's boundary
-tags (`wiki/crosslink/`) in the SAME pass as the docs, and a refresh never
-deletes them. There is no separate "generate crosslink" step in a wiki's normal
-life; the only crosslink config is the graph (`orc crosslink`), needed only to
-resolve what this repo consumes.
-
-**`/orc-wiki crosslink`** → the CROSSLINK-ONLY branch (Phase 3c) is a LEGACY
-BACKFILL: publish tags + resolve consumption from the existing docs'
-`Contracts & shapes` rows (opening only the files they anchor), for wikis whose
-docs predate v0.24.0 and so have no `wiki/crosslink/` yet. No area is re-scanned,
-no doc rewritten. On a wiki scanned at ≥v0.24.0, missing tags are not this
-branch — `orc wiki sync --check` names the real fix. Never a refresh.
-
-**`/orc-wiki crosslink compile`** → the one-shot CROSSLINK COMPILE branch
-(v0.33.0 — references/crosslink-compile.md): resolve/consume from the graph →
-generate the federation atlas (`wiki/crosslink/atlas.md`) → write it into each
-linked repo → inject/update the CLAUDE.md pointer block locally and in each
-linked repo (in-place, user content byte-preserved). Requires a crosslink
-config with ≥1 edge; every step warn-only; never a re-scan. Peer writes are
-FILE writes only — never a commit or push.
-
-**`/orc-wiki update <doc-or-topic>`** → ONE doc, re-scanned. A filename goes
-straight into the targeted refresh. A topic ("the remittance feature") is
-resolved first with `orc wiki resolve` — free, no scan — and an AMBIGUOUS result
-is a question for you, never a guess. Branch detection and area planning are both
-skipped: the doc exists, so its coverage area is already in its own header.
-
-**`/orc-wiki add "<topic>"`** → ONE new doc, in a wiki that already exists, with
-no other area re-planned. It resolves the topic first (if something already
-covers it, that is an `update` and it says so), proposes a coverage scope from
-path names for you to correct, confirms the slug, the covers, the tier and the
-cost in ONE turn, and scans nothing until you say yes. It ends with
-`orc wiki refs`, the derived-reference sweep — adding a doc moves more derived
-surfaces than changing one does: the registration, the orientation page, the
-architecture overview, the CLAUDE.md pointer's doc count, and any crosslink tag
-left anchored to a file that is gone. Only the registration is repaired for you;
-the rest is reported with its command, because a sweep that silently regenerated
-prose would be spending money nobody asked it to spend.
-
-| Argument | Branch |
-|---|---|
-| *(none)* | Phase 0 auto-branch: repair / fresh / resume / refresh (delta default) |
-| `update <doc>` | targeted refresh of ONE doc (skips branch detection + area planning) |
-| `update "<topic>"` | resolve the topic to a doc, then refresh it |
-| `add "<topic>"` | reserve + scan + write ONE new doc, then sweep every derived reference |
-| `crosslink` | Phase 3c legacy backfill (publish tags from existing docs) |
-| `crosslink compile` | one-shot resolve + atlas + CLAUDE.md injection (local + peers) |
-
-Optional focus (`update <doc>` · `add "<topic>"` · `crosslink` ·
-`crosslink compile`): $ARGUMENTS
+---
+description: Build/maintain the project knowledge base (wiki) — Opus 5.5 low, expensive, multi-session, warns before scanning
+---
+
+Use the **orc-wiki** skill. Start at Phase 0: auto-detect whether this is a
+repair of an unregistered wiki, a fresh build, a resume of an in-progress scan,
+or a refresh of an existing wiki, and branch accordingly. On a fresh build, show
+the cost warning and scan NOTHING until the user explicitly confirms. Refreshes
+also sweep for coverage gaps (changed files no doc covers → propose new areas)
+and dead docs (covered files gone → archive/delete, user decides). Every run
+registers via `orc wiki sync` and ends with the integrity self-check. Follow the
+skill's SKILL.md exactly.
+
+**Crosslink is always on.** Plain `/orc-wiki` — every scan, resume, incremental,
+full regenerate, or selective refresh — publishes/updates this repo's boundary
+tags (`wiki/crosslink/`) in the SAME pass as the docs, and a refresh never
+deletes them. There is no separate "generate crosslink" step in a wiki's normal
+life; the only crosslink config is the graph (`orc crosslink`), needed only to
+resolve what this repo consumes.
+
+**`/orc-wiki crosslink`** → the CROSSLINK-ONLY branch (Phase 3c) is a LEGACY
+BACKFILL: publish tags + resolve consumption from the existing docs'
+`Contracts & shapes` rows (opening only the files they anchor), for wikis whose
+docs predate v0.24.0 and so have no `wiki/crosslink/` yet. No area is re-scanned,
+no doc rewritten. On a wiki scanned at ≥v0.24.0, missing tags are not this
+branch — `orc wiki sync --check` names the real fix. Never a refresh.
+
+**`/orc-wiki crosslink compile`** → the one-shot CROSSLINK COMPILE branch
+(v0.33.0 — references/crosslink-compile.md): resolve/consume from the graph →
+generate the federation atlas (`wiki/crosslink/atlas.md`) → write it into each
+linked repo → inject/update the CLAUDE.md pointer block locally and in each
+linked repo (in-place, user content byte-preserved). Requires a crosslink
+config with ≥1 edge; every step warn-only; never a re-scan. Peer writes are
+FILE writes only — never a commit or push.
+
+**`/orc-wiki update <doc-or-topic>`** → ONE doc, re-scanned. A filename goes
+straight into the targeted refresh. A topic ("the remittance feature") is
+resolved first with `orc wiki resolve` — free, no scan — and an AMBIGUOUS result
+is a question for you, never a guess. Branch detection and area planning are both
+skipped: the doc exists, so its coverage area is already in its own header.
+
+**`/orc-wiki add "<topic>"`** → ONE new doc, in a wiki that already exists, with
+no other area re-planned. It resolves the topic first (if something already
+covers it, that is an `update` and it says so), proposes a coverage scope from
+path names for you to correct, confirms the slug, the covers, the tier and the
+cost in ONE turn, and scans nothing until you say yes. It ends with
+`orc wiki refs`, the derived-reference sweep — adding a doc moves more derived
+surfaces than changing one does: the registration, the orientation page, the
+architecture overview, the CLAUDE.md pointer's doc count, and any crosslink tag
+left anchored to a file that is gone. Only the registration is repaired for you;
+the rest is reported with its command, because a sweep that silently regenerated
+prose would be spending money nobody asked it to spend.
+
+| Argument | Branch |
+|---|---|
+| *(none)* | Phase 0 auto-branch: repair / fresh / resume / refresh (delta default) |
+| `update <doc>` | targeted refresh of ONE doc (skips branch detection + area planning) |
+| `update "<topic>"` | resolve the topic to a doc, then refresh it |
+| `add "<topic>"` | reserve + scan + write ONE new doc, then sweep every derived reference |
+| `crosslink` | Phase 3c legacy backfill (publish tags from existing docs) |
+| `crosslink compile` | one-shot resolve + atlas + CLAUDE.md injection (local + peers) |
+
+Optional focus (`update <doc>` · `add "<topic>"` · `crosslink` ·
+`crosslink compile`): $ARGUMENTS

package/templates/hooks/README.md

@@ -214,18 +214,76 @@ move, and it tells you why.
 Every component can be changed: its words, its colour, its shape, how wide it
 is, and when it is allowed to disappear.
 
-**The shape decides what the other settings can do.** Only these shapes print a
-short name in front of the value: `plain`, `label-value`, `bracket`, `angle`,
-`badge`, `pill` and `stack`. A bar, an icon and a bare value have no room for
-one, so the panel switches the Name box off for them and says so. The same is
-true of the number settings: a bar has a width and a colour ramp, and no number
-format at all.
+**The shape decides what the other settings can do.** The panel switches off a
+setting that the shape does not use, and says so.
+
+**Words around any shape** (v2.0.4). Every shape draws the name you type. You
+choose where it goes: before, after, above or below the part. A bar can also have
+text before and after it (for example `[██░░]`) and its number beside it. If you
+type no name, only `plain`, `label-value`, `bracket`, `angle`, `badge`, `pill` and
+`stack` print the part's built-in name.
+
+**Captions.** A caption is a short text on a row above or below a part, at the
+column of that part. `{value}` and `{label}` in the caption are replaced. A caption
+makes the line one row taller.
+
+**Small text.** A terminal has no font size. The letter styles `small` (ꜱᴍᴀʟʟ
+ᴄᴀᴘꜱ), `super` (ˢᵘᵖᵉʳ) and `sub` (₆₁) use Unicode letters that look smaller.
+A character with no small form stays as it is.
+
+**Bars in your own colours and characters.** A bar can have its own fill colour,
+empty colour, colour range (for example `#22c55e,#eab308,#ef4444`, blended cell by
+cell on `gradient`), and its own fill and empty characters (one cell each).
+
+**Every part** can also have brackets, space on the left and right, a background,
+any `#rrggbb` colour, more than one weight, and its own colour and symbol per
+state. A line can be aligned right or centre, and its separator can have a colour.
+`text`, `divider`, `spacer`, `icon-static`, `fill` (pushes the rest to the right
+edge) and `config` take their text in the part's settings.
+
+**Claude Code removes the spaces at the start of every row.** So when a row of
+your status line starts with a space (a caption row, a line prefix, a
+right-aligned line), ORC makes that first space a braille blank (U+2800). It is one
+cell wide and Claude Code keeps it, so a caption stays above or below its own part.
+Under `ORC_STATUSLINE_ASCII=1` this is not done, because U+2800 is not ASCII.
+
+**Pets that move** (the "Pets and motion" group): a pixel cat drawn in braille
+dots, a mouse, a cat that chases the mouse, the text cat ᓚᘏᗢ, pac-man, a fish, a
+bird and a dog. Each can `run` across its track, `bounce` right and back, or stay
+`idle` and move its legs.
+
+**Motion needs a timer.** Claude Code redraws the status line when something
+happens (a message, typing), or every `refreshInterval` seconds if you set it (at
+least 1). Set it with:
+
+```
+orc statusline refresh 1
+```
+
+and remove it with `orc statusline refresh off`. With the timer the hook runs
+every second even when you do nothing, and each run starts `node`. So a pet moves
+about one step per second.
+
+**Weather** (`weather`, `weather-icon`, `weather-desc`). This is the ONLY part of
+the status line that uses the network. The hook itself never waits for it: it reads
+`.claude/orc/weather.json`, and when that is older than 30 minutes it starts
+`orc-weather-fetch.js` in the background, which asks wttr.in and writes the file.
+With an empty `location`, wttr.in finds your place from your network address. It
+runs only while a weather part is on your layout. `ORC_STATUSLINE_NO_NET=1` stops
+it. Every text it gets back is cleaned of control characters before it is saved.
+
+**The panel shows your unsaved changes.** The picture above the board is drawn
+from a temporary copy with your staged changes, so you see the result before you
+press Apply. Nothing is written until you press Apply.
+
+A layout may not carry a control character (for example ESC) in any text. It is
+printed to your terminal, so the CLI refuses it.
 
 **Three things a terminal cannot do**, said plainly so you do not look for them:
 
 | You may want | What you get |
 |---|---|
-| A bigger font | The terminal owns the font size. Use **bold**, or make a component wider — a bar at width 12 is a big object. |
+| A bigger font | The terminal owns the font size. Use **bold**, a small letter style for the words around it, or make a component wider — a bar at width 12 is a big object. |
 | A blinking part | Refused. Half of terminals turn it off, and no part of a status line needs it. |
 | Icon-font symbols | Not shipped. They need a font we cannot check for, and they draw as empty boxes without it. |
 
@@ -472,6 +530,16 @@ It never writes model text, and it blocks a stop only for the narration guard.
   authored. If the compiled file is missing, stale, or does not pass a cheap
   shape check, the hook silently renders the shipped lines instead and
   `orc doctor` names the reason.
+- **Stale means the parts changed, not the version** (v2.0.3). `orc init` and
+  `orc update` write `catalog_hash` into `hooks/orc-version.json`, and the hook
+  compares it with the `catalog_hash` in `statusline.lock.json`. An install with
+  no hash compares the version, as before. `orc update` also recompiles every
+  layout that exists and validates, so an upgrade never leaves your bar on the
+  shipped lines. A good render deletes `orc/statusline-state.json`, so
+  `orc doctor` never reports a fallback that is already gone.
+- `orc statusline show --json` carries `hook`: the hook the settings point to,
+  its version, whether it will run this layout, the last fallback, and the fix.
+  `orc ui` shows that on the status card.
 - The cache file is `.claude/orc/usage-session.json`. The hook reads it once and
   writes it once, after the text is ready. It stores raw numbers only — never a
   word like `fresh` or `STALE`, which is computed each time it is shown.

package/templates/hooks/orc-session-hook.js

@@ -113,10 +113,45 @@ function narrationGuard(data) {
   } catch (_) {
     return false;
   }
-  const lines = text.split(/\r?\n/).filter((l) => /^\[/.test(l));
+  const all = text.split(/\r?\n/).filter((l) => l.trim());
+  const lines = all.filter((l) => /^\[/.test(l));
   if (!lines.some((l) => /\]\s+hook\s+SPAWN /.test(l))) return false; // nothing was dispatched yet
-  if (lines.some((l) => !/\]\s+hook\s+/.test(l))) return false; // a packet already landed
   const statePath = path.join(CLAUDE_DIR, "orc", "narration-guard.json");
+  // v2.1.0 (E21 D7) — narration written BY HAND. A live /orc-quick appended its
+  // lines itself (no `.mmm` stamp, or no stamp at all), so `orc trace write` never
+  // saw them: no grammar check, and none of the FINISH reminders (observe, which
+  // review, config, phases) ran — the lane then claimed the findings were
+  // "logged". The CLI writes every line to the .txt AND its .jsonl twin, so more
+  // narration lines than jsonl rows, or a line without the CLI's stamp, is proof.
+  const narr = all.filter((l) => !/^\[[^\]]*\]\s+hook\s+/.test(l));
+  if (narr.length) {
+    let rows = 0;
+    try {
+      rows = fs.readFileSync(path.join(dir, best.f + ".jsonl"), "utf8").split(/\r?\n/).filter((l) => l.trim()).length;
+    } catch (_) {}
+    // NOT the `.mmm` stamp: `orc trace write` also accepts HH:MM:SS (a live run
+    // proved it, and an early guard blocked a correct run on it).
+    const hand = narr.some((l) => !/^\[\d{6} \d{2}:\d{2}:\d{2}(?:\.\d{1,3})?\] /.test(l)) || narr.length > rows;
+    if (!hand) return reviewGuard(best, text, statePath); // a CLI packet already landed
+    try {
+      const st = JSON.parse(fs.readFileSync(statePath, "utf8"));
+      if (st.run === best.f && st.kind === "hand") return false;
+    } catch (_) {}
+    try {
+      fs.mkdirSync(path.dirname(statePath), { recursive: true });
+      fs.writeFileSync(statePath, JSON.stringify({ run: best.f, kind: "hand", at: Date.now() }) + "\n");
+    } catch (_) {}
+    process.stdout.write(
+      JSON.stringify({
+        decision: "block",
+        reason:
+          `ORC: the trace ${best.f} has lines written by hand — \`orc trace write\` never saw them, so no check and no FINISH reminder ran. ` +
+          `Never append to a trace yourself. Send the FINISH packet now through \`orc trace write --packet -\` (\`run: ${best.f.replace(/\.txt$/, "")}\` if .current is gone) ` +
+          `and do what its reply says (for a review: one \`orc gotcha observe\` per finding), then finish.`,
+      })
+    );
+    return true;
+  }
   try {
     if (JSON.parse(fs.readFileSync(statePath, "utf8")).run === best.f) return false;
   } catch (_) {}
@@ -136,8 +171,48 @@ function narrationGuard(data) {
   return true;
 }
 
+// v2.1.0 (E21 D8) — a FINISHED run that reviewed and recorded nothing. A live
+// /orc ignored the FINISH observe reminder after a review with findings; Review
+// Quality then counts the review but learns no acceptance from it. ONCE per run,
+// in the main session: the trace has a reviewer RETURN and a FINISH line, the
+// review was not clean, and no observation names this run → block one stop.
+function reviewGuard(best, text, statePath) {
+  if (!/\]\s+hook\s+RETURN\s+orc-reviewer-/.test(text) || !/\]\s+\S+\s+FINISH\b/.test(text)) return false;
+  const fo = /FINDING-OUTCOME addressed=(\d+) disputed=(\d+) wontfix=(\d+) open=(\d+)/.exec(text);
+  const f = /\]\s+\S+\s+FINDING p0=(\d+) p1=(\d+) p2=(\d+) p3=(\d+)/.exec(text);
+  if ((fo && fo.slice(1, 5).every((n) => n === "0")) || (!fo && f && f.slice(1, 5).every((n) => n === "0"))) return false; // clean
+  const run = best.f.replace(/\.txt$/, "");
+  try {
+    for (const line of fs.readFileSync(path.join(CLAUDE_DIR, "orc", "observations.jsonl"), "utf8").split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const o = JSON.parse(line);
+        if (o && o.author === "orc" && o.run === run) return false;
+      } catch (_) {}
+    }
+  } catch (_) {}
+  try {
+    const st = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    if (st.run === best.f && st.kind === "review") return false;
+  } catch (_) {}
+  try {
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify({ run: best.f, kind: "review", at: Date.now() }) + "\n");
+  } catch (_) {}
+  process.stdout.write(
+    JSON.stringify({
+      decision: "block",
+      reason:
+        `ORC: the run ${run} ran a review with findings and recorded no outcome. Pipe ONE object per finding to \`orc gotcha observe - --json\` ` +
+        `(source review · author orc · run ${run} · ref "${run} · F<n>" · outcome addressed|disputed|wontfix|open · category · rule or sig), ` +
+        `and write the FINDING-OUTCOME line if it is missing (\`orc trace write --packet -\`, run: ${run}). Then finish.`,
+    })
+  );
+  return true;
+}
+
 // ── The review card at SubagentStart (v2.0.2, eval D13) ─────────────────────
-// A live /orc-quick review dispatched `orc-reviewer-opus-5-med` with NO gotcha
+// A live /orc-quick review dispatched `orc-reviewer-opus-5-low` with NO gotcha
 // card in its prompt in 5 of 5 runs, although review learning is always on. The
 // card is a CLI answer, so the hook hands it over itself: for a reviewer,
 // verifier or judge, the files git sees as changed → `orc gotcha card` → one