@erclx/aitk 0.57.0 → 0.59.0

package/standards/plan.md

@@ -0,0 +1,145 @@
+---
+title: Plan reference
+description: Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
+---
+
+# Plan reference
+
+Applies to a feature plan at `.claude/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
+
+The folder is gitignored and unbacked. Nothing recovers a deleted plan, which is why the archive step below is a move rather than a cleanup.
+
+## Scope
+
+Governs a feature plan under `.claude/plans/feature-<slug>.md`: the filename, the required sections, what each holds, the suggested-and-answer contract, and the lifecycle from the live folder to the archive.
+
+Does not govern:
+
+- One question measured in depth before anyone can plan against it: `groundwork.md`
+- A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- The task file a plan is linked from, and the origin line pointing back at it: `tasks.md`
+- The transform from a branch name to a slug: `slug.md`
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+- When a plan is written at all, and whether a short one goes to a file or to the conversation, which belong to the surface driving it
+
+## What a working plan looks like
+
+A plan works when a session holding none of the conversation that produced it can execute from the file alone:
+
+- What is being built, and which files does it change?
+- Which decisions are already settled, and which are still open?
+- For each open decision, what happens when nobody answers it?
+- What is likely to go wrong, and where does the work collide with something already in flight?
+
+A plan failing these is non-conforming even when it satisfies every shape rule below.
+
+## Filename and slug
+
+- Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
+- Write one concern per file. A request spanning two independent concerns takes two plans rather than one bundling both, since a bundled plan cannot be executed by two sessions or abandoned by half.
+- Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
+- Give the branch that executes the plan the same slug. A later surface finds the plan from the branch name and finds nothing when the two spellings differ.
+
+A plan carries no frontmatter. Its filename is the whole of its identity, so a folder of plans is read by name rather than by a generated catalog.
+
+## Sections
+
+The document opens with `# Feature: <short title>` and one paragraph stating what is being built and why now. The sections below follow in this order.
+
+| Section               | Holds                                                                     | Required      |
+| --------------------- | ------------------------------------------------------------------------- | ------------- |
+| `## Summary`          | three to five one-line bullets: the goal, the deliverables, the trade-off | Always        |
+| `**Constraints:**`    | durable rules the work must respect                                       | When supplied |
+| `**Files to touch:**` | each file with a one-line reason                                          | Always        |
+| `**Risks:**`          | conflicts, coupling, and the tricky spots                                 | Always        |
+| `**Questions:**`      | numbered open decisions, each with a suggestion and an answer slot        | Always        |
+
+- Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the four that follow are labels over lists rather than sections of prose.
+- A section written in the other spelling is still that section. `## Risks` and `**Risks:**` name one thing, and a plan carrying either has stated its risks, so neither reads as an omission. Write the table's form in a new plan and leave an existing plan's spelling alone.
+- Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
+- Aim `## Summary` at a person scanning the plan, not at the session executing it. The other sections carry what execution needs.
+- Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against. Lead with the path or lead with a label carrying the path, whichever reads better for the entry.
+- State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
+- Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
+
+### Constraints
+
+A constraint naming a surface to leave alone forbids two different acts, and it says which. A constraint carrying only the surface leaves the executing session to guess.
+
+- Forbid conforming that surface to whatever shape the change introduces. This is what a scope constraint means, and it keeps the branch from growing a second concern.
+- Never forbid retargeting a pointer the change breaks. A rename, a split, or a deletion that leaves a citation behind ships a dangling reference, so repairing it is required work rather than scope creep.
+- Decide both acts for every surface the constraint names. Carving the distinction out for one file and leaving its siblings under the bare wording ships one correct call beside one broken reference.
+
+### Risks
+
+- Name the collision rather than the category. A risk a reader cannot act on is padding.
+- Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
+
+## The suggested-and-answer contract
+
+Every question carries a `- Suggested:` line and an empty `- Answer:` slot below it.
+
+```markdown
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```
+
+- A blank `- Answer:` means accept the suggestion at execution time. That default is what makes the plan decision-ready in one pass, with no separate round to collect answers.
+- Never ship a question without a suggestion. A bare question defers the judgment the plan exists to supply, and it arrives at the executing session as a stop.
+- State the pick in one line with its reason or its main tradeoff. List an alternative only where it changes the pick.
+- Write `- Suggested: needs your call, <why>` where the answer turns on preference rather than on a technical default. Fabricating a default there hides an open question behind an accepted answer.
+- Never fill an `- Answer:` slot on behalf of the person who owns it. Recording the pick as the suggestion is what the suggestion line is for.
+- Answer in place when a question is settled in conversation, so the file and the decision do not disagree.
+
+This contract inverts the one an intake folder keeps, where an empty slot means unread and acceptance is typed out. A plan is written and read in one sitting with every question already surfaced, so silence is a usable default here and is not one there. Both files state the inversion, since a contract read on only one side of a boundary is the one that gets applied to the wrong document.
+
+## Lifecycle
+
+- Write the plan before implementation starts, and treat it as the scope of the run that executes it.
+- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
+- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current.
+- Move the plan to `.claude/plans-archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it.
+- Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
+
+## Anti-patterns
+
+- **The plan written before the measuring.** A subject that has to be measured before anyone can plan against it belongs in a measurement track, and every plan that skipped that step had to be superseded.
+- **The bundled plan.** Two concerns under one slug cannot be split later without rewriting both halves.
+- **The question with no suggestion.** It reads as thoroughness and lands as a blocked run.
+- **The answer filled in by the author.** A slot holding the writer's own pick destroys the only signal that anyone else agreed.
+- **The count carried in.** A figure quoted from an earlier session survives the change that invalidated it, and the scope built on it is quietly wrong.
+- **The plan deleted on ship.** The considered-and-dropped reasoning goes with it, and the next session re-proposes what this one rejected.
+
+## Template
+
+```markdown
+# Feature: <short title>
+
+<One paragraph on what is being built and why now.>
+
+## Summary
+
+- <one-line bullet covering the goal>
+- <one-line bullet covering the main deliverables>
+- <one-line bullet covering the key decision or trade-off>
+
+**Constraints:**
+
+- <durable rule the work must respect>
+
+**Files to touch:**
+
+- `<path/to/file>`: <reason>
+
+**Risks:**
+
+- <conflict, coupling, or tricky spot>
+
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```

package/standards/rule.md

@@ -33,6 +33,15 @@ Write both when both apply. A rule stating the directive and a skill stating how
 - Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`
 - `<n>` is a number in the subdirectory's band and `<slug>` is a one-to-three-word kebab topic
 - Scaffold a rule with a number that collides with neither the project's rules nor any installed shared rule set
+- Give every rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
+
+## Two sources numbering into one folder
+
+A shared rule set and a project's own rules land in the same installed folder and draw from the same band, so the two need a division or they collide. Divide the band by source rather than by topic: one source takes the top of each band and the other takes the gaps between the tens. A rule set that ships to targets should take the tens, since it is the source a project cannot renumber.
+
+The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks the division, so it holds only while both sources follow it.
+
+State the division where the rule sources are described, not in the rules themselves. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
 
 ## Frontmatter
 

package/standards/tasks.md

@@ -15,6 +15,7 @@ Governs the task board under `.claude/tasks/`: folder layout, filenames, frontma
 
 Does not govern:
 
+- The plan file a task cites, its sections, and its answer contract: `plan.md`
 - Phase-label format and which surfaces a label may appear on: `versioning.md`
 - Sequencing across versions and why the order is what it is: `roadmap.md`
 - Architectural reasoning that outlives a task: `architecture.md`

package/scripts/gov/list.sh

@@ -1,234 +0,0 @@
-#!/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"
-
-STACKS_DIR="$PROJECT_ROOT/governance/stacks"
-RULES_DIR="$PROJECT_ROOT/governance/rules"
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} aitk gov list [options]"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    --stacks    ${GREY}# Only list stacks${NC}"
-  echo -e "${GREY}│${NC}    --rules     ${GREY}# Only list rules${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
-}
-
-read_frontmatter_field() {
-  local file="$1"
-  local field="$2"
-  awk -v f="$field" '
-    BEGIN { fm = 0 }
-    /^---$/ { fm++; if (fm > 1) exit; next }
-    fm == 1 {
-      if (match($0, "^" f ":")) {
-        val = substr($0, RLENGTH + 1)
-        sub(/^[[:space:]]+/, "", val)
-        sub(/^[\x27"]/, "", val)
-        sub(/[\x27"]$/, "", val)
-        print val
-        exit
-      }
-    }
-  ' "$file"
-}
-
-read_frontmatter_paths() {
-  local file="$1"
-  awk '
-    BEGIN { fm = 0; in_paths = 0 }
-    /^---$/ { fm++; if (fm > 1) exit; next }
-    fm == 1 {
-      if (in_paths) {
-        if (match($0, /^[[:space:]]*-[[:space:]]+/)) {
-          val = substr($0, RLENGTH + 1)
-          sub(/^[\x27"]/, "", val)
-          sub(/[\x27"]$/, "", val)
-          print val
-          next
-        }
-        in_paths = 0
-      }
-      if ($0 == "paths:") { in_paths = 1 }
-    }
-  ' "$file"
-}
-
-rule_domain() {
-  local file="$1"
-  local rel="${file#"$RULES_DIR"/}"
-  echo "${rel%%/*}"
-}
-
-stack_rules_array() {
-  local toml="$1"
-  grep -oE '"[0-9]{3}-[a-z0-9-]+"' "$toml" | sed 's/"//g'
-}
-
-json_escape() {
-  local s="$1"
-  s="${s//\\/\\\\}"
-  s="${s//\"/\\\"}"
-  printf '%s' "$s"
-}
-
-list_stacks_text() {
-  log_step "Stacks"
-  local toml
-  for toml in "$STACKS_DIR"/*.toml; do
-    local name
-    name=$(basename "$toml" .toml)
-    local extends
-    extends=$(grep '^extends' "$toml" | cut -d'"' -f2)
-    local rule_count
-    rule_count=$(stack_rules_array "$toml" | wc -l)
-    if [ -n "$extends" ]; then
-      log_info "$name (extends: $extends, $rule_count rules)"
-    else
-      log_info "$name ($rule_count rules)"
-    fi
-  done
-}
-
-list_rules_text() {
-  log_step "Rules"
-  local file
-  while IFS= read -r file; do
-    local name
-    name=$(basename "$file" .md)
-    local domain
-    domain=$(rule_domain "$file")
-    local desc
-    desc=$(read_frontmatter_field "$file" "description")
-    log_info "$name [$domain] $desc"
-  done < <(find "$RULES_DIR" -type f -name "*.md" | sort)
-}
-
-list_stacks_json() {
-  local first=1
-  local toml
-  printf '['
-  for toml in "$STACKS_DIR"/*.toml; do
-    local name
-    name=$(basename "$toml" .toml)
-    local extends
-    extends=$(grep '^extends' "$toml" | cut -d'"' -f2)
-    local rules_json="["
-    local first_rule=1
-    local rule
-    while IFS= read -r rule; do
-      [ -z "$rule" ] && continue
-      if [ "$first_rule" -eq 0 ]; then
-        rules_json+=","
-      fi
-      rules_json+="\"$rule\""
-      first_rule=0
-    done < <(stack_rules_array "$toml")
-    rules_json+="]"
-    if [ "$first" -eq 0 ]; then
-      printf ','
-    fi
-    if [ -n "$extends" ]; then
-      printf '{"name":"%s","extends":"%s","rules":%s}' "$name" "$extends" "$rules_json"
-    else
-      printf '{"name":"%s","extends":null,"rules":%s}' "$name" "$rules_json"
-    fi
-    first=0
-  done
-  printf ']'
-}
-
-list_rules_json() {
-  local first=1
-  local file
-  printf '['
-  while IFS= read -r file; do
-    local name
-    name=$(basename "$file" .md)
-    local domain
-    domain=$(rule_domain "$file")
-    local desc
-    desc=$(read_frontmatter_field "$file" "description")
-
-    local paths_json="null"
-    local paths_collected=()
-    while IFS= read -r p; do
-      [ -n "$p" ] && paths_collected+=("$p")
-    done < <(read_frontmatter_paths "$file")
-    if [ "${#paths_collected[@]}" -gt 0 ]; then
-      paths_json="["
-      local first_p=1
-      local p
-      for p in "${paths_collected[@]}"; do
-        [ "$first_p" -eq 0 ] && paths_json+=","
-        paths_json+="\"$(json_escape "$p")\""
-        first_p=0
-      done
-      paths_json+="]"
-    fi
-
-    if [ "$first" -eq 0 ]; then
-      printf ','
-    fi
-    printf '{"name":"%s","domain":"%s","description":"%s","paths":%s}' \
-      "$name" "$domain" "$(json_escape "$desc")" "$paths_json"
-    first=0
-  done < <(find "$RULES_DIR" -type f -name "*.md" | sort)
-  printf ']'
-}
-
-main() {
-  local show_stacks=1
-  local show_rules=1
-  local json=0
-
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-    -h | --help) show_help ;;
-    --stacks)
-      show_rules=0
-      shift
-      ;;
-    --rules)
-      show_stacks=0
-      shift
-      ;;
-    --json)
-      json=1
-      shift
-      ;;
-    *) log_error "Unknown option: $1" ;;
-    esac
-  done
-
-  trap close_timeline EXIT
-
-  if [ "$json" -eq 1 ]; then
-    printf '{'
-    if [ "$show_stacks" -eq 1 ]; then
-      printf '"stacks":'
-      list_stacks_json
-      [ "$show_rules" -eq 1 ] && printf ','
-    fi
-    if [ "$show_rules" -eq 1 ]; then
-      printf '"rules":'
-      list_rules_json
-    fi
-    printf '}\n'
-    exit 0
-  fi
-
-  [ "$show_stacks" -eq 1 ] && list_stacks_text
-  [ "$show_rules" -eq 1 ] && list_rules_text
-}
-
-main "$@"