@azure-id/orc 2.0.2 → 2.1.1

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