@erclx/canon 4.0.0

package/scripts/standards/list.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/frontmatter.sh"
+
+STANDARDS_DIR="$PROJECT_ROOT/standards"
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} canon standards list [options]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    --json       ${GREY}# Emit machine-readable JSON${NC}"
+  echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  printf '%s' "$s"
+}
+
+# Emits the paths a standard's `## Scope` statement declares, as a JSON array.
+# The declaration is prose, so the contract is narrow on purpose: backticked
+# paths in the first sentence of the statement, or `*` for an attribute standard,
+# which names no path and says so in the same statement. An empty array means the
+# statement did not parse, which consumers report rather than skip.
+read_applies_to() {
+  local file="$1"
+  local scope first paths
+
+  scope=$(awk '/^## Scope[[:space:]]*$/ {found = 1; next} found && NF {print; exit}' "$file")
+  first="${scope%%. *}"
+  paths=$(printf '%s' "$first" | grep -o '`[^`]*`' | tr -d '`' || true)
+
+  if [ -z "$paths" ] && [[ "$scope" == *"attribute standard"* ]]; then
+    paths="*"
+  fi
+
+  printf '%s\n' "$paths" | jq -Rnc '[inputs | select(length > 0)]'
+}
+
+list_text() {
+  log_step "Standards"
+  local file name title
+  while IFS= read -r file; do
+    name=$(basename "$file" .md)
+    [ "$name" = "index" ] && continue
+    title=$(read_frontmatter_field "$file" "description")
+    log_info "$name : $title"
+  done < <(find "$STANDARDS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+}
+
+# No `target` field. It named where a standard installed, and nothing installs
+# one now, so every value it could carry is either a path only this repository
+# has or a duplicate of what `canon standards <name>` reports. `content` already
+# carries the document, which is what a consumer wanted the path for.
+list_json() {
+  local first=1
+  local file name title applies_to
+  printf '['
+  while IFS= read -r file; do
+    name=$(basename "$file" .md)
+    [ "$name" = "index" ] && continue
+    title=$(read_frontmatter_field "$file" "description")
+    applies_to=$(read_applies_to "$file")
+    if [ "$first" -eq 0 ]; then
+      printf ','
+    fi
+    jq -nc \
+      --arg name "$name" \
+      --arg description "$title" \
+      --argjson appliesTo "$applies_to" \
+      --rawfile content "$file" \
+      '{name: $name, description: $description, appliesTo: $appliesTo, content: $content}'
+    first=0
+  done < <(find "$STANDARDS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  printf ']'
+}
+
+main() {
+  local json=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+    -h | --help) show_help ;;
+    --json)
+      json=1
+      shift
+      ;;
+    *) log_error "Unknown option: $1" ;;
+    esac
+  done
+
+  trap close_timeline EXIT
+
+  if [ "$json" -eq 1 ]; then
+    printf '{"standards":'
+    list_json
+    printf '}\n'
+    exit 0
+  fi
+
+  list_text
+}
+
+main "$@"

package/scripts/tooling/create.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
+trap close_timeline EXIT
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  log_step "Tooling create usage"
+  echo -e "${GREY}│${NC}  ${WHITE}Usage:${NC} canon tooling create [stack]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  Creates a new stack with stub manifest, reference, configs, and seeds."
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Arguments:${NC}"
+  echo -e "${GREY}│${NC}    stack   Name of the new stack to create"
+  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}"
+  exit 0
+}
+
+main() {
+  if [[ "$1" == "-h" || "$1" == "--help" ]]; then
+    show_help
+  fi
+
+  local stack="$1"
+
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}│${NC} ${WHITE}canon tooling create${NC}"
+
+  if [ -z "$stack" ]; then
+    ask "Stack name?" "stack"
+  fi
+
+  if [ -z "$stack" ]; then
+    log_error "Stack name is required"
+  fi
+
+  if is_tooling_stack_excluded "$stack"; then
+    log_error "Reserved name: $stack. Managed by \`canon claude\`, not \`canon tooling\`."
+  fi
+
+  local dest="$PROJECT_ROOT/tooling/$stack"
+
+  if [ -d "$dest" ]; then
+    log_error "Stack already exists: $stack"
+  fi
+
+  log_step "Creating"
+  log_add "tooling/$stack/configs/"
+  log_add "tooling/$stack/seeds/"
+  log_add "tooling/$stack/manifest.toml"
+  log_add "tooling/$stack/reference.md"
+
+  select_option "Create stack at tooling/$stack?" "Yes" "No"
+
+  if [ "$SELECTED_OPTION" = "No" ]; then
+    log_warn "Cancelled"
+    exit 0
+  fi
+
+  log_step "Applying"
+
+  mkdir -p "$dest/configs"
+  log_add "tooling/$stack/configs/"
+
+  mkdir -p "$dest/seeds"
+  log_add "tooling/$stack/seeds/"
+
+  cat >"$dest/manifest.toml" <<EOF
+[stack]
+name = "$stack"
+extends = ""
+runtime = ""
+scaffold = ""
+
+[dependencies.dev]
+packages = []
+
+[scripts]
+"script-key" = "command --flag"
+
+[gitignore]
+"# $stack" = ["pattern/", ".file"]
+EOF
+  log_add "tooling/$stack/manifest.toml"
+  cat >"$dest/reference.md" <<EOF
+# Tooling $stack reference
+
+## Overview
+
+[One or two sentences: what this stack provides and its purpose.]
+
+EOF
+  log_add "tooling/$stack/reference.md"
+
+  trap - EXIT
+  echo -e "${GREY}└${NC}\n"
+  echo -e "${GREEN}✓ Stack created${NC}"
+}
+
+main "$@"

package/scripts/tooling/verify.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} canon tooling verify <stack> [options]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    --keep       ${GREY}# Keep tmp dir after run for inspection${NC}"
+  echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  Scaffolds <stack> into .claude/.tmp/verify-<stack>/, syncs the full"
+  echo -e "${GREY}│${NC}  layer chain, and runs check + test:e2e + screenshot."
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+
+read_manifest_field() {
+  local toml="$1"
+  local section="$2"
+  local field="$3"
+  awk -v s="$section" -v f="$field" '
+    $0 == "[" s "]" { in_section = 1; next }
+    in_section && /^\[/ { exit }
+    in_section && match($0, "^" f "[[:space:]]*=") {
+      val = substr($0, RLENGTH + 1)
+      sub(/^[[:space:]]+/, "", val)
+      sub(/^"/, "", val)
+      sub(/"$/, "", val)
+      print val
+      exit
+    }
+  ' "$toml"
+}
+
+run_phase() {
+  local name="$1"
+  shift
+  log_step "$name"
+  if "$@" >/tmp/verify-phase.log 2>&1; then
+    log_info "$name passed"
+    RESULTS+=("$name:pass")
+    return 0
+  fi
+  log_warn "$name failed"
+  tail -20 /tmp/verify-phase.log >&2
+  RESULTS+=("$name:fail")
+  FAILED=1
+  return 1
+}
+
+main() {
+  local stack=""
+  local keep=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+    -h | --help) show_help ;;
+    --keep)
+      keep=1
+      shift
+      ;;
+    -*)
+      log_error "Unknown option: $1"
+      ;;
+    *)
+      if [ -z "$stack" ]; then
+        stack="$1"
+        shift
+      else
+        log_error "Unexpected argument: $1"
+      fi
+      ;;
+    esac
+  done
+
+  [ -z "$stack" ] && log_error "Stack required. See --help."
+
+  if is_tooling_stack_excluded "$stack"; then
+    log_error "Stack '$stack' is excluded from tooling."
+  fi
+
+  local manifest="$PROJECT_ROOT/tooling/$stack/manifest.toml"
+  [ ! -f "$manifest" ] && log_error "No manifest at $manifest"
+
+  local scaffold
+  scaffold=$(read_manifest_field "$manifest" "stack" "scaffold")
+  [ -z "$scaffold" ] && log_error "Stack '$stack' has no scaffold command in manifest."
+
+  local prepare
+  prepare=$(read_manifest_field "$manifest" "verify" "prepare")
+
+  open_timeline "canon tooling verify $stack"
+  trap close_timeline EXIT
+
+  local tmp_root="$PROJECT_ROOT/.claude/.tmp"
+  local tmp_dir="$tmp_root/verify-$stack"
+
+  mkdir -p "$tmp_root"
+  rm -rf "$tmp_dir"
+
+  local project_name="verify-$stack"
+  local scaffold_cmd="${scaffold//\{\{name\}\}/$project_name}"
+
+  RESULTS=()
+  FAILED=0
+
+  log_step "Scaffolding $stack"
+  (cd "$tmp_root" && eval "$scaffold_cmd") >/tmp/verify-scaffold.log 2>&1 || {
+    log_warn "Scaffold failed"
+    tail -20 /tmp/verify-scaffold.log >&2
+    FAILED=1
+  }
+
+  if [ ! -d "$tmp_dir" ]; then
+    log_error "Scaffold did not produce $tmp_dir"
+  fi
+
+  (cd "$tmp_dir" && git init -q && git add . && git commit -m "chore: verify scaffold" -q --no-verify)
+
+  if [ -n "$prepare" ]; then
+    run_phase "Prepare" bash -c "cd '$tmp_dir' && $prepare"
+  fi
+
+  run_phase "Sync" bash -c "cd '$tmp_dir' && CANON_NON_INTERACTIVE=1 canon tooling sync $stack . --write"
+
+  if [ -f "$tmp_dir/package.json" ]; then
+    run_phase "lint:fix" bash -c "cd '$tmp_dir' && bun run lint:fix"
+    run_phase "check" bash -c "cd '$tmp_dir' && bun run check"
+
+    if grep -q '"test:e2e"' "$tmp_dir/package.json"; then
+      run_phase "test:e2e" bash -c "cd '$tmp_dir' && bun run test:e2e"
+    fi
+
+    if grep -q '"screenshot"' "$tmp_dir/package.json"; then
+      if run_phase "screenshot" bash -c "cd '$tmp_dir' && timeout 60 bun run screenshot"; then
+        local shots
+        shots=$(find "$tmp_dir/screenshots" -type f -name '*.png' 2>/dev/null | wc -l)
+        if [ "$shots" -eq 0 ]; then
+          log_warn "screenshot produced no png files"
+          RESULTS+=("screenshot-artifacts:fail")
+          FAILED=1
+        else
+          RESULTS+=("screenshot-artifacts:pass")
+        fi
+      fi
+    fi
+  fi
+
+  log_step "Results"
+  for r in "${RESULTS[@]}"; do
+    local name="${r%:*}"
+    local status="${r##*:}"
+    if [ "$status" = "pass" ]; then
+      log_info "$name"
+    else
+      log_warn "$name"
+    fi
+  done
+
+  if [ "$keep" -eq 0 ] && [ "$FAILED" -eq 0 ]; then
+    rm -rf "$tmp_dir"
+  else
+    log_info "Kept $tmp_dir"
+  fi
+
+  if [ "$FAILED" -ne 0 ]; then
+    exit 1
+  fi
+}
+
+main "$@"

package/snippets/align.md

@@ -0,0 +1,12 @@
+Check alignment before acting, not after. State three lines, then proceed.
+
+- Outcome: what will be true when this is done
+- Scope: what this deliberately does not touch
+- Assumption: the one inference that would change the work if it is wrong
+
+Act without waiting, unless being wrong about the assumption wastes the work rather than costing an edit.
+
+- Three lines, not three paragraphs
+- Name the inference you are least sure of, not the safest one
+- Do not ask what the request already answers
+- Silence is agreement

package/snippets/claude/decision-memo.md

@@ -0,0 +1,39 @@
+Produce a decision memo for a research or should-we question. This is the decision-heavy counterpart to `claude-feature`, which plans a build. Write one file per independent concern under `.claude/plans/feature-<slug>.md`, or answer inline when the plan is small. Use the same plans folder as `claude-feature`.
+
+Read the current state from the code and docs before recommending. Do not assume it.
+
+Output this shape per memo:
+
+```markdown
+# <slug title>
+
+<the question in one or two lines>
+
+## Summary
+
+- <goal in one line>
+- <deliverables in one line>
+- <key tradeoff in one line>
+
+## Finding
+
+<what the current state actually is, from reading the code and docs>
+
+## Item A: <decision>
+
+**Current state.** <what exists today>
+
+**Recommendation.** <the pick, with the tradeoff in one sentence>
+
+**Options.** <the real alternatives, only when the choice is the user's to make>
+
+**Feasibility.** <what is not buildable as asked and why, omit when all options are buildable>
+
+**Questions.**
+
+1. <question>
+   - Suggested: <best-practice default derived from context>
+   - Answer:
+```
+
+Repeat the `## Item` block per decision. Keep chat to the file pointer plus the questions. Recommend, do not enumerate, unless the user's preference is the deciding factor.

package/snippets/claude/feature-recap.md

@@ -0,0 +1,19 @@
+Recap the implementation this session completed. Read the plan file referenced in the session (usually `.claude/plans/feature-<slug>.md`) and produce a verification block.
+
+Output this shape, nothing else:
+
+```markdown
+**Deliverable 1**: <name from the plan>
+
+- `path/to/file`: one-line reason
+
+**Deliverable 2**: <name from the plan>
+
+- `path/to/file`: one-line reason
+
+**Verified**: <what was smoke-tested or `Nothing tested in session.`>
+
+**Open**: <unresolved questions, deferred items, or `None.`>
+```
+
+Group files by deliverable, not by directory. Keep each line scannable. Do not restate the plan body.

package/snippets/claude/figma-steps.md

@@ -0,0 +1,24 @@
+Read the relevant spec from `.claude/DESIGN.md` and any other design files needed. Write step-by-step Figma instructions to produce the component exactly.
+
+For each step, specify:
+
+- The exact tool or keyboard shortcut to activate
+- Which panel or field to click
+- The exact value to enter
+
+When a step has multiple sub-actions or lists several items, use nested bullets instead of stacking them in one sentence.
+
+Cover in order:
+
+- Frame or group setup (dimensions, corner radius, fill)
+- Each layer or shape (type, size, position, fill, stroke)
+- Alignment and spacing rules
+- Export settings
+
+Throughout:
+
+- Use exact values from the spec
+- Do not restate design rationale
+- Use Title Case for all layer and frame names
+- Use Figma terminology throughout, not code or CSS equivalents
+- Reuse existing frames or components from the same Figma document by name instead of rebuilding from scratch

package/snippets/compact-summary.md

@@ -0,0 +1,5 @@
+Summarize the research or findings above into a compact, scannable block.
+
+- State the main takeaways directly
+- Skip background context the reader already has
+- Use short headings and tight bullets where multiple items exist

package/snippets/decision-help.md

@@ -0,0 +1,6 @@
+Apply senior-level judgment. Pick the best option from the discussion so far. State the pick in one sentence, then the reason and the main tradeoff in one or two sentences.
+
+- Minimal and necessary only
+- No nice-to-haves
+- No padding
+- No alternatives unless they change the recommendation

package/snippets/meta-prompt.md

@@ -0,0 +1,14 @@
+Turn the idea below into a production-grade system prompt.
+
+Give it a role of one to three lines, a constraints section, and an output format carrying a template plus one worked example. Add a validation checklist when the prompt involves multi-step logic, edge cases, or error handling. Omit that checklist for a single-purpose prompt.
+
+Group constraints under domain headings when they span two or more domains and total five or more. Use flat must-do and must-not-do lists otherwise. Keep dos and don'ts together under the topic they belong to.
+
+Use `{{DOUBLE_BRACES}}` for values the end user fills in at runtime.
+
+Constraints:
+
+- Use imperative voice. Write `Do X`, never `You should` or `Try to`.
+- Make every constraint verifiable from the output. Reject subjective qualifiers like `appropriate`, `concise`, or `well-structured`.
+- Match prompt length to task complexity. A single-purpose task gets a minimal prompt.
+- Never write `maybe`, `consider`, or `depending on`. Be definitive.

package/snippets/research-prompt.md

@@ -0,0 +1,7 @@
+Generate a self-contained research prompt for another AI chat. Include:
+
+- State what I am trying to do and why
+- List what I have already tried and the results
+- Specify questions that need answers
+
+Write it in first person. Assume the reader has no context from this session.

package/snippets/session-notes.md

@@ -0,0 +1,11 @@
+Write session notes for this conversation using this format:
+
+```markdown
+# Session notes: <topic>
+
+## <title>
+
+<what was decided and why>
+```
+
+Only include decisions made in this session. Output only the markdown block, nothing else.

package/snippets/snippets.toml

@@ -0,0 +1,5 @@
+[essentials]
+names = [
+    "align",
+    "decision-help",
+]

package/snippets/step-by-step.md

@@ -0,0 +1,10 @@
+Give me step-by-step instructions.
+
+For each step:
+
+- State what to do in one sentence.
+- Include the exact value, command, or input where precision matters.
+- Note any output to save or verify before moving on.
+- When the step has multiple sub-actions or lists several items, use nested bullets instead of stacking them in one sentence.
+
+Group related steps under a heading if the process has distinct phases. Flag any step that is irreversible or that blocks later steps.

package/snippets/web-research.md

@@ -0,0 +1,21 @@
+Search the web for the topic or question added after this snippet. Fetch the most relevant pages. Synthesize findings into a decision-ready block using this format:
+
+```markdown
+Topic: [what was researched]
+Recommendation: [one clear answer or choice]
+
+Options considered:
+
+- [Option A]: why considered, why chosen or rejected
+- [Option B]: why considered, why chosen or rejected
+
+Key constraints:
+
+- [constraint that shaped the decision]
+
+Sources:
+
+- [URL]: what it confirmed
+```
+
+Output only the block. Do not add commentary before or after it.