@erclx/canon 5.4.0 → 5.5.0

package/src/teach/nav.ts

@@ -1613,8 +1613,19 @@ export async function generateNav(
     const detail = found.workspace
     const metas = await readLessonMetas(root, detail)
 
+    // The generated base sheet is rewritten on every run so a CLI upgrade
+    // reaches it, while a legacy workspace holding only a hand-authored
+    // course.css is never handed a base sheet its lessons do not link.
     const cssPath = join(root, detail.path, TEACH_ASSETS, TEACH_STYLESHEET)
-    if (!existsSync(cssPath)) await writeStylesheet(root, detail.slug)
+    const basePath = join(
+      root,
+      detail.path,
+      TEACH_ASSETS,
+      TEACH_STYLESHEET_BASE,
+    )
+    if (existsSync(basePath) || !existsSync(cssPath)) {
+      await writeStylesheet(root, detail.slug)
+    }
 
     const contentsPath = join(root, detail.path, 'index.html')
     await writeFile(

package/standards/architecture.md

@@ -65,6 +65,17 @@ A decision's reasoning stays correct while the numbers it cites move. The anchor
 - Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
 - Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
 
+## Revisit condition
+
+A decision says why it won and rarely says when that reason stops holding, so an entry can go stale while every word in it stays true. The revisit sentence names the finding that would show the harm the decision prevents has gone or moved.
+
+- Close each decision with one sentence of the form `Revisit when <finding>.` Name something a reader could notice, such as a platform release, a measured count crossing a line, or a dependency dropping a behavior.
+- Draft it from the harm the decision prevents, never from the mechanism it uses. A mechanism can keep working long after the reason for choosing it is gone, so re-checking it confirms the wrong fact.
+- Place the sentence after the reasoning and before any verification anchor, so the anchor stays the entry's last sentence.
+- Give a heading holding several principles one sentence, for the premise they share, rather than one per principle.
+- Adopt the requirement by stating the clause `Every decision closes with a revisit sentence.` in the record itself. The clause is the record's own, like the cap, so a checker reads it from the file and gates only a record that states it. A record stating none is reported and never gated.
+- A checker reads presence alone. A vacuous sentence passes it, so the sentence is only as useful as the finding it names.
+
 ## Entry cap
 
 Every session pays for this file before any work starts, so a heavy read is a real cost. A file that reads heavy is carrying too many decisions, not decisions written too long, so the bound is a count of decisions rather than of words.
@@ -78,20 +89,20 @@ Every session pays for this file before any work starts, so a heavy read is a re
 
 ## Template
 
-The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none. Each heading below names a slot, so a record starts with one decision per slot and renames each heading to the choice it records.
+The revisit sentence closes the reasoning of every decision. The anchor sentence follows it on a decision whose reasoning cites a measured number and is absent from one that cites none. Each heading below names a slot, so a record starts with one decision per slot and renames each heading to the choice it records.
 
 ```markdown
 # Architecture
 
 ## Overview
 
-This record holds at most 12 decisions.
+This record holds at most 12 decisions. Every decision closes with a revisit sentence.
 
 ## Key technical decisions
 
 ### Stack and runtime
 
-What was chosen, the alternative that lost, and why. Measured at <short-sha> on <YYYY-MM-DD>.
+What was chosen, the alternative that lost, and why. Revisit when <finding>. Measured at <short-sha> on <YYYY-MM-DD>.
 
 ### Delivery
 

package/claude/skills/bash-script/REQUIREMENT.md

@@ -1,36 +0,0 @@
----
-name: bash-script
-description: Scope boundary for the interactive script house style and the stream discipline underneath it
----
-
-# Bash script requirement
-
-## Gap
-
-Without this skill, a session asked for a human-facing shell tool writes one whose frame decoration, log lines, and prompts all land on stdout, so the script cannot be piped and any data it emits arrives mixed with its own presentation.
-
-Three more failures share a cause, which is that an interactive script is written as though a person is always watching. A prompt blocks forever when stdin is not a terminal, which is the shape every CI job and every agent run has. A cancellation path prints both a cancel line and an error, or an exit trap prints a closing frame the success path already printed, so the same run reports twice. And each generated script picks its own icons, casing, and frame characters, so a folder of them reads as several unrelated tools.
-
-The visual conventions this skill fixes are otherwise arbitrary. Their value is that they are the same across every script, which is a property no individual script can establish for itself.
-
-## Must
-
-- Keep every frame, log line, and prompt on stderr, and reserve stdout for data. `--help` is the one exception, since its consumer is a person rather than a pipe.
-- Guard every prompt on an attached terminal and refuse inside the frame rather than blocking on a read that will never return
-- Give the timeline one owner per exit path, so success, cancellation, and error each close it exactly once
-- Copy the shared templates rather than restating them, keeping only the colors and functions the script uses
-
-## Must not
-
-- Assert a convention the generated script cannot be checked against by reading it. A rule that cannot be verified from the output is style with no gate behind it.
-- Carry a second copy of the timeline, logging, or prompt implementations. The bundled reference is the single copy, and a body that restates it drifts from it.
-
-## Guards
-
-- A request for a script with no human at the terminal stops and routes to `bash-cli-script` rather than generating a timeline nothing will render
-
-## Out of scope
-
-- Non-interactive automation, CI, and agent-run scripts: `bash-cli-script`, which keeps the error handling and the stdout contract and drops the timeline, the icons, and the prompts
-- GitHub Actions workflow files: `ci-workflow`
-- What the generated script does. This skill fixes the shape of the output and the stream it goes to, and the commands belong to the request.

package/claude/skills/bash-script/SKILL.md

@@ -1,100 +0,0 @@
----
-name: bash-script
-description: Generates production Bash scripts with a visual timeline UI, state-based interactive prompts, and strict error handling. Use when asked for "a human-facing shell tool", an interactive bash script, or a DevOps tool with framed terminal output. Do NOT use for a non-interactive automation, CI, or pipeline script, that is `bash-cli-script`.
----
-
-# Bash script
-
-Generate production-ready Bash scripts for DevOps and CLI workflows. Enforce strict formatting with a visual timeline UI and state-based interactivity.
-
-Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, logging, help-screen, and full-script code templates, and `${CLAUDE_SKILL_DIR}/references/prompts.md` for the `ask()` and `select_option()` templates when the script prompts. `${CLAUDE_SKILL_DIR}` expands to this skill's own directory, so the path resolves from any project. Copy those definitions verbatim, keeping only the colors and functions the script actually uses.
-
-## Guards
-
-- A request for a script with no human at the terminal stops and routes to `bash-cli-script`. CI jobs, cron entries, agent-run tasks, and any script whose output is consumed by a pipe render no timeline, so generating one costs the frame and returns nothing.
-
-## Script setup
-
-- Start with `#!/usr/bin/env bash`, `set -e`, and `set -o pipefail`.
-- Bash 4+ features (namerefs, associative arrays) are allowed.
-- Implement a visual help screen via `show_help` if the script accepts arguments.
-- Do not rely on unset variables. Use `${VAR:-default}`.
-
-## Visual timeline
-
-- Maintain a vertical timeline (`│`) from `┌` to `└` throughout all output.
-- Write all frame output (`┌`, `│`, `├`, `└`, log lines, prompts) to stderr via `>&2`. Write data (JSON, lists, piped values) to stdout. `--help` is the exception and prints to stdout.
-- Open the timeline once at the start of `main()` via `open_timeline "Title"`, before any logic, prompts, or checks.
-- Close the timeline via `trap close_timeline EXIT`, registered immediately after `open_timeline`.
-- On success, disable with `trap - EXIT`, then print `└\n` and the success message manually.
-- On cancellation and error, never print `└` manually. The trap owns those exits.
-- Use state transitions for interactive prompts: `◆` active, `◇` inactive.
-- Do not add diamonds (`◆` or `◇`) to non-interactive log functions.
-- On cancellation, show `◇ ... Cancelled`, exit 1, and make no `log_error` call. Both `ask()` and `select_option()` handle escape cancellation identically.
-- Guard interactive prompts against non-TTY stdin with `[ -t 0 ]` and render a framed `log_error` when a TTY is required but absent. Never let `read` block silently on piped input.
-
-## Code style
-
-- Decompose by responsibility: each function does one thing, `main()` orchestrates only.
-- Name functions verb-first: `validate_input`, `deploy_service`, `install_dependencies`.
-- Do not use global variables except exports from `ask()`.
-- Do not define unused color variables.
-- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
-- Use sentence case for section headers and log messages. Proper nouns and product names retain their casing.
-- Quote variables inside parameter expansions: `"${file#"$dir"/}"` not `"${file#$dir/}"`.
-- Quote variables in test brackets: `[ "$i" -eq "$cur" ]` not `[ $i -eq $cur ]`.
-- Guard commands that return non-zero on valid empty results: `grep ... || true`, `diff ... || true`.
-
-## Output hygiene
-
-- Show external tool output by default (git, npm, gh).
-- Include context in error messages: `log_error "npm install failed: check package.json"`.
-- Do not echo command names before running them. Output speaks for itself.
-- Do not log "Starting..." and "Finished..." around every action.
-- Do not log intermediate variable assignments.
-- Use `log_add` for item writes (files created, entries added, keys written).
-- Use `log_info` for status confirmations only ("up to date", "check passed").
-- Use `log_warn` for drift, skipped states, or recoverable issues.
-- Never use `log_info` for file or entry writes.
-
-## Icon usage
-
-Interactive prompts only:
-
-- `◆` (green): active user input required
-- `◇` (grey): completed input, transition via `\r\033[K` to rewrite the `◆` line in place
-- `❯` (green): selected option in a menu
-- plain text (grey): unselected option in a menu
-
-Non-interactive logs:
-
-- `├` section branch (`log_step`)
-- `✓` (green): success (`log_info`)
-- `!` (yellow): warning (`log_warn`)
-- `✗` (red): error (`log_error`)
-- `+` (green): add item (`log_add`)
-- `-` (red): remove item (`log_rem`)
-
-## Validation
-
-Before responding, verify:
-
-- File starts with `#!/usr/bin/env bash`, `set -e`, `set -o pipefail` and uses exactly 2 spaces for indentation.
-- Timeline opens via `open_timeline "Title"`, which writes `┌` and `│ Title` to stderr.
-- Timeline closes via `trap close_timeline EXIT` registered immediately after `open_timeline`. Success paths use `trap - EXIT` then manual `└\n` (to stderr) then the success message. Cancellation and error paths never print `└` manually.
-- `open_timeline` and `close_timeline` are defined and write to stderr via `>&2`.
-- All frame output (`│`, `├`, `└`, log lines, interactive prompts) writes to stderr via `>&2`. Stdout carries data only. `--help` is the exception.
-- Interactive prompts (`ask`, `select_option`) guard with `[ -t 0 ]` and call `log_error` if stdin is not a TTY.
-- The timeline (`│`) appears in all log functions, and interactive prompts use `◆` → `◇` transitions.
-- `ask()` uses `\r\033[K` to rewrite the `◆` line in place, with no `\033[1A` cursor-up sequences.
-- `ask()` drains trailing escape bytes with `read -rsn2 -t 0.001 _ || true` before cancelling.
-- All log messages use sentence case (proper nouns and product names exempt).
-- Only defined color variables are used in the script.
-- Cancellation shows a single `◇ ... Cancelled` line without a subsequent `log_error`.
-- Escape key in `ask()` triggers `◇ ... Cancelled` and exits, consistent with `select_option()`.
-- Functions follow single responsibility: each does one thing, `main()` delegates to helpers.
-- Logging is concise: no "Starting.../Finished..." bloat, no intermediate variable logging.
-- `log_add` is used for all file, entry, and key writes.
-- `log_info` is used for status confirmations only, not writes.
-- Every section header uses `log_step`, including the first one after the title block.
-- File ends with exactly one empty line.

package/claude/skills/bash-script/references/patterns.md

@@ -1,250 +0,0 @@
-# Bash script patterns
-
-Code templates for the `bash-script` skill. Copy verbatim, keeping only the colors and functions the script uses.
-
-## Timeline structure
-
-```plaintext
-┌                    # Start boundary (alone on its own line)
-│ Title              # Script or context title (immediately after ┌)
-│                    # Persistent vertical line (grey)
-├ Section Branch     # Section headers (no diamond)
-│ ✓ Log message      # Info/success logs
-│ ! Warning          # Warning logs
-│ ✗ Error            # Error logs
-└                    # End boundary
-```
-
-## Color palette
-
-Define only the colors the script uses from this set:
-
-```bash
-GREEN='\033[0;32m'      # Success/Active
-RED='\033[0;31m'        # Error/Delete
-YELLOW='\033[0;33m'     # Warning
-WHITE='\033[1;37m'      # Active text
-GREY='\033[0;90m'       # Timeline/Inactive
-CYAN='\033[0;36m'       # Optional accent
-MAGENTA='\033[0;35m'    # Optional highlight
-NC='\033[0m'            # Reset
-```
-
-## Timeline lifecycle
-
-Define `open_timeline` and `close_timeline`. Call `open_timeline "Title"` at the start of `main()`, then register `close_timeline` as the EXIT trap. The trap guarantees `└` prints on every exit path: normal completion, `exit 1` from cancellation, or unexpected errors. Do not print `└` manually anywhere else.
-
-```bash
-open_timeline() {
-  echo -e "${GREY}┌${NC}" >&2
-  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
-}
-
-close_timeline() {
-  echo -e "${GREY}└${NC}" >&2
-}
-```
-
-Register the trap inside `main()` right after opening:
-
-```bash
-open_timeline "Script title"
-trap close_timeline EXIT
-```
-
-## Logging
-
-All log functions include the `│` prefix and write to stderr.
-
-```bash
-log_info()  { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2; }
-log_warn()  { echo -e "${GREY}│${NC} ${YELLOW}!${NC} $1" >&2; }
-log_error() { echo -e "${GREY}│${NC} ${RED}✗${NC} $1" >&2; exit 1; }
-log_step()  { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2; }
-log_add()   { echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2; }
-log_rem()   { echo -e "${GREY}│${NC} ${RED}-${NC} $1" >&2; }
-```
-
-## Section headers
-
-Use `log_step` for every section header, including the first. It emits a leading blank `│` line to separate the banner from the first section and to give breathing room between subsequent sections:
-
-```bash
-open_timeline "Script title"
-trap close_timeline EXIT
-
-log_step "Deploy"
-log_step "Verify"
-```
-
-Renders as:
-
-```plaintext
-┌
-│ Script title
-│
-├ Deploy
-...
-│
-├ Verify
-...
-└
-```
-
-## Help system
-
-```bash
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} ./script.sh [options]"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}│${NC}    [flag]        ${GREY}# [Description]${NC}"
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-```
-
-## Error handling helper
-
-```bash
-run_check() {
-  local cmd=$1
-  local err_msg=$2
-  if ! eval "$cmd"; then
-    log_error "$err_msg"
-  fi
-}
-```
-
-## Full script structure
-
-```bash
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-[Color definitions - only used colors]
-
-[Function definitions - only needed functions]
-
-open_timeline() {
-  echo -e "${GREY}┌${NC}" >&2
-  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
-}
-
-close_timeline() {
-  echo -e "${GREY}└${NC}" >&2
-}
-
-check_dependencies() {
-  [Verify required tools installed]
-}
-
-main() {
-  check_dependencies
-
-  open_timeline "Script title"
-  trap close_timeline EXIT
-
-  log_step "First section"
-  [Script logic with timeline maintained]
-
-  trap - EXIT
-  echo -e "${GREY}└${NC}\n" >&2
-  echo -e "${GREEN}✓ Final success message${NC}"
-}
-
-main "$@"
-```
-
-## Worked example
-
-```bash
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-GREEN='\033[0;32m'
-RED='\033[0;31m'
-YELLOW='\033[0;33m'
-WHITE='\033[1;37m'
-GREY='\033[0;90m'
-NC='\033[0m'
-
-log_info()  { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2; }
-log_error() { echo -e "${GREY}│${NC} ${RED}✗${NC} $1" >&2; exit 1; }
-log_step()  { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2; }
-log_add()   { echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2; }
-
-open_timeline() {
-  echo -e "${GREY}┌${NC}" >&2
-  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
-}
-
-close_timeline() {
-  echo -e "${GREY}└${NC}" >&2
-}
-
-ask() {
-  local prompt_text=$1
-  local var_name=$2
-  local default_val=$3
-  local input=""
-  local char
-  local display_default=""
-  if [ -n "$default_val" ]; then
-    display_default=" (${default_val})"
-  fi
-  if [ ! -t 0 ]; then
-    log_error "${prompt_text} requires a TTY"
-  fi
-  echo -e "${GREY}│${NC}" >&2
-  echo -ne "${GREEN}◆${NC} ${prompt_text}${display_default} " >&2
-  while IFS= read -r -s -n1 char; do
-    if [[ $char == $'\x1b' ]]; then
-      read -rsn2 -t 0.001 _ || true
-      echo -ne "\r\033[K" >&2
-      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
-      exit 1
-    elif [[ $char == $'\x7f' || $char == $'\x08' ]]; then
-      if [ -n "$input" ]; then
-        input="${input%?}"
-        echo -ne "\b \b" >&2
-      fi
-    elif [[ -z "$char" ]]; then
-      break
-    else
-      input+="$char"
-      echo -n "$char" >&2
-    fi
-  done
-  [ -z "$input" ] && input="$default_val"
-  echo -ne "\r\033[K" >&2
-  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${input}${NC}" >&2
-  export "$var_name"="$input"
-}
-
-check_dependencies() {
-  command -v npm >/dev/null 2>&1 || log_error "npm not installed"
-}
-
-main() {
-  check_dependencies
-
-  open_timeline "Project Setup"
-  trap close_timeline EXIT
-
-  ask "Project name?" "PROJECT_NAME" "my-app"
-
-  log_step "Installing dependencies"
-  npm install vite
-  log_add "vite@latest"
-
-  log_info "Setup complete"
-  echo -e "\n${GREEN}✓ Project created successfully${NC}"
-}
-
-main "$@"
-```

package/claude/skills/bash-script/references/prompts.md

@@ -1,100 +0,0 @@
-# Bash script prompts
-
-Interactive prompt templates for the `bash-script` skill, read only when the script prompts. Copy verbatim, alongside the colors and logging functions from `patterns.md`.
-
-Both prompts transition `◆` to `◇`, guard against non-TTY stdin with `[ -t 0 ]`, and write UI to stderr.
-
-```bash
-ask() {
-  local prompt_text=$1
-  local var_name=$2
-  local default_val=$3
-  local input=""
-  local char
-  local display_default=""
-  if [ -n "$default_val" ]; then
-    display_default=" (${default_val})"
-  fi
-  if [ ! -t 0 ]; then
-    log_error "${prompt_text} requires a TTY"
-  fi
-  echo -e "${GREY}│${NC}" >&2
-  echo -ne "${GREEN}◆${NC} ${prompt_text}${display_default} " >&2
-  while IFS= read -r -s -n1 char; do
-    if [[ $char == $'\x1b' ]]; then
-      read -rsn2 -t 0.001 _ || true
-      echo -ne "\r\033[K" >&2
-      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
-      exit 1
-    elif [[ $char == $'\x7f' || $char == $'\x08' ]]; then
-      if [ -n "$input" ]; then
-        input="${input%?}"
-        echo -ne "\b \b" >&2
-      fi
-    elif [[ -z "$char" ]]; then
-      break
-    else
-      input+="$char"
-      echo -n "$char" >&2
-    fi
-  done
-  [ -z "$input" ] && input="$default_val"
-  echo -ne "\r\033[K" >&2
-  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${input}${NC}" >&2
-  export "$var_name"="$input"
-}
-```
-
-```bash
-select_option() {
-  local prompt_text=$1
-  shift
-  local options=("$@")
-  local cur=0
-  local count=${#options[@]}
-
-  if [ ! -t 0 ]; then
-    log_error "${prompt_text} requires a TTY"
-  fi
-
-  echo -ne "${GREY}│${NC}\n${GREEN}◆${NC} ${prompt_text}\n" >&2
-
-  while true; do
-    for i in "${!options[@]}"; do
-      if [ "$i" -eq "$cur" ]; then
-        echo -e "${GREY}│${NC}  ${GREEN}❯ ${options[$i]}${NC}" >&2
-      else
-        echo -e "${GREY}│${NC}    ${GREY}${options[$i]}${NC}" >&2
-      fi
-    done
-
-    read -rsn1 key
-    case "$key" in
-      $'\x1b')
-        if read -rsn2 -t 0.001 key_seq; then
-          if [[ "$key_seq" == "[A" ]]; then cur=$(( (cur - 1 + count) % count )); fi
-          if [[ "$key_seq" == "[B" ]]; then cur=$(( (cur + 1) % count )); fi
-        else
-          echo -en "\033[$((count + 1))A\033[J" >&2
-          echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
-          exit 1
-        fi
-        ;;
-      "k") cur=$(( (cur - 1 + count) % count ));;
-      "j") cur=$(( (cur + 1) % count ));;
-      "q")
-        echo -en "\033[$((count + 1))A\033[J" >&2
-        echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
-        exit 1
-        ;;
-      "") break ;;
-    esac
-
-    echo -en "\033[${count}A" >&2
-  done
-
-  echo -en "\033[$((count + 1))A\033[J" >&2
-  echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${WHITE}${options[$cur]}${NC}" >&2
-  SELECTED_OPTION="${options[$cur]}"
-}
-```