@jenga-ai/agent 1.2.4 → 2.0.0

package/agents/tester.md

@@ -155,7 +155,7 @@ When invoked to implement and/or run tests:
    e. Only after all DoD checkboxes are ticked (`- [x]`) may you proceed to step 7.
 7. Evaluate results and set the scrum board status accordingly (see Status Management)
 8. Trigger epic/story rollup if applicable (see Rollup Logic)
-9. If there are unresolved findings, write a test rapport (see Rapport System)
+9. If there are unresolved findings, write a test rapport (see Rapport System) — **unless** the finding is clearly mechanical, in which case fix it in place instead; see "Trivial-Fix-Path (mechanical issues)" below before defaulting to a rapport.
 10. Report back with one of:
     - `"passed"` — all tests passed, no findings
     - `"passed with remarks"` — tests passed but findings exist; reference the rapport
@@ -163,6 +163,52 @@ When invoked to implement and/or run tests:
 
 Always include the sender object in the response.
 
+### Trivial-Fix-Path (mechanical issues)
+
+**Trigger.** During steps 4-6 of "Invoked for test implementation and/or execution" above, you find a defect. Before defaulting to step 9's rapport path, classify it: is this **mechanical** (safe to fix in place) or does it **need a rapport** (a design decision or real risk is involved)? This classification is what determines which of the two remediation paths below you take — it is not optional bookkeeping, and it happens at the moment the defect is found, not retroactively.
+
+**Motivating case.** `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md` Finding 3: the tester found `skills/dev-done/scripts/classify-commit-outcome.sh` committed without its executable bit (`chmod +x`) plus a dead, unreachable error branch. Both were one-line-class fixes, but the only path available at the time was the full formal one — a `test_failure` rapport, a separate developer fix commit, a re-verification pass, and a second complete `j:self-sync` mirror run. That produced 3 of the task's 6 total commits for defects that needed no design judgment at all. This subsection exists so that pattern doesn't repeat.
+
+**Qualifying examples (mechanical — fix in place).**
+- A missing executable bit or other permission-bit error (e.g. a script committed without `chmod +x`) — the exact E42_S04 Finding 3 case.
+- An unreachable/dead code branch that you have **directly exercised and confirmed dead** (not merely suspected) — e.g. an error-handling branch whose triggering condition can never occur given the surrounding logic, verified by tracing the actual call path, as in the second half of the E42_S04 Finding 3 case.
+- A pure formatting slip with no behavior change — stray whitespace, a missing trailing newline, a lint-only violation that doesn't alter what the code does.
+
+**Disqualifying examples (still needs a rapport — unaffected by this section).**
+- Anything touching business logic — a conditional, a calculation, a control-flow change that affects output.
+- Anything security-sensitive — auth, permissions checks (beyond a bare file-mode bit), input validation, secret handling.
+- Anything touching data handling — persistence, migrations, data shape, serialization.
+- Anything touching the shape of a public API, schema, or frontmatter contract.
+- Anything requiring a judgment call about what the intended behavior actually is — if you have to guess at intent to decide the "right" fix, it is not mechanical.
+
+When in doubt, treat the defect as disqualifying. The bar for "mechanical" is narrow on purpose — this path is an exception carved out of the rapport system, not a replacement for it.
+
+**In-place fix mechanism.** Make the minimal fix directly in the worktree you are verifying, and commit it there. This follows the same rule already established in "Verification commit target" below: the commit lands on the branch under verification, in that task's worktree, never on `main` or any other branch — confirm with `git branch --show-current` before committing, same as any other verification-time commit. Use the same commit message convention used elsewhere in this file for verification-time fixes, e.g. `chore(<E##_S##_T##>): trivial fix — <short description>`.
+
+**Audit trail.** A qualifying fix is never silent, even though no rapport is filed. Do both of the following:
+1. Append an event to `project/logs/events.json` with this shape, consistent with the file's existing `advisory_checkpoint`/`tool_approval` event shapes:
+
+```json
+{
+  "event": "trivial_fix",
+  "agent": "tester",
+  "session_id": "<current session id>",
+  "task_id": "<E##_S##_T##>",
+  "story_id": "<E##_S##>",
+  "epic_id": "<E##>",
+  "commit_sha": "<sha of the in-place fix commit>",
+  "issue": "<what was found, e.g. 'missing chmod +x on scripts/foo.sh'>",
+  "note": "<one-line justification for why this qualifies as mechanical>",
+  "date": "<ISO 8601 UTC timestamp>"
+}
+```
+
+2. Include a one-line note about the fix in whatever status/commit output you produce for this task (step 10's report, and the status note recorded per Status Management), so the fix is visible even to someone who never opens `events.json`.
+
+**No rapport, no rework.** A qualifying trivial fix does **not** trigger a `test_failure` rapport and does **not** trigger a developer rework cycle. Verification simply continues from where it left off — proceed to step 7 (status evaluation) as if the defect had not blocked anything, with the fix itself noted per the audit trail above. Do not pause, do not hand back to the developer, do not wait for confirmation.
+
+**No regression for anything else.** Anything that doesn't clearly qualify — including anything you're unsure about — is completely unaffected by this section: it goes through the existing rapport → rework cycle exactly as documented in "Test rapports (unresolved findings)" below, unchanged.
+
 ### Crucial Tier: `advisory`
 
 **Trigger.** The task being verified — or its parent story — carries `crucial_level: advisory` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
@@ -212,11 +258,11 @@ Append this as a new array entry — never overwrite existing log content. This
 
 **Trigger.** The task being verified — or its parent story — carries `crucial_level: locked` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
 
-**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `/jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03). As tester, verify this field is actually `inline` on any `locked` item you're validating — a value that slipped through would itself be a defect worth flagging.
+**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j:jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03). As tester, verify this field is actually `inline` on any `locked` item you're validating — a value that slipped through would itself be a defect worth flagging.
 
-**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `/jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
+**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j:jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
 
-**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `/do` guards above) before the developer ever begins work — none of this depends on you noticing or remembering anything mid-verification. Your only obligation is to recognize that a `locked` task always runs (and was always verified) in the current foreground session, and to never suggest or perform a workaround that would route around that guarantee. If you find evidence during verification that a `locked` item was actually run in a backgrounded or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to silently pass.
+**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j:do` guards above) before the developer ever begins work — none of this depends on you noticing or remembering anything mid-verification. Your only obligation is to recognize that a `locked` task always runs (and was always verified) in the current foreground session, and to never suggest or perform a workaround that would route around that guarantee. If you find evidence during verification that a `locked` item was actually run in a backgrounded or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to silently pass.
 
 ### Invoked for analysis or comparison testing
 When invoked to run an analysis or comparison:
@@ -407,6 +453,24 @@ There is no default analytics run. Analytics only happen when explicitly scoped
 
 ---
 
+## Investigative Mode
+
+**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `j:uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
+
+**Hard constraints.** Investigative Mode is strictly read-only:
+- No worktree is created for write purposes, no test files are written or modified, no test runs that mutate state, no dependency installs.
+- No commits of any kind.
+- No board status writes — this mode doesn't touch task/story/epic status at all, even though status writes are ordinarily your exclusive responsibility.
+- No edits to `PROJECT_SUMMARY.md`, board files, or any other project artifact. The only output is the trace itself, returned to whoever dispatched you.
+
+**Sandbox — reuse the existing worktree hooks, read-only.** Per the story decision behind this mode (see `project/documentation/plans/uncharted-interactive-elicitation.md` and its solution assessment, Problem 7 / Solution A), do not invent a new isolation mechanism. Mount a throwaway worktree via the same `WorktreeCreate` hook the developer agent uses for normal tasks, purely to get a disposable, isolated checkout to read from, and tear it down via `WorktreeRemove` once the investigation ends. This is convention-enforced, not filesystem-enforced: the hook mounts an ordinary writable worktree, and it is Investigative Mode's contract — not a permission bit — that keeps it read-only. Do not execute the test suite in a way that writes fixtures, snapshots, or coverage artifacts back into that worktree; reading existing test files and existing coverage output (if already present) is the mode's ceiling.
+
+**What you trace — the distinct vantage point.** Where the developer's Investigative Mode pass traces what the code *does*, yours traces what the test suite *actually exercises and verifies* for that same flow: which tests touch it, what they assert (and what they merely execute without asserting), and where the coverage gap is — untested branches, unasserted side effects, error paths with no test at all, or a flow that "passes" only because nothing checks the part that matters. These are two distinct vantage points on the same flow, not two names for the same read; do not simply restate the developer's trace with "and there's a test for it" appended.
+
+**Human-oracle-availability limitation.** The same limitation the developer faces applies to you, with an added facet: a passing test suite doesn't clarify intent either — a test can be green because it correctly verifies the right behavior, or green because it asserts nothing meaningful, and the test's own docstring or name can be as misleading as the code's. When you cannot determine from the tests (or their absence) what the intended behavior actually is, say so explicitly — report the uncertainty and the specific gap you couldn't close, rather than presenting a guess as a settled coverage verdict. This is an accepted, standing limitation of the mode, not something to engineer around by fabricating confidence.
+
+---
+
 ## Hooks
 
 Defined in agent frontmatter:

package/hooks/on_session_end.sh

@@ -308,6 +308,33 @@ for HANDOFF_FILE in "$HANDOFF_DIR"/*.json; do
         echo "$TRIGGER" >> "$DEV_QUEUE"
         echo "[on_session_end] scrum-master → developer queue: implementation_assignment"
       fi
+
+      # A conversational architecture elicitation session (/uncharted
+      # onboard's default flow, or segment --mode investigate — E20_S08_T03)
+      # ended mid-run without converging. The session driving it is
+      # responsible for calling skills/uncharted/scripts/elicitation-state.sh
+      # pause and then writing this handoff with status "elicitation_paused"
+      # as its last action (see skills/uncharted/SKILL.md's Multi-Session
+      # Persistence subsection). This routes that pause into a resume
+      # signal for the next scrum-master session, per the existing
+      # SessionEnd/queue pattern rather than a new persistence mechanism
+      # (solution-assessment-uncharted-interactive-elicitation.md, Problem 11).
+      if [ "$HANDOFF_STATUS" = "elicitation_paused" ]; then
+        TRIGGER=$(jq -n \
+          --slurpfile h "$HANDOFF_FILE" \
+          --arg type "elicitation_resume" \
+          --arg date "$TIMESTAMP" \
+          '{
+            type: $type,
+            date: $date,
+            sender: { agent: "scrum-master", session_id: $h[0].session_id, date: $date },
+            elicitation_id: ($h[0].elicitation_id // ""),
+            state_file:     ($h[0].state_file     // ""),
+            message: "A conversational architecture elicitation session paused mid-run. Resume it from the persisted state file."
+          }')
+        echo "$TRIGGER" >> "$QUEUE_FILE"
+        echo "[on_session_end] scrum-master (elicitation_paused) → scrum-master queue: elicitation_resume"
+      fi
       ;;
 
     developer)
@@ -386,4 +413,16 @@ done
 # --- 5. Todo cleanup ---
 # Remove project/todo.md if it is effectively empty (only blanks, # Todo, and HTML comments).
 # Runs unconditionally on every session end regardless of agent type.
-bash "$PROJECT_DIR/scripts/todo_cleanup.sh"
+bash "$PROJECT_DIR/scripts/todo_cleanup.sh"
+
+# --- 6. Stale resolved_context digest sweep (E49_S01_T02) ---
+# Backstop cleanup for project/queue/context/ digest files. The primary
+# cleanup path is scripts/consume-context-digest.sh, called by the receiving
+# subagent once it has read its digest — this sweep only catches a digest
+# whose intended receiver never consumed it (abandoned dispatch, or a
+# receiver that read the raw file directly and forgot to delete it). Age-based
+# rather than routed-and-deleted-immediately like section 4 above, because a
+# digest's consumer is a later session that may not have started yet when
+# THIS session ends — see scripts/sweep-stale-context-digests.sh's header for
+# the full rationale. Runs unconditionally, same as todo cleanup above.
+bash "$PROJECT_DIR/scripts/sweep-stale-context-digests.sh"

package/lib/generate-agent-context.js

@@ -29,6 +29,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { readSkillAllowList } from "./generate-skill-allow-list.js";
 
 // This file lives at <package>/lib/generate-agent-context.js — one level up
 // is the installed jenga-agent package root, which holds templates/.
@@ -76,6 +77,20 @@ function buildSkillList(projectRoot) {
   return skillLines.length > 0 ? skillLines.join("\n") : "_No skills found._";
 }
 
+/**
+ * Build the rendered {{ALLOWED_SKILL_IDS}} block: the canonical, committed
+ * `lib/skill-allow-list.json` artifact (E50_S02_T01/T02), rendered as a
+ * compact comma-joined inline-code list for the "Skill Identifier
+ * Allow-List" section of the generated context files (E50_S02_T04). Reads
+ * via the shared readSkillAllowList() helper — never re-derives its own
+ * scan of skills/, so this list always matches the artifact the MCP router
+ * (E50_S02_T03) and postinstall/self-sync regeneration also read from.
+ */
+function buildAllowedSkillIds(projectRoot, packageRoot) {
+  const ids = readSkillAllowList(projectRoot, packageRoot);
+  return ids.length > 0 ? ids.map((id) => `\`${id}\``).join(", ") : "_No skills found._";
+}
+
 function resolveTemplatePath(projectRoot, packageRoot) {
   const candidates = [
     join(packageRoot, "templates", "agent-context.md.tpl"),
@@ -167,13 +182,15 @@ export function generateAgentContext(projectRoot = process.cwd(), packageRoot =
 
   const tpl = readFileSync(tplPath, "utf8");
   const skillList = buildSkillList(projectRoot);
+  const allowedSkillIds = buildAllowedSkillIds(projectRoot, packageRoot);
   const written = [];
 
   for (const target of TARGETS) {
     const rendered = tpl
       .split("{{TARGET_FILENAME}}").join(target.filename)
       .split("{{SKILL_DISCOVERY_PATH}}").join(target.skillDiscoveryPath)
-      .split("{{SKILL_LIST}}").join(skillList);
+      .split("{{SKILL_LIST}}").join(skillList)
+      .split("{{ALLOWED_SKILL_IDS}}").join(allowedSkillIds);
 
     const targetPath = join(projectRoot, target.filename);
     const jFilename = `J-${target.filename}`;

package/lib/generate-copilot-instructions.js

@@ -33,6 +33,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { readSkillAllowList } from "./generate-skill-allow-list.js";
 
 // This file lives at <package>/lib/generate-copilot-instructions.js — one level up is the
 // installed jenga-agent package root, which holds templates/.
@@ -72,6 +73,19 @@ function buildSkillList(skillsDir) {
   return skillLines.length > 0 ? skillLines.join("\n") : "_No skills found._";
 }
 
+/**
+ * Build the rendered {{ALLOWED_SKILL_IDS}} block: the canonical, committed
+ * `lib/skill-allow-list.json` artifact (E50_S02_T01/T02), rendered as a compact comma-joined
+ * inline-code list for the "Routing decision table" allow-list check (E50_S02_T04). Reads via
+ * the shared readSkillAllowList() helper — never re-derives its own scan of a skills
+ * directory, mirroring the sibling buildAllowedSkillIds in lib/generate-agent-context.js so
+ * both routing paths share the one committed artifact.
+ */
+function buildAllowedSkillIds(projectRoot, packageRoot) {
+  const ids = readSkillAllowList(projectRoot, packageRoot);
+  return ids.length > 0 ? ids.map((id) => `\`${id}\``).join(", ") : "_No skills found._";
+}
+
 /**
  * Replace only the JENGA:START..JENGA:END block in an existing copilot-instructions.md with the
  * freshly rendered one, preserving everything outside the markers. If no existing file, write
@@ -129,7 +143,10 @@ export function generateCopilotInstructions(
     ? (skillsDir.startsWith("/") ? skillsDir : join(projectRoot, skillsDir))
     : undefined;
   const skillList = buildSkillList(resolvedSkillsDir);
-  const rendered = tpl.replace("{{SKILL_LIST}}", skillList);
+  const allowedSkillIds = buildAllowedSkillIds(projectRoot, packageRoot);
+  const rendered = tpl
+    .replace("{{SKILL_LIST}}", skillList)
+    .replace("{{ALLOWED_SKILL_IDS}}", allowedSkillIds);
 
   const githubDir = join(projectRoot, ".github");
   const copilotInstructionsPath = join(githubDir, "copilot-instructions.md");

package/lib/generate-skill-allow-list.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * lib/generate-skill-allow-list.js — canonical skill allow-list generator
+ *
+ * Single source of truth for the `j:`-prefix anti-masquerading guard (E50_S02). Scans a skills
+ * directory for every `<name>/SKILL.md`, extracts each one's canonical `name:` frontmatter
+ * identifier, and writes a sorted, de-duplicated JSON artifact to `lib/skill-allow-list.json`.
+ *
+ * Why this exists: E50_S02's guard checks whether a `j:`-prefixed invocation matches a known
+ * list of genuine Jenga skill identifiers before treating it as trusted (see
+ * docs/skill-authoring.md's "Threat Model — the j: Allow-List Guard" section, landed by
+ * E50_S02_T05, for the guard's exact scope boundary). Every routing path that enforces that
+ * guard — the MCP router (E50_S02_T03) and native/prose routing enforcement (E50_S02_T04) — must
+ * read from this single artifact rather than re-deriving its own scan of `skills/`, mirroring the
+ * drift lesson already documented in E41_S04 (CLAUDE.md and AGENT.md hand-maintained skill lists
+ * had already drifted from each other before that epic unified them onto one generator).
+ *
+ * This module only builds the generator and produces the one-time committed artifact.
+ * Auto-regeneration at `/self-sync`/postinstall time is wired up separately by the follow-up
+ * task E50_S02_T02 — not in scope here.
+ *
+ * Consumers:
+ *   - CLI guard at the bottom of this file (`node lib/generate-skill-allow-list.js`) — run once
+ *     against this repo's own skills/ to produce the committed lib/skill-allow-list.json, and
+ *     intended to be callable from skills/self-sync/scripts/run.js and scripts/postinstall.js in
+ *     the follow-up task.
+ *   - getSkillAllowListIdentifiers() — an in-memory-only helper for callers that want the
+ *     identifier list without touching disk, e.g. the MCP router work in E50_S02_T03.
+ *
+ * ESM, Node built-ins only — mirrors lib/generate-agent-context.js and
+ * lib/generate-copilot-instructions.js.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// This file lives at <package>/lib/generate-skill-allow-list.js — one level up is the repo/
+// package root, which holds skills/.
+const DEFAULT_SKILLS_DIR = join(__dirname, "..", "skills");
+const DEFAULT_OUTPUT_PATH = join(__dirname, "skill-allow-list.json");
+const DEFAULT_PACKAGE_ROOT = join(__dirname, "..");
+
+/**
+ * Extract the `name:` frontmatter field from a SKILL.md's content. Only the scalar `name` field
+ * is needed here (unlike mcp/router/skill-index.js's fuller frontmatter parser, which also
+ * handles array fields like `keywords`/`examples`) — a direct regex against the frontmatter
+ * block is sufficient and avoids re-implementing that broader parser for a single field.
+ */
+function extractName(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  const nameMatch = fmMatch[1].match(/^name:\s*(.+)$/m);
+  if (!nameMatch) return null;
+  const rawName = nameMatch[1].trim().replace(/^["']|["']$/g, "");
+  // Frontmatter may carry either the pre-E50_S01 bare form or the post-rename "j:<name>" form
+  // (skills/*/SKILL.md was migrated in E50_S01_T02) — strip the prefix so the allow-list always
+  // holds bare identifiers, matching mcp/router/skill-index.js's `bareName` handling.
+  return rawName.replace(/^j:/i, "");
+}
+
+/**
+ * Scan `skillsDir` for every immediate `<name>/SKILL.md` and return a sorted, de-duplicated
+ * array of canonical skill identifiers (the frontmatter `name` value, treated as authoritative
+ * per docs/skill-authoring.md's "name must match the directory name" authoring rule — this
+ * function does not itself verify that match, only that `name` is present).
+ *
+ * A SKILL.md missing the `name` field is skipped with a warning, not fatal — mirrors
+ * mcp/router/skill-index.js's buildSkillIndex warning behavior for consistency across the two
+ * scanners.
+ *
+ * No disk write. Pure in-memory scan, for callers (e.g. the MCP router, E50_S02_T03) that want
+ * the identifier list without reading the generated artifact.
+ *
+ * @param {string} skillsDir - directory to scan (default: this repo/package's own skills/)
+ * @returns {string[]} sorted, de-duplicated skill identifiers
+ */
+export function getSkillAllowListIdentifiers(skillsDir = DEFAULT_SKILLS_DIR) {
+  if (!existsSync(skillsDir)) return [];
+
+  const identifiers = new Set();
+
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const skillMdPath = join(skillsDir, entry.name, "SKILL.md");
+    if (!existsSync(skillMdPath)) continue;
+
+    let content;
+    try {
+      content = readFileSync(skillMdPath, "utf8");
+    } catch (e) {
+      process.stderr.write(`Warning: failed to read ${skillMdPath}: ${e.message} — skipped\n`);
+      continue;
+    }
+
+    const name = extractName(content);
+    if (!name) {
+      process.stderr.write(`Warning: ${skillMdPath} has no 'name' in frontmatter — skipped\n`);
+      continue;
+    }
+
+    identifiers.add(name);
+  }
+
+  return [...identifiers].sort();
+}
+
+/**
+ * Read the committed skill-allow-list.json artifact (produced by generateSkillAllowList /
+ * regenerated by postinstall.js and skills/self-sync/scripts/run.js) and return its `skills`
+ * array. Resolution order mirrors resolveTemplatePath's packageRoot-then-projectRoot candidate
+ * order in lib/generate-agent-context.js and lib/generate-copilot-instructions.js: the artifact
+ * normally lives at `<packageRoot>/lib/skill-allow-list.json` (the installed jenga-agent
+ * package's own committed copy), with `<projectRoot>/lib/skill-allow-list.json` as a fallback
+ * for the case where this repo IS the project (e.g. this monorepo's own dogfood run).
+ *
+ * This is the single read path both E50_S02_T04 generators (native Claude Code context files
+ * and Copilot/Codex prose-routing instructions) use to render the "trusted identifiers" list —
+ * neither one re-derives its own scan of skills/, per the drift lesson already documented in
+ * E41_S04 and referenced in this module's header comment.
+ *
+ * @param {string} projectRoot - project root directory
+ * @param {string} packageRoot - installed jenga-agent package root (default: this module's own
+ *   package root)
+ * @returns {string[]} the artifact's `skills` array, or [] if the artifact is missing/unparseable
+ */
+export function readSkillAllowList(projectRoot, packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const candidates = [
+    join(packageRoot, "lib", "skill-allow-list.json"),
+    join(projectRoot, "lib", "skill-allow-list.json"),
+  ];
+  const path = candidates.find(existsSync);
+  if (!path) return [];
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(parsed.skills) ? parsed.skills : [];
+  } catch (e) {
+    process.stderr.write(`Warning: failed to read/parse ${path}: ${e.message} — treating allow-list as empty\n`);
+    return [];
+  }
+}
+
+/**
+ * Generate the canonical skill allow-list artifact at `outputPath`.
+ *
+ * The `skills` array is deterministic — sorted and de-duplicated, so repeat runs with no
+ * `skills/` change produce a byte-identical array. `generated_at` is NOT deterministic (it is a
+ * fresh timestamp on every run) — that is expected and intentional, not a bug: only the `skills`
+ * array itself is contracted to be stable.
+ *
+ * @param {string} skillsDir - directory to scan (default: this repo/package's own skills/)
+ * @param {string} outputPath - where to write the JSON artifact (default: lib/skill-allow-list.json)
+ * @returns {{written: boolean, path: string, skill_count: number}}
+ */
+export function generateSkillAllowList(skillsDir = DEFAULT_SKILLS_DIR, outputPath = DEFAULT_OUTPUT_PATH) {
+  const skills = getSkillAllowListIdentifiers(skillsDir);
+
+  const artifact = {
+    generated_at: new Date().toISOString(),
+    skill_count: skills.length,
+    skills,
+  };
+
+  const outDir = dirname(outputPath);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+
+  writeFileSync(outputPath, JSON.stringify(artifact, null, 2) + "\n", "utf8");
+
+  return { written: true, path: outputPath, skill_count: skills.length };
+}
+
+// CLI guard — allows `node lib/generate-skill-allow-list.js [skillsDir] [outputPath]`, intended
+// to be callable from skills/self-sync/scripts/run.js and scripts/postinstall.js in the
+// follow-up auto-regeneration task (E50_S02_T02).
+//
+// process.argv[1] is compared via realpath, not as a raw string — see the identical comment
+// block in lib/generate-agent-context.js for why: Node resolves import.meta.url through symlinks
+// when loading an ES module, but leaves process.argv[1] exactly as the shell passed it, so an
+// invocation from a path under a symlinked directory (e.g. macOS's /tmp -> /private/tmp) would
+// otherwise silently fail this comparison and skip generation with no error.
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  const skillsDirArg = process.argv[2] || DEFAULT_SKILLS_DIR;
+  const outputPathArg = process.argv[3] || DEFAULT_OUTPUT_PATH;
+  const result = generateSkillAllowList(skillsDirArg, outputPathArg);
+  console.log(`✓ ${result.path} (${result.skill_count} skills)`);
+}

package/lib/skill-allow-list.json

@@ -0,0 +1,43 @@
+{
+  "generated_at": "2026-09-04T00:52:12.012Z",
+  "skill_count": 37,
+  "skills": [
+    "brainstorm",
+    "btw",
+    "clearify",
+    "close-story",
+    "commit",
+    "continue",
+    "deep-dive",
+    "dev-done",
+    "distribute",
+    "do",
+    "doc",
+    "doc-sync",
+    "dooo",
+    "error",
+    "evaluate",
+    "examplify",
+    "help",
+    "idea",
+    "improve",
+    "init",
+    "j-init",
+    "jbp",
+    "jenga",
+    "jenga-permission-level",
+    "lgtm",
+    "pi-plan",
+    "proceed",
+    "publish",
+    "reconcile",
+    "reconcile-origin",
+    "redo",
+    "skillify",
+    "spinoff",
+    "status",
+    "todo",
+    "uncharted",
+    "wtf"
+  ]
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.2.4",
-  "description": "Structured multi-agent development workflow for AI coding agents — scrum board, role-bounded scrum master / developer / tester agents, and 30+ slash-command skills. Works with Claude Code, GitHub Copilot, and Codex.",
+  "version": "2.0.0",
+  "description": "Structured multi-agent development workflow for AI coding agents \u2014 scrum board, role-bounded scrum master / developer / tester agents, and 30+ slash-command skills. Works with Claude Code, GitHub Copilot, and Codex.",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "jenga": "./bin/jenga.js"
+    "jenga": "bin/jenga.js"
   },
   "engines": {
     "node": ">=14.13.1"
@@ -16,12 +16,12 @@
     "postinstall": "node scripts/postinstall.js",
     "test": "bats tests/*.bats",
     "validate:npm-metadata": "bash scripts/validate_npm_metadata.sh",
-    "ui:dev": "npm run ui:dev --prefix project/app",
-    "ui:build": "npm run ui:build --prefix project/app",
-    "api:start": "npm run api:start --prefix project/app",
-    "api:dev": "npm run api:dev --prefix project/app",
-    "dashboard:start": "npm run dashboard:start --prefix project/app",
-    "dashboard:open": "npm run dashboard:open --prefix project/app"
+    "ui:dev": "npm run ui:dev --prefix project/app --",
+    "ui:build": "npm run ui:build --prefix project/app --",
+    "api:start": "npm run api:start --prefix project/app --",
+    "api:dev": "npm run api:dev --prefix project/app --",
+    "dashboard:start": "npm run dashboard:start --prefix project/app --",
+    "dashboard:open": "npm run dashboard:open --prefix project/app --"
   },
   "files": [
     "skills/",
@@ -31,7 +31,17 @@
     "templates/",
     "bin/",
     "lib/",
-    "mcp/",
+    "mcp/execute-ticket/*.js",
+    "mcp/execute-ticket/package.json",
+    "mcp/help/*.js",
+    "mcp/help/package.json",
+    "mcp/router/*.js",
+    "mcp/router/package.json",
+    "mcp/router/package-lock.json",
+    "mcp/router/README.md",
+    "mcp/training_runner/*.js",
+    "mcp/training_runner/package.json",
+    "mcp/training_runner/package-lock.json",
     "README.md",
     "LICENSE"
   ],
@@ -59,7 +69,21 @@
     "skills",
     "project-management",
     "developer-tools",
-    "cli"
+    "cli",
+    "jenga",
+    "jenga-ai",
+    "ai-coding",
+    "ai-coding-agent",
+    "coding-agent",
+    "coding-agents",
+    "ai-workflow",
+    "coding-workflow",
+    "development-workflow",
+    "software-development",
+    "developer-workflow",
+    "ai-framework",
+    "agentic-engineering",
+    "ai-engineering"
   ],
   "author": {
     "name": "Samwel Munga",
@@ -67,15 +91,6 @@
     "url": "https://knappkod.se/jenga-ai"
   },
   "license": "MIT",
-  "dependencies": {
-    "@huggingface/transformers": "^4.2.0"
-  },
-  "overrides": {
-    "sharp": "^0.34.5"
-  },
-  "comments": {
-    "audit": "sharp <0.35.0 and adm-zip <0.6.0 are transitive deps of @huggingface/transformers with no upstream fix available. Not exploitable in this context: only text feature-extraction pipeline is used — no image processing or ZIP handling at application boundary. Review when @huggingface/transformers ships a patched release."
-  },
   "devDependencies": {
     "bats": "^1.13.0"
   }