@friedbotstudio/create-baseline 0.2.1 → 0.3.0

package/obj/template/.claude/hooks/lib/common.mjs

@@ -0,0 +1,283 @@
+// Shared helpers for baseline Claude Code hook scripts (JS port pilot).
+// Imported by .mjs hooks in .claude/hooks/. Bash hooks still source lib/common.sh.
+//
+// Contract:
+//   - Hooks receive a JSON payload on stdin (the Claude Code hook event).
+//   - Hooks emit JSON to stdout for structured decisions, or exit non-zero with
+//     a stderr message to block/warn.
+//   - All hooks must be resilient to a missing/invalid project.json.
+//
+// Behavior is preserved verbatim from lib/common.sh. The one addition is
+// matchAnyGlob — needed by git_commit_guard.mjs for branch policy.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, appendFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+
+export const CLAUDE_PROJECT_ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+export const CLAUDE_DOTDIR = join(CLAUDE_PROJECT_ROOT, '.claude');
+export const PROJECT_JSON = join(CLAUDE_DOTDIR, 'project.json');
+export const STATE_DIR = join(CLAUDE_DOTDIR, 'state');
+export const LOG_DIR = join(STATE_DIR, 'logs');
+
+try { mkdirSync(STATE_DIR, { recursive: true }); } catch {}
+try { mkdirSync(LOG_DIR, { recursive: true }); } catch {}
+
+// Consent-gate marker file paths — written ONLY by consent_gate_grant.mjs
+// (UserPromptSubmit), read by the gate guards. Hooks reference these constants
+// rather than literal paths so a rename is one-line.
+export const CONSENT_MARKER_SPEC   = join(STATE_DIR, '.spec_approval_grant');
+export const CONSENT_MARKER_SWARM  = join(STATE_DIR, '.swarm_approval_grant');
+export const CONSENT_MARKER_COMMIT = join(STATE_DIR, '.commit_consent_grant');
+export const CONSENT_MARKER_PUSH   = join(STATE_DIR, '.push_consent_grant');
+export const CONSENT_MARKER_SPEC_REL   = '.claude/state/.spec_approval_grant';
+export const CONSENT_MARKER_SWARM_REL  = '.claude/state/.swarm_approval_grant';
+export const CONSENT_MARKER_COMMIT_REL = '.claude/state/.commit_consent_grant';
+export const CONSENT_MARKER_PUSH_REL   = '.claude/state/.push_consent_grant';
+
+// Read the raw hook JSON payload from stdin. Returns a plain object (empty on parse error).
+export async function readPayload() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString('utf8');
+  if (!raw.trim()) return {};
+  try { return JSON.parse(raw); } catch { return {}; }
+}
+
+function dottedLookup(obj, path) {
+  if (obj == null) return undefined;
+  let cur = obj;
+  for (const part of String(path).replace(/^\.+|\.+$/g, '').split('.')) {
+    if (part === '') continue;
+    if (cur && typeof cur === 'object' && !Array.isArray(cur) && part in cur) {
+      cur = cur[part];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+// Extract a field from the hook payload using a dotted path.
+// Usage: payloadGet(payload, '.tool_input.command')
+export function payloadGet(payload, path) {
+  return dottedLookup(payload, path);
+}
+
+// Lazily-loaded project.json cache.
+let _projectJsonCache;
+let _projectJsonLoaded = false;
+function loadProjectJson() {
+  if (_projectJsonLoaded) return _projectJsonCache;
+  _projectJsonLoaded = true;
+  try {
+    _projectJsonCache = JSON.parse(readFileSync(PROJECT_JSON, 'utf8'));
+  } catch {
+    _projectJsonCache = undefined;
+  }
+  return _projectJsonCache;
+}
+
+// Read a field from .claude/project.json at a dotted path.
+// Returns undefined if project.json or the key is missing.
+export function projectGet(path) {
+  return dottedLookup(loadProjectJson(), path);
+}
+
+// Emit a structured block decision (PreToolUse). Prints JSON to stdout, exits 0.
+export function emitBlock(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: String(reason),
+    },
+  };
+  process.stdout.write(JSON.stringify(out) + '\n');
+  process.exit(0);
+}
+
+// Emit a structured ask decision.
+export function emitAsk(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'ask',
+      permissionDecisionReason: String(reason),
+    },
+  };
+  process.stdout.write(JSON.stringify(out) + '\n');
+  process.exit(0);
+}
+
+// Emit allow (no-op decision). Equivalent to exit 0 with no output.
+export function emitAllow() {
+  process.exit(0);
+}
+
+// Informational message (stderr, non-blocking).
+export function emitInfo(msg) {
+  process.stderr.write(String(msg) + '\n');
+}
+
+// Append a line to a hook-specific log. Best-effort, never throws.
+export function logLine(hook, msg) {
+  try {
+    const ts = new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+    appendFileSync(join(LOG_DIR, `${hook}.log`), `${ts}  ${msg}\n`);
+  } catch {}
+}
+
+// Canonicalize a filepath and make it relative to CLAUDE_PROJECT_ROOT.
+// Lexical only — does NOT resolve symlinks (matches the bash helper's
+// deliberate choice; symlink-swap defense is a separate hardening).
+// Returns the project-relative canonical path, or an absolute canonical
+// path if the input escapes the root, or '' if input equals the root.
+export function canonicalRel(filepath) {
+  if (!filepath) return '';
+  const norm = resolve(normalize(filepath));
+  const normRoot = resolve(normalize(CLAUDE_PROJECT_ROOT));
+  if (norm === normRoot) return '';
+  if (norm.startsWith(normRoot + sep)) return norm.slice(normRoot.length + 1);
+  return norm;
+}
+
+// Reduce a user-typed approval arg (bare slug, filename, or path) to a slug.
+//   docs/specs/foo.md  -> foo
+//   foo.md             -> foo
+//   foo                -> foo
+export function canonicalSlug(s) {
+  if (s == null) return '';
+  let base = String(s);
+  const slash = base.lastIndexOf('/');
+  if (slash >= 0) base = base.slice(slash + 1);
+  if (base.endsWith('.md')) base = base.slice(0, -3);
+  return base;
+}
+
+// Atomic marker write: temp file + rename. Returns true on success.
+export function writeMarkerAtomic(markerPath, ...lines) {
+  const tmp = `${markerPath}.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join('\n') + '\n');
+    renameSync(tmp, markerPath);
+    return true;
+  } catch {
+    try { unlinkSync(tmp); } catch {}
+    return false;
+  }
+}
+
+// Block Claude from writing a consent-marker file via Write/Edit/MultiEdit.
+// The marker's unforgeability is what makes consent gates structural — only
+// consent_gate_grant (UserPromptSubmit, outside Claude's tool boundary) may
+// produce it. Calls emitBlock (which exits) on match.
+//
+// Args: rel — the relative path being written; markerRel — the marker's REL
+// constant; gateLabel — human label for the error message ("Git Commit Guard");
+// cmdHint — the user command users should run ("/grant-commit").
+export function blockMarkerSelfWrite(rel, markerRel, gateLabel, cmdHint) {
+  const hookLog = gateLabel.toLowerCase().replace(/\s+/g, '_');
+  if (rel === markerRel) {
+    logLine(hookLog, `BLOCKED direct write to consent marker: ${rel}`);
+    emitBlock(`${gateLabel}: '${rel}' is a consent marker written by the consent_gate_grant UserPromptSubmit hook in response to \`${cmdHint}\`. Claude is not permitted to create or edit this marker — its unforgeability is what makes the gate structurally enforced.`);
+  }
+}
+
+// Validate a consent marker (freshness + optional slug match) and consume it.
+// emitBlocks (exits) on any failure; returns on success after deleting the marker.
+// TTL comes from .consent.gate_marker_ttl_seconds (default 120).
+//
+// Marker shape:
+//   - With expectedSlug:  line 1 = slug, line 2 = epoch.
+//   - Epoch-only:         line 1 = epoch.
+export function validateConsentMarker(markerPath, gateLabel, cmdHint, expectedSlug = '') {
+  const hookLog = gateLabel.toLowerCase().replace(/\s+/g, '_');
+  let ttl = projectGet('.consent.gate_marker_ttl_seconds');
+  if (typeof ttl !== 'number' || !Number.isFinite(ttl)) ttl = 120;
+
+  if (!existsSync(markerPath)) {
+    logLine(hookLog, `BLOCKED no marker: ${markerPath}`);
+    emitBlock(`${gateLabel}: requires a fresh consent marker at ${markerPath}. The marker is produced by the consent_gate_grant hook when the user runs \`${cmdHint}\` — Claude cannot create it.`);
+  }
+
+  let markerSlug = '';
+  let markerEpoch;
+  try {
+    const text = readFileSync(markerPath, 'utf8');
+    const lines = text.split(/\r?\n/);
+    if (expectedSlug) {
+      markerSlug = (lines[0] ?? '').trim();
+      markerEpoch = (lines[1] ?? '').trim();
+    } else {
+      markerEpoch = (lines[0] ?? '').trim();
+    }
+  } catch {
+    markerEpoch = '';
+  }
+
+  if (!/^\d+$/.test(markerEpoch)) {
+    logLine(hookLog, `BLOCKED malformed marker: ${markerPath}`);
+    emitBlock(`${gateLabel}: marker at ${markerPath} is malformed. Ask the user to re-run \`${cmdHint}\`.`);
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const age = now - parseInt(markerEpoch, 10);
+  if (age > ttl) {
+    logLine(hookLog, `BLOCKED marker expired age=${age}s ttl=${ttl}s`);
+    try { unlinkSync(markerPath); } catch {}
+    emitBlock(`${gateLabel}: consent marker expired (${age}s old, TTL ${ttl}s). Ask the user to re-run \`${cmdHint}\`.`);
+  }
+
+  if (expectedSlug && markerSlug !== expectedSlug) {
+    logLine(hookLog, `BLOCKED slug mismatch marker=${markerSlug} expected=${expectedSlug}`);
+    emitBlock(`${gateLabel}: marker slug (${markerSlug}) does not match expected (${expectedSlug}). Ask the user to re-run \`${cmdHint}\` with the correct argument.`);
+  }
+
+  logLine(hookLog, `ALLOWED marker=${markerPath} age=${age}s slug=${markerSlug || 'N/A'}`);
+  try { unlinkSync(markerPath); } catch {}
+}
+
+// Hand-rolled shell-glob → RegExp matcher. Used for git.protected_branches.
+// `*` matches anything except `/`; `**` matches anything including `/`;
+// `?` matches a single non-`/` char; `[...]` is a character class.
+// Returns false if globs is null/undefined/empty.
+export function matchAnyGlob(name, globs) {
+  if (!Array.isArray(globs) || globs.length === 0) return false;
+  for (const glob of globs) {
+    if (typeof glob !== 'string' || glob === '') continue;
+    if (globToRegex(glob).test(name)) return true;
+  }
+  return false;
+}
+
+function globToRegex(glob) {
+  let pattern = '^';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        pattern += '.*';
+        i += 1;
+      } else {
+        pattern += '[^/]*';
+      }
+    } else if (c === '?') {
+      pattern += '[^/]';
+    } else if (c === '[') {
+      let j = i + 1;
+      while (j < glob.length && glob[j] !== ']') j++;
+      if (j >= glob.length) {
+        pattern += '\\[';
+      } else {
+        pattern += glob.slice(i, j + 1);
+        i = j;
+      }
+    } else if ('.+()^$|\\{}'.includes(c)) {
+      pattern += '\\' + c;
+    } else {
+      pattern += c;
+    }
+  }
+  pattern += '$';
+  return new RegExp(pattern);
+}

package/obj/template/.claude/hooks/lib/common.sh

@@ -229,7 +229,7 @@ else:
 PY
 }
 
-# Consent-gate marker file paths — written ONLY by consent_gate_grant.sh
+# Consent-gate marker file paths — written ONLY by consent_gate_grant.mjs
 # (UserPromptSubmit) when the user invokes the corresponding slash command,
 # read by the gate guards (PreToolUse) before allowing approval-token writes.
 # Hooks reference these constants instead of literal paths so a rename is a

package/obj/template/.claude/hooks/memory_session_start.sh

@@ -54,8 +54,9 @@ except Exception:
     head = ''
 
 # Files in canonical order. _pending.md handled separately.
-canonical = ['landmarks', 'libraries', 'decisions', 'landmines', 'conventions', 'pending-questions']
+canonical = ['landmarks', 'libraries', 'decisions', 'landmines', 'conventions', 'pending-questions', 'backlog']
 PENDING_FILE = 'pending-questions'
+STALE_EXEMPT_FILES = {'backlog'}
 STALE_COMMITS = 30
 STALE_DAYS = 30  # non-git fallback threshold
 
@@ -96,6 +97,8 @@ def _split_blocks(body):
 
 
 def _is_stale(block, name):
+    if name in STALE_EXEMPT_FILES:
+        return False
     closure_field = 'resolved-at' if name == PENDING_FILE else 'superseded-at'
     if _field(block, closure_field):
         return False
@@ -151,6 +154,10 @@ lines = [
 ]
 for name, n, stale, status in rows:
     lines.append(f'| `{name}.md` | {n} | {stale} | {status} |')
+# Phase 10.6: surface the _pending.md row in the index so K=0 / K>0 are
+# visible without the prose nag. The body content is gitignored; only the
+# count matters here.
+lines.append(f'| `_pending.md` | {pending_count} | — | ok |')
 
 if stale_records:
     stale_records.sort(key=lambda r: (r[2] or '', f'{r[0]}:{r[1]}'))
@@ -167,13 +174,20 @@ if stale_records:
 
 lines.append('')
 
-if pending_count > 0:
+# Phase 10.6 (memory-flush as workflow phase) downgraded the SessionStart nag to
+# debt-mode only: fire when _pending.md has unflushed candidates AND no active
+# workflow is on disk. During an active workflow, Phase 10.6 will handle them;
+# the nag would be redundant. On K=0, stay silent — the index table above already
+# shows the _pending.md row count.
+workflow_json = root / '.claude/state/workflow.json'
+active_workflow = workflow_json.is_file()
+
+if pending_count > 0 and not active_workflow:
+    plural = '' if pending_count == 1 else 's'
     lines.append(
-        f'**{pending_count} candidate{"" if pending_count == 1 else "s"} pending in `_pending.md`** — '
-        'run `/memory-flush` to review and commit keepers before starting workflow phases.'
+        f'**{pending_count} pending memory candidate{plural} carried over from a prior workflow** — '
+        'run `/memory-flush` to clear before starting new work.'
     )
-else:
-    lines.append('No pending memory candidates.')
 
 lines.append('')
 lines.append(

package/obj/template/.claude/hooks/memory_stop.sh

@@ -29,7 +29,7 @@ PENDING="$MEM_DIR/_pending.md"
 
 # Extract candidates with python; never fail the hook (it's advisory).
 TRANSCRIPT="$TRANSCRIPT" PENDING="$PENDING" python3 <<'PY' || true
-import json, os, re, sys, time
+import hashlib, json, os, re, sys, time
 from pathlib import Path
 from datetime import datetime, timezone
 
@@ -42,7 +42,7 @@ existing_keys = set(re.findall(r'(?m)^##\s+CANDIDATE:\s*(\S+)', existing))
 
 candidates = []  # (key, category, body_lines)
 
-# Source-dir prefixes that are interesting for landmark candidates.
+# --- Source-dir prefixes that are interesting for landmark candidates. -------
 SRC_PREFIXES = ('src/', 'lib/', 'app/', 'pkg/', 'internal/', 'cmd/', '.claude/hooks/', '.claude/skills/')
 SKIP_PREFIXES = ('.claude/memory/', '.claude/state/', 'docs/scout/', 'docs/research/', 'docs/intake/',
                  'docs/specs/', 'docs/brd/', 'docs/rca/', 'docs/security/', 'docs/archive/')
@@ -56,10 +56,112 @@ def is_source(path: str) -> bool:
         return True
     return False
 
+# --- Intent-extraction constants + helpers (backlog candidates). -------------
+# Anchored line-start patterns. USER patterns accept an optional Markdown
+# bullet prefix; ASSISTANT patterns require strict line-start to suppress
+# Claude's natural tendency to write narrative summaries containing trigger
+# phrases. Precision-favoring per the user constraint; mid-sentence matches
+# MUST NOT fire.
+_USER_BULLET = r'^(?:\s*[-*]\s*)?'
+_ASSISTANT_BULLET = r'^'
+_INTENT_TRIGGERS = [
+    r'TODO[:\s]',
+    r'next\s+we\s+(?:should|need\s+to|must)\b',
+    r"let'?s\s+also\b",
+    r'we\s+should\s+also\b',
+    r'backlog\s+this\b',
+    r'after\s+this(?:\s+lands)?\b',
+]
+USER_INTENT_PATTERNS = [re.compile(_USER_BULLET + t, re.I) for t in _INTENT_TRIGGERS]
+ASSISTANT_INTENT_PATTERNS = [re.compile(_ASSISTANT_BULLET + t, re.I) for t in _INTENT_TRIGGERS]
+
+# Stripped from the matched line before slug derivation so the slug captures
+# the *intent payload*, not the trigger phrase.
+TRIGGER_STRIP = re.compile(
+    r"^(?:\s*[-*]\s*)?"
+    r"(?:TODO[:\s]+"
+    r"|next\s+we\s+(?:should|need\s+to|must)\s+"
+    r"|let'?s\s+also\s+"
+    r"|we\s+should\s+also\s+"
+    r"|backlog\s+this[:\s]*"
+    r"|after\s+this(?:\s+lands)?[\s,]*)",
+    re.I,
+)
+
+NOISE_PREFIXES = ('<system-reminder>', '<command-name>', '<local-command-')
+MAX_INTENT_TEXT_LEN = 240
+
+
+def _extract_text_blocks(content):
+    """Walk a message content list and return trimmed text-block strings.
+    Mirrors lib/resume_writer.py:72-88."""
+    out = []
+    if isinstance(content, str):
+        if content.strip():
+            out.append(content.strip())
+        return out
+    if not isinstance(content, list):
+        return out
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        if block.get('type') == 'text':
+            t = block.get('text', '')
+            if isinstance(t, str) and t.strip():
+                out.append(t.strip())
+    return out
+
+
+def _filter_noise(text: str) -> bool:
+    """True when the text is hook-injected noise that must not produce candidates."""
+    head = text.lstrip()[:64]
+    return any(head.startswith(p) for p in NOISE_PREFIXES)
+
+
+def _iter_intent_matches(text: str, patterns):
+    """Yield each line of `text` whose start matches any of `patterns`."""
+    for line in text.splitlines():
+        for pat in patterns:
+            if pat.match(line):
+                yield line
+                break
+
+
+def _normalize_intent(line: str) -> str:
+    """Lowercase, whitespace-collapse, trigger-strip. Empty result = discard."""
+    stripped = TRIGGER_STRIP.sub('', line).strip()
+    if not stripped:
+        return ''
+    return re.sub(r'\s+', ' ', stripped).lower()
+
+
+def _slug_words(normalized: str, max_words: int = 8) -> str:
+    """Kebab-case slug from the first `max_words` ASCII-alphanumeric words."""
+    words = re.findall(r'[a-z0-9]+', normalized)
+    if not words:
+        return ''
+    return '-'.join(words[:max_words])
+
+
+def _derive_key(line: str):
+    """Return (key, normalized) where key = `<slug>-<4-char-sha256>` or
+    (None, '') if the line has no extractable intent payload."""
+    normalized = _normalize_intent(line)
+    if not normalized:
+        return None, ''
+    slug = _slug_words(normalized)
+    if not slug:
+        return None, ''
+    hsh = hashlib.sha256(normalized.encode('utf-8')).hexdigest()[:4]
+    return f'{slug}-{hsh}', normalized
+
+
 # Track per-path edit counts so we only candidate paths touched ≥1 time
 # (loose threshold; the curator decides what's worth keeping).
 path_touches = {}  # path -> count
 lib_queries = []  # list of dicts {library, topic}
+intent_candidates = []  # list of dicts {key, verbatim, role, source}
+seen_intent_keys = set()  # within-session dedup keyed on f'{key}::{source}'
 
 # Walk the transcript JSONL.
 try:
@@ -79,6 +181,7 @@ try:
             content = msg.get('content')
             if not isinstance(content, list):
                 continue
+            # tool_use blocks → landmark / library candidates.
             for block in content:
                 if not isinstance(block, dict):
                     continue
@@ -98,6 +201,36 @@ try:
                     topic = inp.get('topic') or inp.get('query') or ''
                     if lib:
                         lib_queries.append({'library': str(lib), 'topic': str(topic)[:80]})
+
+            # text blocks → backlog (intent) candidates. Errors here MUST NOT
+            # crash the hook — preserve the never-fail contract.
+            try:
+                role = msg.get('role') or (ev.get('role') if isinstance(ev, dict) else None)
+                if role in ('user', 'assistant'):
+                    patterns = USER_INTENT_PATTERNS if role == 'user' else ASSISTANT_INTENT_PATTERNS
+                    source_value = 'user-instruction' if role == 'user' else 'assistant-deferral'
+                    for text in _extract_text_blocks(content):
+                        if _filter_noise(text):
+                            continue
+                        for matched_line in _iter_intent_matches(text, patterns):
+                            key, normalized = _derive_key(matched_line)
+                            if not key:
+                                continue
+                            dedup_key = f'{key}::{source_value}'
+                            if dedup_key in seen_intent_keys:
+                                continue
+                            seen_intent_keys.add(dedup_key)
+                            verbatim = matched_line.strip()
+                            if len(verbatim) > MAX_INTENT_TEXT_LEN:
+                                verbatim = verbatim[:MAX_INTENT_TEXT_LEN].rstrip() + '…'
+                            intent_candidates.append({
+                                'key': key,
+                                'verbatim': verbatim,
+                                'role': role,
+                                'source': source_value,
+                            })
+            except Exception as e:
+                sys.stderr.write(f'memory_stop: intent extraction failed for one event: {e}\n')
 except Exception as e:
     sys.stderr.write(f'memory_stop: transcript walk failed: {e}\n')
 
@@ -145,6 +278,32 @@ for q in lib_queries:
     ]
     candidates.append((key, 'libraries', body))
 
+# Backlog (intent) candidates from user/assistant text blocks.
+workflow_slug = ''
+try:
+    wf_path = Path(os.environ.get('CLAUDE_PROJECT_DIR') or os.getcwd()) / '.claude/state/workflow.json'
+    if wf_path.is_file():
+        wf = json.loads(wf_path.read_text(encoding='utf-8'))
+        workflow_slug = wf.get('slug') or ''
+except Exception:
+    workflow_slug = ''
+
+for cand in intent_candidates:
+    key = cand['key']
+    full_key = f'backlog → {key}'
+    if full_key in existing_keys:
+        continue
+    body = [
+        f'## CANDIDATE: backlog → {key}',
+        f'- Intent: {cand["verbatim"]}',
+        f'- Role: {cand["role"]}',
+        f'- Source: {cand["source"]}',
+        f'- Context: {workflow_slug or "(no active workflow)"}',
+        f'- Emitted-at: {ts}',
+        '',
+    ]
+    candidates.append((full_key, 'backlog', body))
+
 # If nothing to add, exit cleanly.
 if not candidates:
     sys.exit(0)

package/obj/template/.claude/hooks/spec_approval_guard.sh

@@ -6,7 +6,7 @@
 #   1. Approval artifacts (.claude/state/spec_approvals/*.approval) — only
 #      writable when a fresh slug-matched consent marker exists at
 #      .claude/state/.spec_approval_grant. The marker is written by
-#      consent_gate_grant.sh on /approve-spec invocation, OUTSIDE Claude's
+#      consent_gate_grant.mjs on /approve-spec invocation, OUTSIDE Claude's
 #      tool boundary. Validated and consumed via validate_consent_marker.
 #
 #   2. The marker file itself — Claude SHALL NEVER write it via tool. The

package/obj/template/.claude/hooks/swarm_approval_guard.sh

@@ -6,7 +6,7 @@
 #   1. Approval artifacts (.claude/state/swarm_approvals/<slug>.approval) —
 #      writable only when a fresh slug-matched marker at
 #      .claude/state/.swarm_approval_grant exists. Marker is written by
-#      consent_gate_grant.sh on /approve-swarm. Validated + consumed via
+#      consent_gate_grant.mjs on /approve-swarm. Validated + consumed via
 #      validate_consent_marker.
 #
 #   2. The marker file itself — Claude SHALL NEVER write it via tool.

package/obj/template/.claude/hooks/tests/fixtures/ac008_byte_equal_reference.txt

@@ -1,12 +1,12 @@
 ## Project memory — index (.claude/memory/)
 
-HEAD: `n/a`  ·  total entries: 32  ·  stale (>=30 commits old): 0
+HEAD: `n/a`  ·  total entries: 68  ·  stale (>=30 commits old): 0
 
 | File | Entries | Stale | Status |
 |---|---:|---:|---|
-| `landmarks.md` | 19 | 0 | ok |
-| `libraries.md` | 3 | 0 | ok |
-| `decisions.md` | 1 | 0 | ok |
-| `landmines.md` | 5 | 0 | ok |
-| `conventions.md` | 3 | 0 | ok |
-| `pending-questions.md` | 1 | 0 | ok |
+| `landmarks.md` | 34 | 0 | ok |
+| `libraries.md` | 5 | 0 | ok |
+| `decisions.md` | 2 | 0 | ok |
+| `landmines.md` | 8 | 0 | ok |
+| `conventions.md` | 7 | 0 | ok |
+| `pending-questions.md` | 6 | 0 | ok |

package/obj/template/.claude/hooks/tests/fixtures/memory_stop_landmark_baseline.txt

@@ -0,0 +1,21 @@
+---
+owners: [memory_stop.sh writes; /memory-flush clears]
+category: auto-extracted candidates awaiting curation
+verifies-against: none
+---
+
+# Pending memory candidates
+
+---
+
+
+<!-- session 2026-05-17T09:35Z -->
+## CANDIDATE: src/foo.py → landmarks.md
+- Touched in this session: 2 times
+- Suggested role: <fill in from session context>
+- Source: file written/edited at 2026-05-17T09:35Z
+
+## CANDIDATE: src/bar.py → landmarks.md
+- Touched in this session: 1 time
+- Suggested role: <fill in from session context>
+- Source: file written/edited at 2026-05-17T09:35Z

package/obj/template/.claude/hooks/tests/fixtures/regenerate-ac008.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Regenerate the AC-008 byte-equality fixture from the live .claude/memory/ tree.
+#
+# Runs memory_session_start.sh against the current repo, extracts the
+# "## Project memory" header through the "| `pending-questions.md`" row, and
+# normalizes the HEAD short SHA to the literal sentinel "n/a". The fixture is
+# HEAD-agnostic; memory_session_start_test.sh's AC-008 case applies the same
+# normalization to the live capture before byte-comparing.
+#
+# Re-run this whenever the canonical .claude/memory/ tree drifts in entry
+# counts. Idempotent — same tree state produces identical bytes.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../../../.." && pwd)"
+HOOK="$REPO_ROOT/.claude/hooks/memory_session_start.sh"
+FIXTURE="$HERE/ac008_byte_equal_reference.txt"
+
+if [ ! -f "$HOOK" ]; then
+  echo "regenerate-ac008.sh: hook not found at $HOOK" >&2
+  exit 1
+fi
+
+block="$(CLAUDE_PROJECT_DIR="$REPO_ROOT" bash "$HOOK" <<< '{}' | python3 -c '
+import json, re, sys
+HEAD_RE = re.compile(r"^(HEAD:\s*`)[^`]+(`)")
+data = sys.stdin.read().strip()
+if not data:
+    sys.exit("regenerate-ac008.sh: memory_session_start.sh emitted no output")
+j = json.loads(data)
+ctx = j["hookSpecificOutput"]["additionalContext"]
+out = []
+started = False
+for ln in ctx.split("\n"):
+    if ln.startswith("## Project memory"):
+        started = True
+    if not started:
+        continue
+    out.append(HEAD_RE.sub(r"\1n/a\2", ln))
+    if ln.startswith("| `pending-questions.md`"):
+        break
+sys.stdout.write("\n".join(out) + "\n")
+')"
+
+printf '%s\n' "$block" > "$FIXTURE"
+echo "regenerated $FIXTURE"