toga-ai 1.0.565 → 1.0.566

package/.claude/settings.json

@@ -13,7 +13,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Bash|Read|Grep|Glob|Edit|Write|MultiEdit|NotebookEdit|Task|WebFetch|WebSearch",
+        "matcher": "Bash|Read|Grep|Glob|Edit|Write|MultiEdit|NotebookEdit|Task|Agent|WebFetch|WebSearch",
         "hooks": [
           {
             "type": "command",

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
+updated: 2026-08-12
 owners: ["dfranks", "jcardinal", "mhammontree", "ajean", "bala"]
 files:
   - _underscore/Error.php
@@ -438,20 +438,41 @@ app that has not been wired up yet.
 in `_underscore` and `library` in the **same** release, and the `/errors` console work needs
 **both** `library` and `tools` deployed before it is visible.
 
-## ⚠ OPEN DEFECT (2026-08-06) — error capture is DEAD on sandbox-dev/beta: `Logs.Issue` is missing `clickupPriority`
+## ✅ RESOLVED (2026-08-12) — error capture was DEAD on sandbox-dev: `Logs.Issue` was missing SEVEN columns (originally filed as one)
 
-**Anyone debugging on that environment is flying blind.** The capture INSERT fails with **MySQL 1054
-(unknown column)** because `Logs.Issue` there has `clickupAssigneeId` and `createsClickupTask` but
-**not `clickupPriority`**. Consequences:
+**Filed 2026-08-06 as a single missing column (`clickupPriority`); it was actually SEVEN.** On
+**2026-08-12**, debugging a `/v2/surfaces/meta` 500 that returned `EO-1` with a null `error.id` and
+wrote nothing to `Logs.Event`, a live `information_schema` diff of dev-sandbox `Logs.Issue` (**23
+columns**) against `_Model_Core_Logs_Issue` (**30 columns**) found **seven** missing columns:
+`clickupPriority` (migration `dbchanges2/Logs/2026-08-03a`) **plus the entire `2026-08-05a` lifecycle
+migration** — `status`, `dtAutoResolved`, `baselineGapSeconds`, `baselineSampleCount`,
+`dtBaselineAnchor`, `baselineAnchorOccurrences`. `_Model::save()` builds its INSERT from **all 30
+declared fields**, so the first absent column throws **MySQL 1054 (unknown column)** and the whole
+capture aborts. **Anyone debugging on that environment was flying blind.** While broken:
 
 - **No error is persisted at all** — no `Logs.Issue` row, no `Logs.Event` row, no ClickUp task.
-- The only trace is inline in the API response as **`identifiers.captureFailure`**. If you are
-  looking in the database or ClickUp for an error you just triggered and finding nothing, look at the
-  response body for `captureFailure` before concluding the error didn't happen.
-
-**Cause:** `_underscore` commit `4ebe12fe` *"Improve error fingerprinting, add ClickUp priority
-tracking"* shipped the code that writes the column **without its schema migration reaching that
-environment.** Fix is a one-column `dbchanges2` migration in the `Logs` folder.
+- The only trace is inline in the API response as **`identifiers.captureFailure`** — and that is
+  **debug-mode-gated**, so on a deployed non-prod box with debug off the caller sees `identifiers: []`
+  and has *nothing*. (This blind spot is now closed — see the controller hardening below.)
+
+**Cause:** both `dbchanges2/Logs/2026-08-03a` and `2026-08-05a` exist in the repo but **never ran on
+dev-sandbox** — the runner tracks applied files per environment (see `Logs/2026-07-29a`), and these two
+were skipped there. The originally-filed "one missing column, needs a one-column migration" was correct
+about the mechanism but **undercounted the drift** — reading the 2026-08-06 note alone would have left
+six columns still missing.
+
+**Resolution (2026-08-12):** **re-applied the two existing migrations (`2026-08-03a`, then `2026-08-05a`)
+to dev-sandbox** — no new migration was written; capture came back to life immediately (`Logs.Issue`/
+`Logs.Event` rows written, `error.id` populated). **Still verify the same drift on beta and every other
+non-prod env** before trusting their capture.
+
+**Controller hardening (api2, 2026-08-12):** `api2/Controller/Index.php` now surfaces
+`identifiers.captureFailure` on **every environment except production** (`_Environment::$name !==
+'production'`), even with debug mode off — in both the `execute()` catch and the DB-bootstrap catch. The
+exception `message`/`trace` stay debug-only (they carry `_Database::register()` frame-arg credentials);
+`captureFailure` names only *why the recorder failed* and cannot leak them. A dead capture layer now
+announces itself instead of returning empty `identifiers`, so this class of `Logs` schema drift can never
+again be silent on a non-prod box.
 
 **The general lesson (this is the pipeline's structural weak point):** error capture is the one
 subsystem whose own failure cannot be reported through itself. A schema drift here does not degrade
@@ -631,6 +652,17 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-12 — **Corrected the 2026-08-06 open defect and marked it RESOLVED.** The sandbox-dev
+  `Logs.Issue` drift was **seven** missing columns, not one: `clickupPriority` (`2026-08-03a`) **plus the
+  whole `2026-08-05a` lifecycle migration** (`status`, `dtAutoResolved`, `baselineGapSeconds`,
+  `baselineSampleCount`, `dtBaselineAnchor`, `baselineAnchorOccurrences`) — found by an
+  `information_schema` diff (live 23 cols vs. model 30 cols) while debugging a `/v2/surfaces/meta` 500
+  that returned `EO-1` with a null `error.id` and wrote no `Logs.Event`. Both migrations existed but had
+  **never run on dev-sandbox** (the runner tracks applied files per environment); **re-applying the two
+  existing files** restored capture — no new migration. Also **hardened `api2/Controller/Index.php`** to
+  surface `identifiers.captureFailure` on every non-production environment even with debug off
+  (`message`/`trace` stay debug-only, as they carry DB creds), so a dead capture layer can no longer be
+  invisible on a non-prod box. (jcardinal)
 - 2026-08-11 — Sharpened the `error.id` lookup recipe from a production incident investigation
   (Compass, api2 500s): **`status = 'RESOLVED'` with `dtAutoResolved` set and `isManaged = 0` is a
   cron auto-close after a quiet window, not a fix** — it is indistinguishable from a real fix on

package/knowledge/sessions/2026-08-12-api2-error-capture-schema-drift-jcardinal.md

@@ -0,0 +1,87 @@
+---
+type: session
+slug: api2-error-capture-schema-drift
+title: Fix invisible api2 500s (sandbox-dev Logs.Issue schema drift killed error capture); harden the recorder and the kickoff KB-priming gate
+author: jcardinal
+repos: [api2, _underscore, dbchanges2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-08-12
+updated: 2026-08-12
+---
+
+# Session: api2-error-capture-schema-drift
+**Date:** 2026-08-12
+**Project/Repo:** api2, _underscore, dbchanges2 (2.0) + harness (`~/toga-tech` skills/hooks)
+**Task:** A `/v2/surfaces/meta` 500 on dev.sandbox returned `EO-1` with a null `error.id` and wrote
+nothing to `Logs.Event` — undebuggable. Find why nothing is recorded and make errors visible.
+
+---
+
+## What was wrong (root cause)
+
+api2's `Controller/Index.php` catches `Throwable` from `V2.php::execute()` and calls
+`_Error::captureException()` to record the error and mint an `error.id`. `captureException()` does
+`$issue->save()`, and `_Model::save()` builds its INSERT from **all 30 fields declared on
+`_Model_Core_Logs_Issue`**. Live **dev-sandbox `Logs.Issue` had only 23 columns** — the first missing
+one throws **MySQL 1054** and the whole capture aborts (returns `null`): no `Logs.Issue` row, no
+`Logs.Event` row, null `error.id`.
+
+Seven columns were missing (an `information_schema` diff, not the migration files — the files lag):
+- `clickupPriority` — `dbchanges2/Logs/2026-08-03a`
+- `status`, `dtAutoResolved`, `baselineGapSeconds`, `baselineSampleCount`, `dtBaselineAnchor`,
+  `baselineAnchorOccurrences` — the whole `dbchanges2/Logs/2026-08-05a` lifecycle migration
+
+Both migrations existed but had **never run on dev-sandbox** (the runner tracks applied files per
+environment — see `Logs/2026-07-29a`). The KB had this filed (2026-08-06) as **one** missing column;
+it was actually seven.
+
+**Second, compounding blind spot:** capture's only failure signal is
+`identifiers.captureFailure`, which the controller emitted **only in debug mode**. The deployed
+sandbox box runs with debug off, so the caller got `identifiers: []` — no hint at all.
+
+## What was done
+
+1. **Schema (fix that unblocked it):** re-applied the two existing migrations (`2026-08-03a` then
+   `2026-08-05a`) to dev-sandbox. No new migration. Capture came back immediately — confirmed fixed by
+   the developer. **Still verify beta and other non-prod envs for the same drift.**
+2. **Observability hardening (`api2/Controller/Index.php`):** surface `identifiers.captureFailure` on
+   **every environment except production** (`_Environment::$name !== 'production'`, new constant
+   `PRODUCTION_ENVIRONMENT_NAME`), even with debug off — in both the `execute()` catch and the
+   DB-bootstrap catch. `message`/`trace` stay **debug-only** (they carry `_Database::register()`
+   frame-arg DB credentials); `captureFailure` names only *why the recorder failed*, so it cannot leak
+   them. A dead capture layer now announces itself instead of returning empty `identifiers`.
+   *(Working tree only — not committed; a project repo, so the developer deploys it.)*
+3. **KB doc corrected:** `_underscore/features/error-reporting-issue-event.md` — the 2026-08-06 open
+   defect updated from one column to seven and marked RESOLVED, with the controller-hardening note.
+
+## Harness change (kickoff KB-priming enforcement)
+
+Prompted by a process failure this session: after `/kickoff`'s interview + preflight, the KB
+`context-primer` was spawned **in the background** while repo code was read **in parallel** — the team
+knowledge base was treated as a side-channel instead of the first source. Fixed so it cannot recur:
+
+- **`scripts/hooks/kickoff-gate.js`** is now **two-stage**: preflight no longer releases the gate — it
+  advances `armed → primer`. In `primer`, all repo `Read/Grep/Glob/Edit/Write` and every non-primer
+  agent stay **blocked** until the **`context-primer` subagent is spawned in the foreground**
+  (`run_in_background: false`); that spawn releases the gate. Reading `repo-path-<repo>` memories and
+  `AskUserQuestion` stay allowed.
+- **`.claude/settings.json`** — added `Agent` to the gate's `PreToolUse` matcher so it fires on
+  `Agent`-tool spawns.
+- **`skills/kickoff/SKILL.md`** — Step 4 rewritten to mandate KB-first, foreground, wait-for-it
+  subagent priming *before any other research* (even files named in the `/kickoff` sentence); the
+  top gate prose now describes the two stages.
+
+## Gotchas worth remembering
+- `_Model::save()` INSERTs **every declared field** — one missing `Logs` column silently kills ALL
+  capture on that environment (the recorder can't report its own failure). Any column added to a
+  `Logs` table must land its migration in **every** environment.
+- Read the **live** `Logs` schema (`information_schema` / `toga_describe_table`), not the `dbchanges2`
+  migration files — the files lag the deployed schema.
+- To debug an api2 500 you can't see: the `error.id` (`<Issue.reference>-<Event.eventNumber>`) →
+  `Logs.Issue.trace` by the reference (part before the dash) is the real stack; the response omits it.
+
+## Related
+- [[error-reporting-issue-event]] (the capture pipeline this session repaired + documented)
+- [[surface-meta-option]] (the endpoint whose 500 surfaced the blind spot)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.565",
+  "version": "1.0.566",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/scripts/hooks/kickoff-gate.js

@@ -2,32 +2,44 @@
 'use strict';
 
 /*
- * kickoff-gate.js — DETERMINISTIC enforcement of the /kickoff priming gate.
+ * kickoff-gate.js — DETERMINISTIC, TWO-STAGE enforcement of the /kickoff priming gate.
  *
- * Why this exists: the kickoff SKILL.md states a "hard gate" — when /kickoff is
- * invoked you MUST complete priming (Steps 0–6) BEFORE touching the task with any
- * Read/Grep/Glob/Edit/Write/Task call. Prose alone did not stop the model from
- * jumping straight to investigation when /kickoff was followed by a long, specific
- * task description. This hook makes the gate mechanical, not advisory.
+ * Why this exists: the kickoff SKILL.md states a "hard gate" — when /kickoff is invoked
+ * you MUST prime BEFORE touching the task. Prose alone did not stop the model from
+ * jumping to investigation when /kickoff was followed by a detailed task description.
+ * A first version of this hook released the gate the instant `kickoff-preflight` ran —
+ * but preflight only resolves the load-set; it does NOT read the team knowledge base.
+ * The model could (and did) run preflight, then read repo code BEFORE the team KB was
+ * primed, treating the knowledge base as a side-channel instead of the first source.
  *
- * It registers for TWO events from a single file:
+ * The team knowledge base is the whole point of kickoff — it is the distilled, shared
+ * gold the team maintains, and it must be primed FIRST, via the `context-primer`
+ * subagent, before ANY other research. This hook now enforces that in TWO stages:
  *
- *   UserPromptSubmit  → if the submitted prompt invokes /kickoff, ARM the gate:
- *                       write a session-scoped lock and inject a forceful reminder.
+ *   Stage 1  ARMED   (set by /kickoff)  — allow ONLY the read-only priming steps
+ *                    (version check, team-repo probe, manifest, interview) and
+ *                    `kickoff-preflight`. Everything else is blocked. Running
+ *                    `kickoff-preflight` ADVANCES the gate to stage 2 — it no longer
+ *                    releases it.
  *
- *   PreToolUse        → while the gate is armed for THIS session, ALLOW only the
- *                       read-only priming steps (the priming Bash commands + the
- *                       interview via AskUserQuestion/Skill, which don't match the
- *                       PreToolUse matcher) and BLOCK every task tool
- *                       (Read/Grep/Glob/Edit/Write/MultiEdit/NotebookEdit/Task/
- *                       WebFetch/WebSearch and any non-priming Bash). The lock
- *                       AUTO-CLEARS the moment `knowledge.js kickoff-preflight`
- *                       runs — the definitive priming step that precedes Step 4's
- *                       first Read. So the model literally cannot investigate or
- *                       edit the task until it has actually primed.
+ *   Stage 2  PRIMER  (set by preflight) — the load-set is known but the team KB is not
+ *                    yet primed. Block all repo research (Read/Grep/Glob of code, Edit,
+ *                    Write, and every non-primer agent) until the `context-primer`
+ *                    subagent is spawned IN THE FOREGROUND (run_in_background: false),
+ *                    so the model actually waits for the briefing. Spawning it releases
+ *                    the gate. Reading repo-path MEMORY files and asking the developer
+ *                    remain allowed (they are part of priming).
  *
- * Fail-open: any internal/parse error allows the tool (a crashing gate must never
- * brick every session). The SKILL.md prose remains the backup.
+ * Net effect: after the interview, the model literally cannot read a single repo file,
+ * grep the code, or spawn any other agent until it has primed from the team KB via the
+ * context-primer subagent. KB-first, via subagent, without exception.
+ *
+ * Registered for UserPromptSubmit (arm) + PreToolUse (enforce). A defensive
+ * PostToolUse branch is a no-op — release is spawn-time in PreToolUse, so the gate can
+ * never get stuck waiting on an event that did not fire.
+ *
+ * Fail-open: any internal/parse error allows the tool (a crashing gate must never brick
+ * every session). The SKILL.md prose remains the backup.
  *
  * Escape hatch: set KICKOFF_GATE_DISABLED=1 to disable enforcement entirely.
  */
@@ -61,10 +73,11 @@ function readLock() {
   try { return JSON.parse(fs.readFileSync(lockPath(), 'utf8')); } catch (e) { return null; }
 }
 
-function writeLock(sessionId) {
+// phase: 'armed' (priming not started) → 'primer' (preflight ran, team KB not yet primed).
+function writeLock(sessionId, phase) {
   try {
     fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
-    fs.writeFileSync(lockPath(), JSON.stringify({ session: sessionId || null, ts: Date.now() }) + '\n');
+    fs.writeFileSync(lockPath(), JSON.stringify({ session: sessionId || null, ts: Date.now(), phase: phase || 'armed' }) + '\n');
   } catch (e) { /* non-fatal */ }
 }
 
@@ -84,7 +97,7 @@ function invokesKickoff(prompt) {
 }
 
 /* Bash commands that ARE the read-only priming steps (Steps 0–3). Everything else
- * is task work and stays blocked until preflight clears the gate. */
+ * is task work and stays blocked. */
 function isPrimingBash(command) {
   if (typeof command !== 'string') return false;
   return /knowledge\.js|kickoff-preflight|toga-ai\.version|npm\s+view\s+toga-ai|npx\s+toga-ai|registry\.json|rev-parse/i.test(command);
@@ -94,58 +107,107 @@ function isPreflightBash(command) {
   return typeof command === 'string' && /kickoff-preflight/i.test(command);
 }
 
-/* Tools that constitute touching the task — blocked while the gate is armed. */
+/* A Read of a repo-path (or any) MEMORY file is part of priming (Step 3 resolves each
+ * repo's local path from a repo-path-<repo> memory). Allowed even in the primer stage;
+ * everything else under Read is repo research and stays blocked until the KB is primed. */
+function isMemoryReadPath(p) {
+  if (typeof p !== 'string' || !p) return false;
+  const norm = p.replace(/\\/g, '/');
+  return /\.claude\/projects\/.+\/memory\//i.test(norm);
+}
+
+/* The subagent that primes the team knowledge base. It — and only it — may run in the
+ * primer stage. */
+const PRIMER_SUBAGENT = 'context-primer';
+
+/* Tools that constitute touching the task — blocked while the gate is armed. Both the
+ * classic `Task` tool and this harness's `Agent` tool are included. */
 const BLOCKED_TOOLS = new Set([
   'Read', 'Grep', 'Glob', 'Edit', 'Write', 'MultiEdit',
   'NotebookEdit', 'Task', 'Agent', 'WebFetch', 'WebSearch',
 ]);
 
-function blockMessage() {
+function armedMessage() {
   return [
-    '🛑 KICKOFF GATE — priming is not complete.',
+    '🛑 KICKOFF GATE (stage 1 of 2) — priming has not started.',
     '',
-    '/kickoff was invoked this session. You MUST finish priming BEFORE touching the task',
-    'with any Read/Grep/Glob/Edit/Write/Task call — no matter how detailed the request after',
-    '/kickoff looks. That trailing text is the Step 2 task description, NOT permission to start.',
+    '/kickoff was invoked this session. Finish the read-only priming steps BEFORE any',
+    'Read/Grep/Glob/Edit/Write/Task — no matter how detailed the request after /kickoff',
+    'looks. That trailing text is the Step 2 task description, NOT permission to start.',
     '',
-    'Do this now, in order (these are allowed while the gate is armed):',
+    'Allowed now, in order:',
     '  • Step 0  version check (cat .claude/toga-ai.version ; npm view toga-ai version)',
     '  • Step 1  resolve the team repo (probe for knowledge/registry.json)',
     '  • Step 2  interview the developer (framework / layer / repo(s) / client / task)',
-    '  • Step 3  node "<TEAM_REPO>/knowledge.js" kickoff-preflight ...   ← this AUTO-CLEARS the gate',
-    '  • Step 4+ THEN read the knowledge docs and start the task',
+    '  • Step 3  node "<TEAM_REPO>/knowledge.js" kickoff-preflight ...',
     '',
-    'The gate releases automatically the instant kickoff-preflight runs.',
+    'Running kickoff-preflight ADVANCES the gate to stage 2 (team-KB priming). It no',
+    'longer releases the gate — priming the knowledge base does.',
     '(Emergency override only: set KICKOFF_GATE_DISABLED=1.)',
   ].join('\n');
 }
 
+function primerMessage() {
+  return [
+    '🛑 KICKOFF GATE (stage 2 of 2) — the TEAM KNOWLEDGE BASE has not been primed yet.',
+    '',
+    'kickoff-preflight resolved the load-set, but the team KB is the FIRST source you must',
+    'prime from — before ANY other research. Do NOT read repo code, grep/glob the source,',
+    'edit, or spawn any other agent yet — not even files named in the /kickoff sentence.',
+    '',
+    'Do this now (Step 4): spawn the context-primer subagent to read the resolved knowledge',
+    'docs and return the briefing —',
+    '    Agent tool · subagent_type: "context-primer" · run_in_background: false',
+    '    pass it: TEAM_REPO, the full kickoff-preflight JSON, and the task description.',
+    'Wait for its briefing. THEN read repo code and start the work.',
+    '',
+    'Allowed meanwhile: reading repo-path-<repo> memory files, AskUserQuestion (to ask for',
+    'a repo path), and knowledge.js priming commands.',
+    '(Emergency override only: set KICKOFF_GATE_DISABLED=1.)',
+  ].join('\n');
+}
+
+function foregroundMessage() {
+  return [
+    '🛑 KICKOFF GATE (stage 2 of 2) — spawn the context-primer in the FOREGROUND.',
+    '',
+    'Pass run_in_background: false so team-KB priming actually COMPLETES before you',
+    'continue. A backgrounded primer lets you race ahead and read repo code before the',
+    'knowledge-base briefing lands — the exact failure this gate exists to prevent.',
+  ].join('\n');
+}
+
 function main() {
   if (process.env.KICKOFF_GATE_DISABLED === '1') process.exit(0);
 
   const data = readPayload();
 
   // ---- UserPromptSubmit: arm the gate when /kickoff is invoked ----
-  // Identify by the presence of a prompt and absence of a tool call.
   const isPromptEvent =
     data.hook_event_name === 'UserPromptSubmit' ||
     (typeof data.prompt === 'string' && !data.tool_name);
 
   if (isPromptEvent) {
     if (invokesKickoff(data.prompt)) {
-      writeLock(data.session_id);
+      writeLock(data.session_id, 'armed');
       // stdout from UserPromptSubmit is injected into the model's context.
       console.log(
-        '<system-reminder>KICKOFF GATE ARMED. Before ANY other tool call, complete priming ' +
-        'Steps 0–6 of the kickoff skill — version check, resolve team repo, interview, then ' +
-        'run `knowledge.js kickoff-preflight` (which releases the gate), THEN read docs and work. ' +
-        'The trailing task description is Step 2 input, not permission to start. ' +
-        'A hook will block Read/Grep/Edit/Write/Task until preflight runs.</system-reminder>'
+        '<system-reminder>KICKOFF GATE ARMED (two stages). Stage 1: complete read-only ' +
+        'priming (version check, resolve team repo, interview) then run `knowledge.js ' +
+        'kickoff-preflight`. Stage 2: preflight does NOT release the gate — you must FIRST ' +
+        'prime the team knowledge base via the `context-primer` subagent (foreground, ' +
+        'run_in_background: false) BEFORE any repo Read/Grep/Glob/Edit/Write or other agent. ' +
+        'The trailing task description is Step 2 input, not permission to start.</system-reminder>'
       );
     }
     process.exit(0);
   }
 
+  // ---- PostToolUse: no-op. Release is spawn-time in PreToolUse, so the gate can never
+  //      hang waiting on a completion event. Present defensively so a PostToolUse wiring
+  //      never falls through to the PreToolUse enforcement below. ----
+  if (data.hook_event_name === 'PostToolUse') process.exit(0);
+
   // ---- PreToolUse: enforce while armed for THIS session ----
   const lock = readLock();
   if (!lock) process.exit(0);
@@ -158,22 +220,54 @@ function main() {
   if (data.session_id && lock.session && !sameSession) process.exit(0);
 
   const tool = data.tool_name || '';
-  const command = (data.tool_input && data.tool_input.command) || '';
+  const toolInput = data.tool_input || {};
+  const command = toolInput.command || '';
+  const phase = lock.phase || 'armed';
 
-  if (tool === 'Bash') {
-    if (isPreflightBash(command)) { clearLock(); process.exit(0); } // priming reached — release
-    if (isPrimingBash(command)) process.exit(0);                    // other read-only priming step
-    console.log(blockMessage());
-    process.exit(2);
+  // ================= STAGE 1: ARMED — only priming Steps 0–3 =================
+  if (phase === 'armed') {
+    if (tool === 'Bash') {
+      // preflight ADVANCES to stage 2 (does NOT release) — the team KB is still unprimed.
+      if (isPreflightBash(command)) { writeLock(lock.session, 'primer'); process.exit(0); }
+      if (isPrimingBash(command)) process.exit(0); // other read-only priming step
+      console.log(armedMessage());
+      process.exit(2);
+    }
+    if (BLOCKED_TOOLS.has(tool)) { console.log(armedMessage()); process.exit(2); }
+    process.exit(0); // AskUserQuestion, Skill, TodoWrite, … — part of the interview
   }
 
-  if (BLOCKED_TOOLS.has(tool)) {
-    console.log(blockMessage());
-    process.exit(2);
+  // ============ STAGE 2: PRIMER — team KB must be primed via subagent first ============
+  if (phase === 'primer') {
+    if (tool === 'Agent' || tool === 'Task') {
+      if (toolInput.subagent_type === PRIMER_SUBAGENT) {
+        // Must be foreground so the model waits for the briefing before doing anything else.
+        // (The classic `Task` tool runs synchronously; only the async `Agent` tool needs the
+        // explicit run_in_background: false.)
+        if (tool === 'Agent' && toolInput.run_in_background !== false) {
+          console.log(foregroundMessage());
+          process.exit(2);
+        }
+        clearLock(); // team-KB priming is underway in the foreground — release the gate
+        process.exit(0);
+      }
+      console.log(primerMessage()); // any other agent must wait until the KB is primed
+      process.exit(2);
+    }
+    if (tool === 'Read') {
+      if (isMemoryReadPath(toolInput.file_path || toolInput.path)) process.exit(0); // repo-path lookup
+      console.log(primerMessage());
+      process.exit(2);
+    }
+    if (tool === 'Bash') {
+      if (isPrimingBash(command)) process.exit(0);
+      console.log(primerMessage());
+      process.exit(2);
+    }
+    if (BLOCKED_TOOLS.has(tool)) { console.log(primerMessage()); process.exit(2); } // Grep/Glob/Edit/Write/…
+    process.exit(0); // AskUserQuestion (ask for a repo path), Skill, … — allowed
   }
 
-  // Anything else (AskUserQuestion, Skill, TodoWrite, ExitPlanMode, …) is part of
-  // priming/interview — allow.
   process.exit(0);
 }
 

package/skills/kickoff/SKILL.md

@@ -23,15 +23,24 @@ description: Start-of-session context loader for TOGA Technology projects. Run t
 > Only after Step 5's "primed and ready" summary (and Step 6's plan, for non-trivial work)
 > may you touch the task itself.
 >
-> **This gate is mechanically enforced — it is not just prose.** A hook
+> **This gate is mechanically enforced in TWO stages — it is not just prose.** A hook
 > (`hooks/toga/kickoff-gate.js`, wired on `UserPromptSubmit` + `PreToolUse`) arms the
 > instant `/kickoff` is invoked and will **hard-block** `Read`, `Grep`, `Glob`, `Edit`,
-> `Write`, `Task`, and any non-priming `Bash` until you actually prime. The only calls it
-> permits while armed are the read-only priming steps (the version check, team-repo probe,
-> `knowledge.js manifest`, the developer interview) and `knowledge.js kickoff-preflight` —
-> **running preflight (Step 3) is what releases the gate.** So the correct response to a
-> block message is never to fight it: run Steps 0–3, and the moment preflight executes you
-> are free to read docs and work. (Emergency override only: `KICKOFF_GATE_DISABLED=1`.)
+> `Write`, `Task`/`Agent`, and any non-priming `Bash` until you actually prime.
+>
+> - **Stage 1 (armed):** only the read-only priming steps (version check, team-repo probe,
+>   `knowledge.js manifest`, the developer interview) and `knowledge.js kickoff-preflight`
+>   are permitted. Running **preflight (Step 3) does NOT release the gate — it advances it to
+>   stage 2.**
+> - **Stage 2 (primer):** the load-set is resolved but the **team knowledge base is not yet
+>   primed.** Everything stays blocked until you spawn the **`context-primer` subagent in the
+>   foreground** (Step 4) — priming the team KB via that subagent is **what releases the gate.**
+>   Reading `repo-path-<repo>` memories and asking the developer stay allowed.
+>
+> So the correct response to a block message is never to fight it: run Steps 0–3, then
+> **prime the team KB via the foreground `context-primer` subagent (Step 4) BEFORE any other
+> research** — before you open a single repo file, even one named in the `/kickoff` sentence.
+> (Emergency override only: `KICKOFF_GATE_DISABLED=1`.)
 
 ## Session permission policy — auto-accept local file I/O, ALWAYS confirm dangerous execution
 
@@ -257,20 +266,30 @@ source — this is the one thing preflight can't know):
 
 Never ask for a repo not in `loadSet`.
 
-## Step 4 — Load the knowledge via the `context-primer` subagent (do NOT read docs inline)
-
-**This is the token-discipline core of kickoff.** Reading every architecture + feature +
-standard + client doc *into this conversation* is exactly what bloats the thread and trips
-compaction later. So you do **not** read those docs here. Instead, **delegate the heavy
-reading to the `context-primer` subagent**, which reads them in *its own* context and
-returns a small distilled briefing. Preflight (Step 3) has already released the kickoff
-gate, so spawning a subagent is now permitted.
-
-Spawn it with the `Agent` tool (`subagent_type: context-primer`) and pass:
-- `TEAM_REPO` (the resolved path),
-- the **full `kickoff-preflight` JSON** from Step 3 (it contains `reads[]`, `clientScope`,
-  `standards`, `client`, `estimate`),
-- the developer's one-line task description.
+## Step 4 — Prime the team knowledge base FIRST, via the `context-primer` subagent
+
+> 🛑 **THIS IS THE FIRST RESEARCH YOU DO — NOT OPTIONAL, NOT PARALLELIZABLE.**
+> After the interview, the team knowledge base is the **first source you prime from, before
+> ANY other research.** You may **not** read repo code, `Grep`/`Glob` the source, spawn any
+> other agent, or open a file **named in the `/kickoff` sentence** until the `context-primer`
+> subagent has **returned its briefing.** Preflight (Step 3) did **not** release the gate — it
+> advanced it to stage 2, and **spawning the foreground `context-primer` is what releases it.**
+> The team KB is the team's distilled, shared gold: skipping it, or side-channeling it (running
+> the primer in the background while you read code in parallel), is the exact failure this gate
+> exists to prevent — do neither.
+
+**This is also the token-discipline core of kickoff.** Reading every architecture + feature +
+standard + client doc *into this conversation* bloats the thread and trips compaction later. So
+you do **not** read those docs here — you **delegate the heavy reading to the `context-primer`
+subagent**, which reads them in *its own* context and returns a small distilled briefing.
+
+Spawn it with the `Agent` tool and **wait for it**:
+- `subagent_type: context-primer`,
+- **`run_in_background: false`** — foreground, so you MUST wait for the briefing before doing
+  anything else; a backgrounded primer running while you read code is precisely the violation,
+- pass it: `TEAM_REPO` (the resolved path), the **full `kickoff-preflight` JSON** from Step 3
+  (`reads[]`, `clientScope`, `standards`, `client`, `estimate`), and the developer's one-line
+  task description.
 
 The primer returns a `## Primer` block (critical rules, task-relevant knowledge + gotchas,
 client variations, gaps) plus a `## Doc map`. **Keep only that briefing as your context for