@hegemonart/get-design-done 1.0.7

package/hooks/budget-enforcer.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * budget-enforcer.js — PreToolUse hook (matcher: Agent)
+ *
+ * Intercepts every Agent tool spawn. Consults:
+ *   (a) router decision (from tool_input.context.router_decision if supplied)
+ *   (b) .design/cache-manifest.json for short-circuit cached answers (D-05)
+ *   (c) .design/budget.json for tier_overrides + caps (D-01, D-04, D-10)
+ *
+ * Enforcement (D-02, D-03, D-11):
+ *   - enforcement_mode: "enforce" + 100% cap → block with actionable error
+ *   - enforcement_mode: "enforce" + 80% soft-threshold + auto_downgrade_on_cap → rewrite tier to haiku
+ *   - enforcement_mode: "warn" → log warning, allow spawn
+ *   - enforcement_mode: "log" → advisory only
+ *
+ * Logs every decision to .design/telemetry/costs.jsonl (OPT-09 schema).
+ * Every telemetry write fires a detached child aggregator (scripts/aggregate-agent-metrics.js)
+ * that rebuilds .design/agent-metrics.json incrementally.
+ *
+ * Hook type: PreToolUse
+ * Input:  JSON on stdin { tool_name, tool_input }
+ * Output: JSON on stdout { continue, suppressOutput, message, modified_tool_input? }
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { spawn } = require('child_process');
+
+const BUDGET_PATH = path.join(process.cwd(), '.design', 'budget.json');
+const MANIFEST_PATH = path.join(process.cwd(), '.design', 'cache-manifest.json');
+const TELEMETRY_PATH = path.join(process.cwd(), '.design', 'telemetry', 'costs.jsonl');
+const STATE_PATH = path.join(process.cwd(), '.design', 'STATE.md');
+
+// ---- budget.json loader with defaults per D-12 ----
+function loadBudget() {
+  const defaults = {
+    per_task_cap_usd: 2.00,
+    per_phase_cap_usd: 20.00,
+    tier_overrides: {},
+    auto_downgrade_on_cap: true,
+    cache_ttl_seconds: 3600,
+    enforcement_mode: 'enforce'
+  };
+  if (!fs.existsSync(BUDGET_PATH)) return defaults;
+  try { return { ...defaults, ...JSON.parse(fs.readFileSync(BUDGET_PATH, 'utf8')) }; }
+  catch { return defaults; }
+}
+
+// ---- cumulative phase spend from telemetry (D-02 per_phase_cap_usd check) ----
+function currentPhaseSpend(phase) {
+  if (!fs.existsSync(TELEMETRY_PATH)) return 0;
+  const lines = fs.readFileSync(TELEMETRY_PATH, 'utf8').split(/\r?\n/).filter(Boolean);
+  let sum = 0;
+  for (const line of lines) {
+    try {
+      const row = JSON.parse(line);
+      if (row.phase === phase) sum += Number(row.est_cost_usd || 0);
+    } catch { /* tolerant */ }
+  }
+  return sum;
+}
+
+// ---- cycle + phase reader (STATE.md frontmatter) ----
+function readCycleAndPhase() {
+  const defaults = { cycle: 'unknown', phase: 'unknown' };
+  if (!fs.existsSync(STATE_PATH)) return defaults;
+  try {
+    const content = fs.readFileSync(STATE_PATH, 'utf8');
+    // Match the first frontmatter block: between opening '---' and next '---'
+    const fm = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    const body = fm ? fm[1] : content;
+    const cycleMatch = body.match(/^cycle:\s*"?([^"\n]+)"?/m);
+    const phaseMatch = body.match(/^phase:\s*"?([^"\n]+)"?/m);
+    return {
+      cycle: cycleMatch ? cycleMatch[1].trim() : 'unknown',
+      phase: phaseMatch ? phaseMatch[1].trim() : 'unknown',
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+// Deprecated alias for plan 01 callers (and any other hook/script that imports this).
+// Returns only the phase string; prefer readCycleAndPhase() for new code.
+function currentPhase() {
+  return readCycleAndPhase().phase;
+}
+
+// ---- cache short-circuit (D-05) ----
+function cacheLookup(agent, inputHash) {
+  if (!fs.existsSync(MANIFEST_PATH)) return null;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+    const entry = manifest.entries?.[`${agent}:${inputHash}`];
+    if (!entry) return null;
+    const age = Date.now() / 1000 - entry.ts_unix;
+    if (age > (manifest.ttl_seconds || 3600)) return null;
+    return entry.result;  // cached blob
+  } catch { return null; }
+}
+
+// ---- tier resolution (D-04) ----
+function resolveTier(agent, agentDefaultTier, overrides) {
+  return overrides?.[agent] || agentDefaultTier || 'sonnet';
+}
+
+// ---- detached aggregator invocation ----
+// Fire-and-forget: do not block the hook. The aggregator reads costs.jsonl tail
+// and rewrites .design/agent-metrics.json atomically.
+function spawnAggregator() {
+  try {
+    const aggregatorPath = path.join(process.cwd(), 'scripts', 'aggregate-agent-metrics.js');
+    if (!fs.existsSync(aggregatorPath)) return; // script not installed — fail open
+    const child = spawn('node', [aggregatorPath], {
+      cwd: process.cwd(),
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    });
+    child.unref();
+  } catch {
+    // Aggregator failures are non-fatal to the hook.
+  }
+}
+
+// ---- locked-schema row builder (OPT-09) ----
+function buildTelemetryRow(partial) {
+  const { cycle, phase } = partial._cyclePhase || readCycleAndPhase();
+  // The nine mandatory fields per OPT-09, always in this order.
+  const row = {
+    ts: partial.ts || new Date().toISOString(),
+    agent: String(partial.agent || 'unknown'),
+    tier: String(partial.tier || 'unknown'),
+    tokens_in: Number(partial.tokens_in || 0),
+    tokens_out: Number(partial.tokens_out || 0),
+    cache_hit: Boolean(partial.cache_hit),
+    est_cost_usd: Number(partial.est_cost_usd || 0),
+    cycle: partial.cycle || cycle,
+    phase: partial.phase || phase,
+  };
+  // Optional diagnostic fields (Phase 11 reflector ignores unknown fields gracefully).
+  if (partial.tier_downgraded !== undefined) row.tier_downgraded = Boolean(partial.tier_downgraded);
+  if (partial.enforcement_mode !== undefined) row.enforcement_mode = String(partial.enforcement_mode);
+  if (partial.lazy_skipped !== undefined) row.lazy_skipped = Boolean(partial.lazy_skipped);
+  if (partial.block_reason !== undefined) row.block_reason = String(partial.block_reason);
+  return row;
+}
+
+// ---- telemetry writer: append one JSON row to costs.jsonl ----
+function writeTelemetry(partial) {
+  const dir = path.dirname(TELEMETRY_PATH);
+  try {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const row = buildTelemetryRow(partial);
+    fs.appendFileSync(TELEMETRY_PATH, JSON.stringify(row) + '\n', 'utf8');
+    // Fire-and-forget aggregator — rebuilds .design/agent-metrics.json incrementally.
+    spawnAggregator();
+  } catch {
+    // Fail open: telemetry must never block the hook.
+  }
+}
+
+// Backward-compat alias (plan 01 called it appendTelemetry; keep it working).
+const appendTelemetry = writeTelemetry;
+
+// ---- main ----
+async function main() {
+  const rl = readline.createInterface({ input: process.stdin });
+  let inputData = '';
+  for await (const line of rl) inputData += line + '\n';
+
+  let parsed;
+  try { parsed = JSON.parse(inputData); } catch { process.exit(0); }
+
+  if (parsed.tool_name !== 'Agent') process.exit(0);  // only guard Agent spawns
+
+  const toolInput = parsed.tool_input || {};
+  const agent = toolInput.subagent_type || toolInput.agent || 'unknown';
+  const inputHash = toolInput._input_hash || null;  // supplied by orchestrator if cache-manager pre-computed it
+
+  // Resolve cycle + phase once so every branch can stamp consistent values.
+  const { cycle, phase } = readCycleAndPhase();
+  const cyclePhase = { cycle, phase };
+
+  // Branch A: lazy-gate signal from plan 10.1-04 agents (design-verifier-gate, etc.).
+  // Gate agents set tool_input.lazy_skipped === true when the heuristic declines
+  // to spawn the full checker. We log a zero-cost row and pass through.
+  if (toolInput.lazy_skipped === true) {
+    writeTelemetry({
+      agent,
+      tier: 'gate',
+      tokens_in: 0,
+      tokens_out: 0,
+      cache_hit: false,
+      est_cost_usd: 0,
+      lazy_skipped: true,
+      _cyclePhase: cyclePhase,
+    });
+    const response = { continue: true, suppressOutput: true };
+    process.stdout.write(JSON.stringify(response));
+    return;
+  }
+
+  const budget = loadBudget();
+
+  // Branch B: cache short-circuit (D-05)
+  if (inputHash) {
+    const cached = cacheLookup(agent, inputHash);
+    if (cached !== null) {
+      writeTelemetry({
+        agent,
+        tier: 'cache',
+        tokens_in: 0,
+        tokens_out: 0,
+        cache_hit: true,
+        est_cost_usd: 0,
+        _cyclePhase: cyclePhase,
+      });
+      const response = {
+        continue: false,  // block the real spawn; orchestrator reads suppressOutput.message for cached blob
+        suppressOutput: false,
+        message: `gdd-budget-enforcer: SkippedCached — returning cached result for ${agent}:${inputHash}`,
+        cached_result: cached,
+      };
+      process.stdout.write(JSON.stringify(response));
+      return;
+    }
+  }
+
+  // Layer B: cap checks (D-02)
+  const estCost = Number(toolInput._est_cost_usd || 0);
+  const phaseSpend = currentPhaseSpend(phase);
+
+  if (budget.enforcement_mode === 'enforce') {
+    // Branch C: 100% per_task cap (hard block)
+    if (estCost >= budget.per_task_cap_usd) {
+      writeTelemetry({
+        agent,
+        tier: toolInput._tier_override || toolInput._default_tier || 'sonnet',
+        tokens_in: Number(toolInput._tokens_in_est || 0),
+        tokens_out: Number(toolInput._tokens_out_est || 0),
+        cache_hit: false,
+        est_cost_usd: estCost,
+        enforcement_mode: budget.enforcement_mode,
+        block_reason: 'per_task_cap',
+        _cyclePhase: cyclePhase,
+      });
+      const response = {
+        continue: false,
+        suppressOutput: false,
+        message: `Budget cap reached for per-task. Estimated: $${estCost.toFixed(4)}, cap: $${budget.per_task_cap_usd.toFixed(2)}. Raise cap in .design/budget.json or retry after next task.`,
+      };
+      process.stdout.write(JSON.stringify(response));
+      return;
+    }
+    // Branch D: 100% per_phase cap (hard block)
+    if (phaseSpend + estCost >= budget.per_phase_cap_usd) {
+      writeTelemetry({
+        agent,
+        tier: toolInput._tier_override || toolInput._default_tier || 'sonnet',
+        tokens_in: Number(toolInput._tokens_in_est || 0),
+        tokens_out: Number(toolInput._tokens_out_est || 0),
+        cache_hit: false,
+        est_cost_usd: estCost,
+        enforcement_mode: budget.enforcement_mode,
+        block_reason: 'per_phase_cap',
+        _cyclePhase: cyclePhase,
+      });
+      const response = {
+        continue: false,
+        suppressOutput: false,
+        message: `Budget cap reached for per-phase (${phase}). Cumulative: $${(phaseSpend + estCost).toFixed(4)}, cap: $${budget.per_phase_cap_usd.toFixed(2)}. Raise cap in .design/budget.json or retry after next phase.`,
+      };
+      process.stdout.write(JSON.stringify(response));
+      return;
+    }
+    // 80% soft-threshold downgrade (D-03)
+    if (budget.auto_downgrade_on_cap && (phaseSpend + estCost) >= (0.80 * budget.per_task_cap_usd)) {
+      toolInput._tier_override = 'haiku';
+      toolInput._tier_downgraded = true;
+    }
+  } else if (budget.enforcement_mode === 'warn') {
+    if (estCost >= budget.per_task_cap_usd) {
+      process.stderr.write(`gdd-budget-enforcer WARN: per-task cap will be exceeded ($${estCost.toFixed(4)} >= $${budget.per_task_cap_usd})\n`);
+    }
+  }
+  // enforcement_mode === 'log': no blocking, just telemetry
+
+  // D-04: tier_overrides rewrite
+  if (budget.tier_overrides[agent]) {
+    toolInput._tier_override = budget.tier_overrides[agent];
+  }
+
+  // Branch E: standard spawn-allowed (includes tier-downgraded path D-03)
+  writeTelemetry({
+    agent,
+    tier: toolInput._tier_override || toolInput._default_tier || 'sonnet',
+    tokens_in: Number(toolInput._tokens_in_est || 0),
+    tokens_out: Number(toolInput._tokens_out_est || 0),
+    cache_hit: false,
+    est_cost_usd: estCost,
+    tier_downgraded: !!toolInput._tier_downgraded,
+    enforcement_mode: budget.enforcement_mode,
+    _cyclePhase: cyclePhase,
+  });
+
+  const response = {
+    continue: true,
+    suppressOutput: true,
+    modified_tool_input: toolInput
+  };
+  process.stdout.write(JSON.stringify(response));
+}
+
+main().catch(err => { console.error('budget-enforcer hook error:', err); process.exit(0); });

package/hooks/context-exhaustion.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * context-exhaustion.js — PostToolUse hook
+ *
+ * Monitors context usage reported in the tool_response. When usage exceeds
+ * THRESHOLD (default 85%), writes a <paused> resumption block to
+ * .design/STATE.md so the next session can resume without losing context.
+ *
+ * Hook type: PostToolUse (any tool)
+ * Input:  JSON on stdin { tool_name, tool_input, tool_response }
+ * Output: JSON on stdout { continue, suppressOutput, message } or nothing
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const THRESHOLD = parseFloat(process.env.GDD_CONTEXT_THRESHOLD || '0.85');
+const STATE_PATH = path.join(process.cwd(), '.design', 'STATE.md');
+
+function now() {
+  return new Date().toISOString();
+}
+
+function extractContextUsage(toolResponse) {
+  // Claude Code injects context usage as a field in the tool response envelope.
+  // Try common field names used across Claude Code versions.
+  if (typeof toolResponse !== 'object' || toolResponse === null) return null;
+
+  // Direct field
+  if (typeof toolResponse.context_usage === 'number') return toolResponse.context_usage;
+  if (typeof toolResponse.contextUsage === 'number') return toolResponse.contextUsage;
+
+  // Nested under metadata
+  const meta = toolResponse.metadata || toolResponse.meta || {};
+  if (typeof meta.context_usage === 'number') return meta.context_usage;
+  if (typeof meta.contextUsage === 'number') return meta.contextUsage;
+
+  // Fraction string "0.87" or percentage "87%"
+  const raw = toolResponse.context_usage || toolResponse.contextUsage
+    || meta.context_usage || meta.contextUsage;
+  if (typeof raw === 'string') {
+    if (raw.endsWith('%')) return parseFloat(raw) / 100;
+    const n = parseFloat(raw);
+    if (!isNaN(n)) return n > 1 ? n / 100 : n;
+  }
+
+  return null;
+}
+
+function buildPausedBlock(toolName, usage) {
+  const pct = Math.round(usage * 100);
+  return `
+<paused>
+recorded: ${now()}
+trigger: context-exhaustion-hook
+context_usage: ${pct}%
+last_tool: ${toolName}
+
+## Resumption instructions
+
+Context reached ${pct}% during the previous session (threshold: ${Math.round(THRESHOLD * 100)}%).
+The session was auto-paused to preserve quality.
+
+To resume:
+1. Run \`/gdd:resume\` — it will read this block and restore working context
+2. If mid-plan: check .design/STATE.md for the last completed task
+3. Re-read the active PLAN.md to orient before continuing
+
+Intel store status at pause time:
+  ls .design/intel/files.json 2>/dev/null && echo "present" || echo "missing"
+</paused>
+`;
+}
+
+function stateFileHasPausedBlock() {
+  if (!fs.existsSync(STATE_PATH)) return false;
+  const content = fs.readFileSync(STATE_PATH, 'utf8');
+  return content.includes('<paused>') && content.includes('context-exhaustion-hook');
+}
+
+function appendPausedBlock(block) {
+  if (!fs.existsSync(path.dirname(STATE_PATH))) {
+    fs.mkdirSync(path.dirname(STATE_PATH), { recursive: true });
+  }
+  if (!fs.existsSync(STATE_PATH)) {
+    fs.writeFileSync(STATE_PATH, '# Design State\n\n', 'utf8');
+  }
+  fs.appendFileSync(STATE_PATH, block, 'utf8');
+}
+
+async function main() {
+  const rl = readline.createInterface({ input: process.stdin });
+  let inputData = '';
+  for await (const line of rl) inputData += line + '\n';
+
+  let parsed;
+  try { parsed = JSON.parse(inputData); } catch { process.exit(0); }
+
+  const toolName = parsed?.tool_name || 'unknown';
+  const toolResponse = parsed?.tool_response || {};
+
+  const usage = extractContextUsage(toolResponse);
+
+  // No usage data — cannot act
+  if (usage === null) process.exit(0);
+
+  // Below threshold — do nothing
+  if (usage < THRESHOLD) process.exit(0);
+
+  // At or above threshold — write paused block (only once per session)
+  if (stateFileHasPausedBlock()) process.exit(0);
+
+  const block = buildPausedBlock(toolName, usage);
+  appendPausedBlock(block);
+
+  const response = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-context-exhaustion: Context at ${Math.round(usage * 100)}% — auto-recorded <paused> block in .design/STATE.md. Run /gdd:resume in the next session to continue.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+}
+
+main().catch(err => { console.error('context-exhaustion hook error:', err); process.exit(0); });

package/hooks/gdd-read-injection-scanner.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * gdd-read-injection-scanner — PostToolUse hook
+ * Scans Read tool output for common prompt-injection patterns and warns
+ * (does not block) when suspicious content is found in a read file.
+ */
+
+const readline = require('readline');
+
+const INJECTION_PATTERNS = [
+  /ignore\s+(all\s+)?(previous|prior|above)\s+instructions?/i,
+  /disregard\s+(all\s+)?(previous|prior|above)\s+instructions?/i,
+  /you\s+are\s+now\s+a\s+different/i,
+  /system\s*:\s*you\s+are/i,
+  /<\s*\/?\s*(system|assistant|human)\s*>/i,
+  /\[INST\]/i,
+  /###\s*instruction/i,
+];
+
+async function main() {
+  const rl = readline.createInterface({ input: process.stdin });
+  let inputData = '';
+  for await (const line of rl) inputData += line + '\n';
+
+  let parsed;
+  try { parsed = JSON.parse(inputData); } catch { process.exit(0); }
+
+  if (parsed?.tool_name !== 'Read') process.exit(0);
+
+  const content = parsed?.tool_response?.content || '';
+  const matched = INJECTION_PATTERNS.some(p => p.test(content));
+  if (!matched) process.exit(0);
+
+  const file = parsed?.tool_input?.file_path || 'unknown';
+  const response = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-injection-scanner: Suspicious prompt-injection pattern detected in content read from "${file}". Review before acting on instructions contained in that file.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/hooks.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.sh\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.js\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-read-injection-scanner.js\""
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.js\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@hegemonart/get-design-done",
+  "version": "1.0.7",
+  "description": "A Claude Code plugin for systematic design improvement",
+  "author": "Hegemon",
+  "homepage": "https://github.com/hegemonart/get-design-done",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hegemonart/get-design-done.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    ".claude-plugin/",
+    "agents/",
+    "skills/",
+    "hooks/",
+    "scripts/",
+    "connections/",
+    "reference/",
+    "SKILL.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.cjs\"",
+    "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",
+    "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
+    "validate:schemas": "node scripts/validate-schemas.cjs",
+    "validate:frontmatter": "node scripts/validate-frontmatter.cjs agents/",
+    "detect:stale-refs": "node scripts/detect-stale-refs.cjs",
+    "scan:injection": "node scripts/run-injection-scanner-ci.cjs",
+    "test:size-budget": "node --test tests/agent-size-budget.test.cjs",
+    "release:extract-changelog": "node scripts/extract-changelog-section.cjs",
+    "verify:version-sync": "node scripts/verify-version-sync.cjs"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-code-plugin",
+    "plugin",
+    "design",
+    "design-system",
+    "self-improvement",
+    "reflection",
+    "tested",
+    "ci"
+  ],
+  "skills": [
+    "SKILL.md"
+  ],
+  "hooks": "hooks/hooks.json"
+}

package/reference/BRANCH-PROTECTION.md

@@ -0,0 +1,65 @@
+# Branch Protection — Two-Phase Rollout
+
+Per D-16 / D-17: branch protection on `main` is rolled out in two phases. The
+repo admin applies each phase manually via `scripts/apply-branch-protection.sh`
+(no CI automation — avoids leaking repo admin credentials).
+
+## Phase A — Advisory (initial state)
+
+Status checks **run** on every push, but they are **not required to merge**.
+This is the default posture while CI stabilizes and baselines are established.
+
+Apply:
+
+```bash
+bash scripts/apply-branch-protection.sh --advisory
+```
+
+Effects:
+
+- Required status checks: **none** (checks run but don't block)
+- `main` accepts direct pushes (the solo maintainer's existing workflow)
+- Force-push: allowed by admins
+
+## Phase B — Enforcing (after first clean release)
+
+After the first full release cycle ships clean (plan 13-06 / 13-07 smoke test
+passes on a real tag + GitHub Release), tighten to enforcing.
+
+Apply:
+
+```bash
+bash scripts/apply-branch-protection.sh --enforcing
+```
+
+Effects:
+
+- Required status checks (all must pass to merge):
+  - `Lint (markdown + frontmatter + stale-refs)`
+  - `Validate (schemas + plugin + shellcheck)`
+  - `Test (Node 22 / ubuntu-latest)`
+  - `Test (Node 22 / macos-latest)`
+  - `Test (Node 22 / windows-latest)`
+  - `Test (Node 24 / ubuntu-latest)`
+  - `Test (Node 24 / macos-latest)`
+  - `Test (Node 24 / windows-latest)`
+  - `Security (secrets + injection scan)`
+  - `Size budget (blocking)`
+- Require linear history (no merge commits)
+- Disallow force-push
+- Admins still bypass for emergency fixes (logged)
+
+## When to promote Phase A → Phase B
+
+- [ ] Wave A + B of Phase 13 merged to main
+- [ ] `release.yml` (plan 13-06) merged and triggered at least once successfully
+- [ ] Release smoke test (plan 13-07) passed on a real tag
+- [ ] Baseline lock (plan 13-08) committed
+
+When all four are true, run `apply-branch-protection.sh --enforcing`.
+
+## Rollback
+
+To revert either phase: `apply-branch-protection.sh --disable` removes all
+protection rules. Use only if a protection misconfiguration is blocking a
+legitimate merge.