@erclx/canon 5.14.0 → 5.15.0

package/claude/skills/role-orchestrator/scripts/watch.sh

@@ -1,181 +0,0 @@
-#!/usr/bin/env bash
-# Reports worker and pull request transitions as they happen. Reads only.
-#
-# The poll answers "what moved since the last run" on a schedule the session
-# holds. This answers "what just changed" on a loop of its own, and it exists
-# because the two readings a dispatch needs are not one reading: a worker that
-# finishes goes idle and a worker that crashes vanishes, so a watch matching
-# only the pull request list stays silent through the second. A third case is
-# neither: a worker that stops on a question or a prompt neither finishes nor
-# crashes, and sits reading "waiting" beside the two statuses that resolve on
-# their own until something reports it, which is the WORKER-STOPPED line
-# below, or WORKER-UNMEASURABLE for a "waiting" row too old to carry a stamp
-# this reads.
-#
-# `set -e` is deliberately not set. This runs for hours, and one transient `gh`
-# failure aborting the loop is a silent stop rather than a reported one. Every
-# read below states its own failure instead.
-set -uo pipefail
-
-# Seconds between passes. A pass costs two cheap reads and the transitions it
-# watches take minutes, so the number trades staleness against little. Raise it
-# in a project whose workers run long.
-INTERVAL=60
-
-# Seconds a worker can sit in "waiting" before this reports it as stopped
-# rather than folding it into the ordinary status-change lines below. "busy"
-# and "idle" resolve on their own; "waiting" does not, so a dwell that keeps
-# growing there is a session blocked on something outside itself.
-#
-# Measured against the live session registry: 341 usable records carried a
-# status at all, and exactly one carried "waiting", too sparse a sample to fit
-# a distribution. The number is picked from the two bounds the measurement can
-# still name rather than from a round guess: well above INTERVAL, so a handful
-# of passes confirm the row before it reports rather than one slow tool call
-# tripping it, and well inside the ten-to-thirty-minute span a dispatched build
-# ordinarily runs, so a real stall is caught with most of that window still
-# open to act on it.
-#
-# That one record carried `waitingFor: "approve Bash"`, a permission prompt
-# rather than a question, and the two clear on different schedules: a prompt
-# resolves the moment a person approves it, where a question can sit
-# legitimately while a controller finishes a turn. This number is defensible
-# for the second and generous for the first, and the gap stays open rather
-# than splitting the constant on a sample of one.
-STALL_THRESHOLD_S=300
-
-# Resolving the main worktree root rather than this file's folder keeps a watch
-# started from a linked worktree reading the same repository as one started from
-# main. The repository field on a roster row is that root's `.git`.
-MAIN_ROOT="$(git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}')"
-if [ -z "$MAIN_ROOT" ]; then
-  echo "watch: not a git repository, so nothing is watched" >&2
-  exit 1
-fi
-REPOSITORY="$MAIN_ROOT/.git"
-
-# The base branch is read rather than assumed, since this ships to projects that
-# do not all call it `main`. It is what separates a worker from the controlling
-# session, which sits on the base branch in the main worktree.
-BASE_REF="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
-if [ -z "$BASE_REF" ]; then
-  BASE_REF="origin/$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null || echo main)"
-fi
-BASE_BRANCH="${BASE_REF#origin/}"
-
-# Every session in this repository holding a branch other than the base one is a
-# worker, whoever launched it. The prototype matched the `orchestrator-` prefix
-# instead, which reads a dispatched worker and misses every hand-launched one,
-# and those are the ordinary shape whenever the operator is launching.
-#
-# The row goes out tab-separated and comes back read with IFS set to a tab. A
-# name this client actually writes carries spaces, `Update session markdown
-# and check runnable commands (3)` among them, and splitting on whitespace
-# took that one apart into a wrong name, branch, status, and dwell.
-read_workers() {
-  canon sessions list --json 2>/dev/null | tail -1 | jq -r \
-    --arg repository "$REPOSITORY" --arg base "$BASE_BRANCH" '
-      .sessions[]?
-      | select(.repository == $repository)
-      | select(.branch != null and .branch != $base)
-      | [.name, .branch, .status, (.statusDwellMs // -1 | tostring)]
-      | @tsv
-    ' 2>/dev/null | sort
-}
-
-read_pulls() {
-  gh pr list --state open --json number,headRefName,title --jq \
-    '.[] | "PR-OPEN #\(.number) \(.headRefName) \(.title)"' 2>/dev/null | sort
-}
-
-# A failed read is reported and the previous baseline kept. Reading an empty
-# result as the current state would report every worker gone and every pull
-# request new on the pass after, which is the one failure that makes a detection
-# tool worth less than no tool.
-#
-# The two sources carry a baseline flag apiece rather than sharing one. A read
-# that fails on the first pass leaves its baseline empty while the other source
-# establishes one, and a single flag would then report that source's whole list
-# as new on the pass after it recovers.
-prev_pulls=""
-prev_workers=""
-prev_names=""
-pulls_seen=0
-workers_seen=0
-
-# One row per worker name currently reported, waiting past STALL_THRESHOLD_S
-# or waiting with no stamp to measure, so a reader watching the log is told
-# once rather than on every remaining pass. The prototype for that shape is
-# the WORKER-GONE/WORKER pair above, tracked in the same state a status change
-# is: a name drops out the pass it stops reading "waiting", which lets the
-# same worker report a second stall later in its life rather than being
-# marked forever by its first one.
-declare -A stalled
-
-while true; do
-  pulls="$(read_pulls)"
-  pulls_read=$?
-  workers="$(read_workers)"
-  workers_read=$?
-
-  if [ "$pulls_read" -ne 0 ]; then
-    echo "watch: the open pull request list failed to load, so none is classified this pass"
-  fi
-  if [ "$workers_read" -ne 0 ]; then
-    echo "watch: the session roster failed to load, so no worker is classified this pass"
-  fi
-
-  names="$(printf '%s\n' "$workers" | awk -F'\t' 'NF {print $1}' | sort -u)"
-
-  if [ "$pulls_seen" -eq 1 ] && [ "$pulls_read" -eq 0 ]; then
-    comm -13 <(printf '%s\n' "$prev_pulls") <(printf '%s\n' "$pulls") | grep . || true
-  fi
-
-  if [ "$workers_seen" -eq 1 ] && [ "$workers_read" -eq 0 ]; then
-    comm -13 <(printf '%s\n' "$prev_workers") <(printf '%s\n' "$workers") |
-      grep . | sed 's/^/WORKER /' || true
-    comm -23 <(printf '%s\n' "$prev_names") <(printf '%s\n' "$names") |
-      grep . | sed 's/^/WORKER-GONE /' || true
-  fi
-
-  if [ "$workers_read" -eq 0 ]; then
-    while IFS=$'\t' read -r w_name w_branch w_status w_dwell_ms; do
-      [ -z "$w_name" ] && continue
-
-      if [ "$w_status" != "waiting" ]; then
-        unset "stalled[$w_name]"
-        continue
-      fi
-
-      if [ "$w_dwell_ms" = "-1" ]; then
-        if [ -z "${stalled[$w_name]:-}" ]; then
-          echo "WORKER-UNMEASURABLE $w_name $w_branch"
-          stalled[$w_name]=1
-        fi
-        continue
-      fi
-
-      w_dwell_s=$((w_dwell_ms / 1000))
-      if [ "$w_dwell_s" -ge "$STALL_THRESHOLD_S" ]; then
-        if [ -z "${stalled[$w_name]:-}" ]; then
-          echo "WORKER-STOPPED $w_name $w_branch ${w_dwell_s}s"
-          stalled[$w_name]=1
-        fi
-      else
-        unset "stalled[$w_name]"
-      fi
-    done <<<"$workers"
-  fi
-
-  if [ "$pulls_read" -eq 0 ]; then
-    prev_pulls="$pulls"
-    pulls_seen=1
-  fi
-  if [ "$workers_read" -eq 0 ]; then
-    prev_workers="$workers"
-    prev_names="$names"
-    workers_seen=1
-  fi
-
-  sleep "$INTERVAL"
-done

package/governance/rules/canon/645-decisions.md

@@ -1,12 +0,0 @@
----
-description: Route canon/decisions/ edits to the decisions standard for record shape and lifecycle
-paths:
-  - 'canon/decisions/**'
-  - '.claude/decisions/**'
----
-
-# Decisions standards
-
-## Authority
-
-- Follow the decisions standard for folder layout, the ordinal filename, frontmatter, record sections, and the append-only lifecycle. It is the single source. Read it with `canon standards decisions`.

package/standards/decisions.md

@@ -1,105 +0,0 @@
----
-title: Decisions reference
-description: Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
----
-
-# Decisions reference
-
-Applies to `canon/decisions/`. Holds the history a canonical doc used to carry itself: pick rounds, superseded figures, and a decision's rejected alternatives, in a tracked folder nothing loads eagerly. A canonical doc points at a record from its own history section rather than restating it.
-
-## Scope
-
-Governs `canon/decisions/`: folder layout, the ordinal filename, frontmatter, record sections, and the append-only lifecycle.
-
-Does not govern:
-
-- Which canonical doc points here and when, and what stays behind in that doc's own body: `architecture.md`, `context.md`, `wireframes.md`, `design.md`, `requirements.md`, once each states its own retirement rule
-- Voice, rhythm, and sentence construction: the `write-human` skill
-- Headings, punctuation, word choice, and file references: `markdown.md`
-
-## What a working record looks like
-
-A record works when a reader who has never opened the project can follow it from the file alone:
-
-- What was decided, stated once, without needing the canonical doc that points here
-- What else was considered, and why each alternative lost
-- Which claim rests on a measurement, and what commit that measurement was read against
-
-A record failing these is non-conforming even when it satisfies every shape rule below.
-
-## Folder name
-
-- `canon/decisions/`, resolved the way every tracked surface is: at `canon/decisions/` in a project that has moved, at `.claude/decisions/` in one that has not.
-- Never add `canon/decisions/index.md` to a `CLAUDE.md` `@` import. A log that loads eagerly rebuilds the bloat it exists to absorb. A canonical doc's own pointer is how a reader reaches a record, one file at a time.
-
-## Record filename
-
-- Name each record `<nn>-<slug>.md`, a two-digit zero-padded ordinal followed by a kebab-case slug, the same shape a groundwork track's folder takes.
-- The ordinal is the order the record was written in, which is what lets a listing sort by when a decision landed rather than alphabetically by subject.
-- Never renumber an existing record. A later reader cites it by that name, and a record whose number moved is a record a stale citation can no longer find.
-
-## Frontmatter
-
-- `title` (required): the decision in sentence case
-- `description` (required): one line naming what was decided
-
-## Sections
-
-Use `## Context`, `## Decision`, `## Alternatives`, `## Revisit when`, and `## Measurements`.
-
-- `## Context`: the problem as it stood, stated so a reader needs nothing else open. Restate a fact rather than pointing at where it was found.
-- `## Decision`: what was chosen, and why, in enough detail that a reader can tell it apart from an alternative that sounds similar.
-- `## Alternatives`: each one considered and dropped, with the reason it lost. An alternative with no stated reason reads as a claim nobody checked.
-- `## Revisit when`: one bullet per finding that would reopen the decision. Required when the record came from a groundwork track whose deciding leans carried "Overturned by" lines, which carry over as written. It is optional otherwise, for a decision resting on how an outside tool, an installer, or the model behaves. Skip it for a decision resting on the project's own code.
-- `## Measurements`: skip when the decision cites no number. When it does, state the number and close with the commit it was read against, per Verification anchors below.
-
-## Verification anchors
-
-A record's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
-
-- Close a `## Measurements` section with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
-- Anchor on the number alone. A record citing none carries no `## Measurements` section at all.
-- Read an absent section as unchecked rather than as current. A record with no measurements has nothing due a re-read.
-
-## Lifecycle
-
-- Append-only. A written record is never edited to reflect a later reversal.
-- Write a new record when a later decision supersedes an earlier one, naming the record it supersedes. The old record stays as it was written, since it is history rather than a live statement of the current shape.
-- Never auto-loaded. A canonical doc's own history section links to a record by relative path, and a reader reaches it by following that link, not by the folder loading with the session.
-
-## Citation
-
-- Never cite `.canon/`. A record restates what it needs, since a clone without the gitignored records folder resolves nothing there.
-- Cite a same-repository pull request or commit the way `publish.md` fixes for any tracked document.
-
-## Template
-
-```markdown
----
-title: <Decision, in sentence case>
-description: <one line naming what was decided>
----
-
-# <Decision title>
-
-## Context
-
-<The problem as it stood, self-contained.>
-
-## Decision
-
-<What was chosen, and why.>
-
-## Alternatives
-
-- **<Alternative>.** <Why it lost.>
-- **<Alternative>.** <Why it lost.>
-
-## Revisit when
-
-- <The finding that would reopen the decision.>
-
-## Measurements
-
-<The number the decision rests on.> Measured at <short-sha> on <YYYY-MM-DD>.
-```

package/tooling/claude/seeds/canon/decisions/index.md

@@ -1,8 +0,0 @@
----
-title: Decisions
-subtitle: Decision history a project doc points at, never loaded eagerly
----
-
-# Decisions
-
-Decision history a project doc points at, never loaded eagerly