tickmarkr 2.4.0 → 2.4.2

package/skills/tickmarkr-overseer/SKILL.md

@@ -165,6 +165,21 @@ overseer holds the mission's judgment. A tier collapse is therefore a context le
 **The tell, and you will not notice it from inside:** if you are typing `tickmarkr resume`, or reading a
 journal tail to decide what happens next, or sweeping orphans — you have taken the loop. Hand it back.
 
+### Pre-run checklist — install these laws in the brief before `compile` / `plan` / `run`
+
+1. **Run the files[]-versus-oracle pin sweep (RULING-222-36).** Read every acceptance item and enumerate
+   the PINS its satisfaction must move: implementation files, callers, fixtures, tests, snapshots and
+   documentation assertions. Put every pin in that task's `files[]` before compile. A criterion that
+   forces a file its scope forbids is a plan defect; repair the plan before dispatch, never spend a
+   worker's repair ladder on the scope/test catch-22.
+2. **Install the live-run command boundary (RULING-222-28 §5 and 222-29 §3).** While a run is live, run
+   no `vitest` probe of any size — the daemon's `suite-wait` guard counts it. During that same window the
+   runner's name never enters a shell argv: not reason text, a heredoc, `pgrep -f`, or a commit subject.
+   Write records containing the word through an editor, and wait for run-end before probing.
+3. **Gate a mid-run fix at the base, not at a summary (law 47 / OBS-909).** A fix landed on main while a
+   run is live is proved with `tickmarkr verify --base <main>`, never with a suite summary copied from a
+   different tree. A release proof runs every CI-ordered step — including lint — before its suite.
+
 ### What the ORCHESTRATOR does, and what you require of it
 
 - **The live surface arrives with the run.** `tickmarkr run` is stdout-silent until run-end by design;
@@ -358,7 +373,7 @@ The protocol, in both directions:
    herdr pane run <partner> "I am at <N>%. Clear me: send /clear to <my-pane>, then point me at <my-handoff>."
    # 3. the PARTNER sends the clear, then VERIFIES before pointing:
    herdr pane run <my-pane> "/clear"
-   #    read the pane back — a cleared claude session shows an empty prompt and a reset context gauge
+   #    read the pane back — a cleared claude session shows an empty prompt and a LOWER context percentage
    # 4. and only THEN, as a SEPARATE send, the re-orientation:
    herdr pane run <my-pane> "You were cleared at <N>%. Read <handoff> and <brief>. Same-process clear kept
    every background task alive: retire only your recorded watcher pids, verify twice, kill-by-pid, arm,
@@ -367,7 +382,9 @@ The protocol, in both directions:
 
    ⚠ **Steps 3 and 4 are two sends, never one.** A pointer batched with the clear lands *during* it and is
    lost with the context it was meant to survive. Verify the clear landed by reading the prompt line
-   before sending the pointer — the same read-back every other send in this skill requires.
+   and re-reading the banner percentage below its pre-clear value before sending the pointer — the same
+   read-back every other send in this skill requires. A working seat or a typed prompt defers the act;
+   neither authorises a queued `/clear`.
    ⚠ **The partner must not clear itself in the same window.** One supervising tier stays live at all
    times; the seat holding the endgame goes second.
    ⚠ **Step 4 must state an EXPECTED-RETURN DEADLINE**, e.g. *"confirm you are back within 10 minutes."*
@@ -451,7 +468,9 @@ The first argument chooses the closed per-seat tier (`orchestrator-context` or `
 and every beat names the second argument as that tier's seat. The watcher beats only after reading a
 rendered percentage, keeps beating on the supervision cadence even when its requested poll is slower,
 continues past WARN to ACT, and records a stand-down on each controlled exit. A killed watcher alone
-leaves its last beat to age into `STALE`.
+leaves its last beat to age into `STALE`. Auto-clear waits for `idle` plus an empty or dim-only ANSI
+prompt line, prints `CONTEXT_ACT_DEFERRED` while that gate is closed, and emits `CONTEXT_CLEARED` only
+after a banner read-back proves the percentage dropped; only then does it send the re-brief.
 **Every handoff's re-arm list ends with the announce step from Setup 0** — inform the surviving
 orchestrator the fresh seat is live — or the next seat re-arms silently beside a tier that still
 believes it is alone.
@@ -545,6 +564,11 @@ they are left implicit:
   that discriminates** — text sitting on `❯` is exactly what will not run — and a delivery report
   is prompt-line state alone, or nothing: a decorative check beside a real one reads as
   corroboration (two greens, one of which was never capable of disagreeing).
+  **Law 50 applies to every handoff, including `/clear`: a seat-send to a WORKING seat leaves a DRAFT.**
+  Send only when the seat is idle and the ANSI prompt line is empty or dim-only (the Esc/SGR discriminator
+  separates an autosuggest ghost from typed input), then read back activity or an ACK; presence is not
+  delivery. If a stale draft must be replaced, supersede it explicitly with
+  `agent prompt " <-- disregard … ACTUAL: …"` instead of stacking another instruction behind it.
 - **A MESSAGE TO A WORKING SEAT IS A QUEUED MESSAGE, AND THE QUEUE DRAINS ONLY AT TURN BOUNDARIES.**
   Delivery is not arrival: `agent prompt` to a `working` claude seat lands in its queue (`Press up to
   edit queued messages` on the seat's prompt line is the tell) and is READ only when the current turn
@@ -994,10 +1018,21 @@ orchestrator turn boundary.
    - **RUN BOTH RELEASE PROOFS BEFORE STANDING DOWN.** The first is the exported-tree suite, which
      maintainers run from the private repo with its `verify:export` script — that tooling is deliberately
      not part of this package, so the command does not exist in a public checkout; it must install,
-     build, and run the suite in the exported tree; then
+     build, lint, and only then run the suite in the exported tree; then
      `TICKMARKR_E2E=1 npx vitest run tests/e2e/orca-smoke.e2e.test.ts` must exercise the installed-Orca
      smoke. A skipped smoke is not proof. Record both results before declaring the release complete.
 
+   - **GRADE PUBLIC CI FROM JOB LOGS AT RUN-END ONLY (law 48).** A badge is not the grade, and
+     `gh run view --job --log` is empty while the run is in progress. At run-end execute
+     `scripts/grade-ci.sh <run-id> <expected-count> <tag>` and require GREEN from both jobs; its
+     UNREADABLE state is a hard stop, not a green default. Derive the expected glob pathspec count with
+     `git ls-files ':(glob)tests/**/*.test.ts'` (including the `.tsx` sibling where present), never a bare
+     `tests/**/*.test.ts`: bare `**` is not a git glob (law 49).
+
+   - **RE-READ THE REGISTRY BEFORE RULING (law 51).** A successful Release run and the first
+     `npm view` are separate observations: registry propagation can briefly return the prior version.
+     Read `npm view tickmarkr version` again and verify provenance before recording the publish verdict.
+
    - **REWRITE THE MEMORY INDEX FIRST, and read it back.** Minutes after `2.1.1` hit npm, the index line
      a fresh session loads still read *"⛔ 2.1.1 CANNOT ship from run …2011"* — true when written, and by
      then the exact opposite of the truth. **The index is what everyone loads and the body is what nobody

package/skills/tickmarkr-overseer/scripts/grade-ci.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# grade-ci.sh <run-id> <expected-count> [tag] — grade both public CI jobs from their JOB LOGS.
+# Grade only at run-end. A missing/in-progress/empty log is UNREADABLE, never evidence of green.
+# Tri-state: exit 0 GREEN, 1 RED, 2 UNREADABLE. UNREADABLE dominates a mixed result.
+set -u
+
+run=${1:?run id required}
+expected=${2:?expected tracked test-file count required}
+tag=${3:-$run}
+repo=${TKR_GRADE_CI_REPO:-alzahrani-khalid/tickmarkr}
+out_dir=${TKR_GRADE_CI_DIR:-${TKR_STATE_DIR:-.tickmarkr}/overseer/diag}
+mkdir -p "$out_dir" || { echo "UNREADABLE: cannot create log directory $out_dir"; exit 2; }
+
+verdict=0
+mark_unreadable() { verdict=2; }
+mark_red() { [ "$verdict" -eq 0 ] && verdict=1; }
+
+jobs=$(gh run view "$run" --repo "$repo" --json jobs \
+  --jq '.jobs[] | [.databaseId, .name, .status, (.conclusion // "")] | @tsv') \
+  || { echo "UNREADABLE: job list"; exit 2; }
+[ -n "$jobs" ] || { echo "UNREADABLE: empty job list"; exit 2; }
+
+seen_test=0
+seen_macos=0
+while IFS=$'\t' read -r id name status conclusion; do
+  case "$name" in
+    test) seen_test=1 ;;
+    test-macos) seen_macos=1 ;;
+    *) continue ;;
+  esac
+
+  echo "$name: status=$status conclusion=${conclusion:-none} job=$id"
+  if [ "$status" != "completed" ]; then
+    echo "$name: UNREADABLE (job has not reached run-end)"
+    mark_unreadable
+    continue
+  fi
+
+  log="$out_dir/CI-$tag-$name.log"
+  gh run view --repo "$repo" --job "$id" --log > "$log" 2>/dev/null
+  if [ ! -s "$log" ]; then
+    echo "$name: UNREADABLE (empty log)"
+    mark_unreadable
+    continue
+  fi
+
+  oracle=$(grep -oE 'COUNT_ORACLE [A-Z]+ expected=[0-9A-Z]+ actual=[0-9A-Z]+' "$log" | tail -1)
+  files=$(grep -oE 'Test Files .*' "$log" | sed 's/[[:space:]]*$//')
+  passed=$(printf '%s\n' "$files" | grep -oE '[0-9]+ passed' | awk '{s+=$1} END{print s+0}')
+  skipped=$(printf '%s\n' "$files" | grep -oE '[0-9]+ skipped' | awk '{s+=$1} END{print s+0}')
+  failed=$(printf '%s\n' "$files" | grep -oE '[0-9]+ failed' | awk '{s+=$1} END{print s+0}')
+  timedout=$(grep -cE 'Test timed out|Error: Hook timed out' "$log" || true)
+  errors=$(grep -oE '##\[error\].*' "$log" | sort | uniq -c | sed 's/^ *//' | tr '\n' ';')
+
+  echo "$name: oracle=[${oracle:-MISSING}] files=[$(printf '%s' "$files" | tr '\n' '|')] passed=$passed skipped=$skipped failed=$failed timedout=$timedout errors=[$errors]"
+  if [ -z "$oracle" ] || [ -z "$files" ]; then
+    echo "$name: UNREADABLE"
+    mark_unreadable
+  elif [ "$oracle" = "COUNT_ORACLE GREEN expected=$expected actual=$expected" ] \
+       && [ "$failed" -eq 0 ] && [ "$timedout" -eq 0 ] \
+       && [ $((passed + skipped)) -eq "$expected" ]; then
+    echo "$name: GREEN"
+  else
+    echo "$name: RED"
+    mark_red
+  fi
+done <<< "$jobs"
+
+if [ "$seen_test" -ne 1 ]; then
+  echo "test: UNREADABLE (job missing from run)"
+  mark_unreadable
+fi
+if [ "$seen_macos" -ne 1 ]; then
+  echo "test-macos: UNREADABLE (job missing from run)"
+  mark_unreadable
+fi
+
+echo "VERDICT rc=$verdict (0=all GREEN 1=RED 2=UNREADABLE)"
+exit "$verdict"

package/skills/tickmarkr-overseer/scripts/watch-context.sh

@@ -36,7 +36,7 @@
 #   TKR_AUTO_CLEAR=1   at act-pct WITH a fresh handoff, auto-clear orchestrator/overseer; other roles wake only.
 #   TKR_REBRIEF=<path> the file the re-briefed seat is told to read (defaults to the handoff).
 #   TKR_HANDOFF_MAX_AGE_S  how fresh "fresh" is (default 900).
-#   TKR_CLEAR_SETTLE_S     seconds to let a cleared seat settle before the re-brief (default 6).
+#   TKR_CLEAR_SETTLE_S     seconds allowed for the cleared banner percentage to drop (default 6).
 #   TKR_BLIND_ALARM_S      seconds unreadable before CONTEXT_BLIND alarms (default 120).
 #   TKR_CONTEXT_WINDOW     context window in tokens. Set it when the banner does not name one;
 #                          NEVER guessed — a wrong denominator makes every warn and act line wrong.
@@ -234,6 +234,82 @@ context_pct() {
   banner_pct
 }
 
+status_of() {
+  herdr agent get "$TARGET" 2>/dev/null \
+    | sed -n 's/.*"agent_status":"\([a-z_]*\)".*/\1/p' | head -1
+}
+
+# A clear is a SEND, so it inherits the verified-send precondition: the target must be between turns
+# and its live prompt line must contain no typed draft. Claude Code's autosuggest is text in the plain
+# rendering but is wrapped in SGR dim in the ANSI rendering; it is decoration, not a draft. Parse the
+# Esc-prefixed SGR bytes instead of treating every visible character after the prompt glyph as state.
+prompt_is_empty_or_dim() {
+  herdr agent read "$TARGET" --source visible --lines 14 --format ansi 2>/dev/null | python3 -c '
+import re, sys
+screen = sys.stdin.read().splitlines()
+ansi = re.compile(r"\x1b\[([0-9;]*)m")
+prompt = None
+for line in screen:
+    plain = ansi.sub("", line).lstrip()
+    if plain.startswith(("❯", "›")):
+        prompt = line
+if prompt is None:
+    sys.exit(1)
+glyph = min((i for i in (prompt.find("❯"), prompt.find("›")) if i >= 0), default=-1)
+if glyph < 0:
+    sys.exit(1)
+payload = prompt[glyph + 1:]
+dim = False
+pos = 0
+for match in ansi.finditer(payload):
+    if payload[pos:match.start()].strip() and not dim:
+        sys.exit(1)
+    codes = [int(c) if c else 0 for c in match.group(1).split(";")]
+    if 0 in codes:
+        dim = False
+    if 2 in codes:
+        dim = True
+    if 22 in codes:
+        dim = False
+    pos = match.end()
+if payload[pos:].strip() and not dim:
+    sys.exit(1)
+' 2>/dev/null
+}
+
+clear_target_ready() {
+  CLEAR_STATUS=$(status_of)
+  case "$CLEAR_STATUS" in
+    idle|done) ;;
+    *) CLEAR_REASON="status=${CLEAR_STATUS:-unreadable}"; return 1 ;;
+  esac
+  if ! prompt_is_empty_or_dim; then
+    CLEAR_REASON="status=$CLEAR_STATUS prompt=typed-or-unreadable"
+    return 1
+  fi
+  return 0
+}
+
+# `/clear` has landed only when a fresh banner read says its context percentage is lower. The JSONL
+# source deliberately does not participate in this receipt: it names the pre-clear session and can
+# remain at the old fill while the new prompt is already visible. No drop means no re-brief and no
+# CONTEXT_CLEARED claim.
+wait_for_clear_receipt() {
+  local before="$1" waited=0 after
+  case "$SETTLE" in *[!0-9]*|'') return 1 ;; esac
+  while :; do
+    after=$(banner_pct 2>/dev/null) || after=""
+    if printf '%s\n' "$after" | grep -qE '^[0-9]+$' \
+       && [ "$after" -lt "$before" ] 2>/dev/null; then
+      printf '%s\n' "$after"
+      return 0
+    fi
+    [ "$waited" -lt "$SETTLE" ] || return 1
+    sleep 1
+    waited=$((waited + 1))
+  done
+}
+
 handoff_fresh() {
   [ -n "$HANDOFF" ] || return 1
   [ -f "$HANDOFF" ] || return 1
@@ -245,13 +321,23 @@ handoff_fresh() {
 }
 
 act_on() {
-  local P="$1"
+  local P="$1" BEFORE AFTER
   if handoff_fresh; then
     if [ "${TKR_AUTO_CLEAR:-0}" = "1" ] && { [ "$ROLE" = "orchestrator" ] || [ "$ROLE" = "overseer" ]; }; then
+      if ! clear_target_ready; then
+        echo "CONTEXT_ACT_DEFERRED $TARGET at ${P}% — ${CLEAR_REASON}; waiting for idle and an empty/dim-only prompt line"
+        return 0
+      fi
+      BEFORE=$(banner_pct 2>/dev/null) || BEFORE=""
+      case "$BEFORE" in ''|*[!0-9]*) echo "CONTEXT_CLEAR_UNVERIFIED $TARGET — no numeric banner baseline; not clearing"; return 0 ;; esac
       herdr agent prompt "$TARGET" "/clear" >/dev/null 2>&1
-      sleep "$SETTLE"
+      if ! AFTER=$(wait_for_clear_receipt "$BEFORE"); then
+        echo "CONTEXT_CLEAR_UNVERIFIED $TARGET at ${P}% — banner did not re-read below ${BEFORE}% within ${SETTLE}s"
+        echo "  no re-brief sent and CONTEXT_CLEARED withheld; inspect the seat before acting again"
+        exit 0
+      fi
       herdr agent prompt "$TARGET" "Read ${REBRIEF} and continue exactly where it says. Your context was cleared at ${P}% against that handoff; it is current as of $(date '+%H:%M'). The same-process clear kept every background task alive: kill only this seat's recorded watcher pids first, verify the process table twice, then re-arm. Do not reconstruct from memory — everything you need is on disk." >/dev/null 2>&1
-      echo "CONTEXT_CLEARED $TARGET at ${P}% — handoff fresh, re-briefed from ${REBRIEF}"
+      echo "CONTEXT_CLEARED $TARGET ${P}% -> ${AFTER}% — banner re-read lower, handoff fresh, re-briefed from ${REBRIEF}"
       exit 0
     fi
     echo "CONTEXT_ACT $TARGET ${P}% (>= ${ACT}) — handoff is FRESH, a clear is SAFE now"