@erclx/aitk 1.6.0 → 1.7.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/records.md

@@ -110,7 +110,7 @@ aitk records push --json
 aitk records pull
 ```
 
-The backed folders are `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `review-archive`, `task-archive`, `tasks`, and `teach`, all under `.claude/`. They are the gitignored Claude group minus `.claude/.tmp`, which is deletable without loss, and `.claude/worktrees/`, whose contents belong to the project repository already. The list is a constant rather than configuration, matching the four folder names `validate` hardcodes.
+The backed folders are `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `review-archive`, `task-archive`, `tasks`, and `teach`, all under `.claude/`. They are the Claude ignore group the claude manifest ships, minus three entries: `.claude/.tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.claude/.records.git/`, which is the history the other ten are pushed into. The list is a constant rather than configuration, matching the four folder names `validate` hardcodes.
 
 Records are gitignored by design, so the history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the ten folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/check-color-source.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+SCRIPTS_ROOT="$PROJECT_ROOT/scripts"
+PALETTE_SOURCE="$SCRIPTS_ROOT/lib/ui.sh"
+
+# `find` writes to stderr and returns non-zero for a missing root, inside a
+# process substitution whose status nothing reads. Without this the walk covers
+# nothing and the check reports the tree clean having never measured it.
+if [ ! -f "$PALETTE_SOURCE" ]; then
+  echo "No palette source at ${PALETTE_SOURCE#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
+  exit 1
+fi
+
+# Any SGR sequence in either spelling. The cursor and erase sequences an
+# interactive prompt writes end in a letter instead, and they run only where a
+# terminal already exists, so they are not what this measures.
+SGR='\\(033|e|x1b)\[[0-9;]*m'
+
+# Sixteen copies of one decision is what made color impossible to turn off on
+# the TypeScript side. A rule nothing enforces rebuilds them the next time a
+# script wants grey, so the escape lives in the shared library and every other
+# script reads the palette that library derives for its stream.
+offenders=""
+while IFS= read -r file; do
+  [ "$file" = "$PALETTE_SOURCE" ] && continue
+  if grep -qE "$SGR" "$file"; then
+    offenders="$offenders  ${file#"$PROJECT_ROOT/"}"$'\n'
+  fi
+done < <(find "$SCRIPTS_ROOT" -type f -name '*.sh')
+
+if [ -n "$offenders" ]; then
+  echo "A color escape is defined outside the shared library:" >&2
+  printf '%s' "$offenders" >&2
+  echo "Source scripts/lib/ui.sh and read its palette, so one answer covers every writer." >&2
+  exit 1
+fi

package/scripts/core/snapshot.sh

@@ -2,19 +2,13 @@
 set -e
 set -o pipefail
 
-GREEN='\033[0;32m'
-RED='\033[0;31m'
-WHITE='\033[1;37m'
-GREY='\033[0;90m'
-NC='\033[0m'
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
-NESTED="${VERIFY_NESTED:-false}"
+# shellcheck source=/dev/null
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
 
-log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
-log_error() {
-  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
-  exit 1
-}
+NESTED="${VERIFY_NESTED:-false}"
 
 OUTPUT_FILE=".claude/.tmp/project/PROJECT-SNAPSHOT.md"
 
@@ -117,15 +111,23 @@ write_snapshot() {
 main() {
   check_dependencies
 
-  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+  if [ "$NESTED" = false ]; then open_timeline; fi
 
-  echo -e "${GREY}├${NC} ${WHITE}Snapshot${NC}"
+  log_step "Snapshot"
   write_snapshot
   log_info "Written to $OUTPUT_FILE"
 
+  # The whole frame goes to stderr, since the run writes its document to a file
+  # and leaves stdout carrying nothing. Edges on stdout with the body on stderr
+  # would capture as a frame with no body inside it.
   if [ "$NESTED" = false ]; then
-    echo -e "${GREY}└${NC}\n"
-    echo -e "${GREEN}✓ Snapshot complete${NC}"
+    close_timeline
+    # All six are declared to scope what `set_palette` assigns, so the four this
+    # line never spells stay out of the globals a sourcing script reads.
+    # shellcheck disable=SC2034
+    local GREEN RED YELLOW WHITE GREY NC
+    set_palette 2
+    echo -e "\n${GREEN}✓ Snapshot complete${NC}" >&2
   fi
 }
 

package/scripts/core/verify.sh

@@ -595,6 +595,7 @@ main() {
   log_step "Shell"
   if has_changed '\.sh$|^package\.json$'; then
     run_check "bun run check:shell" "Shell check failed"
+    run_check "bash $PROJECT_ROOT/scripts/core/check-color-source.sh" "A color escape is defined outside scripts/lib/ui.sh."
     log_info "Shell check passed"
   else
     log_info "Skipped, no shell changes"

package/scripts/lib/ui.sh

@@ -12,26 +12,85 @@ fi
 # shellcheck source=/dev/null
 source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/sandbox-path.sh"
 
-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_warn() { echo -e "${GREY}│${NC} ${YELLOW}!${NC} $1" >&2; }
+# `NO_COLOR` follows the published convention, where any non-empty value turns
+# color off whatever the value says.
+supports_color() {
+  [ -z "${NO_COLOR:-}" ] && [ -t "$1" ]
+}
+
+# Assigns the six palette names for one file descriptor. The blank palette keeps
+# every frame character and drops only the escapes, so a captured run still
+# reads as one block.
+#
+# Bash returns a string and nothing richer, so the palette arrives through the
+# caller's own scope. A writer declaring all six `local` before calling this
+# keeps the assignment to itself, which is what leaves the source-time answer
+# below standing for anything that sources this file.
+set_palette() {
+  if supports_color "$1"; then
+    GREEN='\033[0;32m'
+    RED='\033[0;31m'
+    YELLOW='\033[0;33m'
+    WHITE='\033[1;37m'
+    GREY='\033[0;90m'
+    NC='\033[0m'
+  else
+    GREEN=''
+    RED=''
+    YELLOW=''
+    WHITE=''
+    GREY=''
+    NC=''
+  fi
+}
+
+# Every writer below frames to stderr and asks about that stream at write time,
+# so no answer is frozen before a caller's redirect is in place. This one answers
+# for stdout instead, because it is read by a sourcing script writing its own
+# frame with a bare `echo`, and that is the stream a bare `echo` reaches.
+set_palette 1
+
+log_info() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
+  echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2
+}
+log_warn() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
+  echo -e "${GREY}│${NC} ${YELLOW}!${NC} $1" >&2
+}
 log_error() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   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; }
+log_step() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
+  echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2
+}
+log_add() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
+  echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2
+}
+log_rem() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
+  echo -e "${GREY}│${NC} ${RED}-${NC} $1" >&2
+}
 
-pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line" >&2; done; }
+pipe_output() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
+  while IFS= read -r line; do echo -e "${GREY}│${NC}  $line" >&2; done
+}
 
 open_timeline() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   echo -e "${GREY}┌${NC}" >&2
   if [ -n "${1:-}" ]; then
     echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
@@ -39,6 +98,8 @@ open_timeline() {
 }
 
 close_timeline() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   echo -e "${GREY}└${NC}" >&2
 }
 
@@ -52,6 +113,8 @@ guard_root() {
 }
 
 require_project_root() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   local sandbox
   sandbox="$(resolve_sandbox_dir)"
   if [[ "$PWD" == "$sandbox" || "$PWD" == "$sandbox"/* ]]; then
@@ -65,6 +128,8 @@ require_project_root() {
 }
 
 ask() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   local prompt_text=$1
   local var_name=$2
   local default_val=$3
@@ -107,6 +172,8 @@ ask() {
 }
 
 select_or_route_scenario() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   local prompt_text=$1
   shift
   local options=("$@")
@@ -122,6 +189,8 @@ select_or_route_scenario() {
 }
 
 select_option() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   local prompt_text=$1
   shift
   local options=("$@")

package/scripts/manage-sandbox.sh

@@ -320,6 +320,8 @@ execute_sandbox_and_commit() {
 }
 
 finalize_sandbox_run() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   trap - EXIT
   close_timeline
   echo "" >&2
@@ -327,6 +329,8 @@ finalize_sandbox_run() {
 }
 
 cmd_clean() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   log_step "Removing sandbox"
   rm -rf "$SANDBOX"
   log_rem "$SANDBOX"
@@ -337,6 +341,8 @@ cmd_clean() {
 }
 
 reset_sandbox() {
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
   if [ ! -d "$SANDBOX/.git" ]; then
     log_error "No sandbox found. Run \`aitk sandbox\` first."
   fi

package/scripts/tooling/ref.sh

@@ -91,6 +91,12 @@ main() {
   local stack="$1"
   local target="${2:-.}"
 
+  # Every frame below goes to stderr, so it asks about that stream rather than
+  # reading the source-time answer, which is for stdout and is what `show_help`
+  # above wants. Declared after the help branch so that call keeps it.
+  local GREEN RED YELLOW WHITE GREY NC
+  set_palette 2
+
   echo -e "${GREY}┌${NC}" >&2
   echo -e "${GREY}│${NC} ${WHITE}aitk tooling ref${NC}" >&2
 

package/src/records/backup.ts

@@ -5,10 +5,17 @@ import { gitEnv } from '@/git-env'
 
 /**
  * The folders a backup carries, relative to `.claude/`. They are the `# Claude`
- * group in `.gitignore` minus `.claude/.tmp`, which is defined as deletable
- * without loss, and `.claude/worktrees/`, whose contents belong to the
- * enclosing repository already. The list is spelled out rather than read off
- * that group so adding an ignore entry cannot silently enlarge the payload.
+ * group the claude manifest ships, minus three: `.claude/.tmp`, which is
+ * defined as deletable without loss, `.claude/worktrees/`, whose contents
+ * belong to the enclosing repository already, and `.claude/.records.git/`,
+ * which is the history the other ten are pushed into. The list is spelled out
+ * rather than read off that group so adding an ignore entry cannot silently
+ * enlarge the payload.
+ *
+ * The manifest group is the one this reads rather than the enclosing
+ * repository's own `.gitignore`, which spreads the same entries across two
+ * headers and carries `.claude/README.md` that no target receives. Subtracting
+ * three from that file instead yields eleven names against this list of ten.
  *
  * `RECORD_KINDS` in `validate.ts` overlaps this on five names and carries one
  * more that no backup reaches. The two lists differ on purpose: one is what a

package/tooling/claude/manifest.toml

@@ -8,4 +8,4 @@ runtime = ""
 scaffold = ""
 
 [gitignore]
-"# Claude" = [".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/plans-archive/", ".claude/review/", ".claude/review-archive/", ".claude/task-archive/", ".claude/worktrees/", ".claude/tasks/"]
+"# Claude" = [".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/plans-archive/", ".claude/review/", ".claude/review-archive/", ".claude/task-archive/", ".claude/worktrees/", ".claude/tasks/", ".claude/teach/"]

package/tooling/claude/reference.md

@@ -50,7 +50,7 @@ A project installed before the diagram surface became a folder still holds `.cla
 
 ## Gitignore
 
-- `# Claude`: `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/plans-archive/`, `.claude/review/`, `.claude/review-archive/`, `.claude/task-archive/`, `.claude/worktrees/`, `.claude/tasks/`
+- `# Claude`: `.claude/.records.git/`, `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/plans-archive/`, `.claude/review/`, `.claude/review-archive/`, `.claude/task-archive/`, `.claude/worktrees/`, `.claude/tasks/`, `.claude/teach/`
 
 ## CLI