@marcomigozzi/trailhead 0.4.0 → 0.5.1

package/plugins/trailhead/hooks/trailhead-install-guard.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// trailhead-install-guard.js: PreToolUse(Bash) hook.
+// Slopsquatting barrier. trailhead's executor/fix agents can install packages
+// (npm / PyPI / crates.io / Go / RubyGems) while resolving a ticket, so a
+// hallucinated or typosquatted package NAME could be fetched silently. This gate
+// BLOCKS any public-registry install that names a package until the agent has
+// vetted the name, then instructs it to verify legitimacy (typosquat similarity,
+// package age, download counts, repo metadata) and checkpoint the human on a
+// suspicious result (block-and-ask). A vetted install proceeds by re-running the
+// command prefixed with the sentinel `TRAILHEAD_VERIFIED_INSTALL=1`.
+// Only a NAMED install is gated: lockfile/manifest installs (bare `npm install`,
+// `npm ci`, `pip install -r`, `cargo build`, `go mod download`, `bundle install`)
+// and local paths / URLs / VCS refs carry no typed name and pass through.
+// Blocks with exit 2 + {"decision":"block",...}; allows everything else.
+// Crash-safe: any error → exit 0 (never wedge the user's workflow).
+// Self-contained, no dependencies. Pure functions exported for tests; runs as a
+// hook when executed directly.
+
+const SENTINEL = /(?:^|\s)TRAILHEAD_VERIFIED_INSTALL=1(?:\s|$)/;
+
+// Per-ecosystem: the binaries that own it, and the install verbs that fetch a
+// named package. `add` covers pnpm/yarn/bun/uv/poetry/cargo; `install`/`i` npm
+// and pip; `get`/`install` go.
+const ECOSYSTEMS = {
+  npm: { bins: ['npm', 'pnpm', 'yarn', 'bun'], verbs: ['install', 'i', 'add'] },
+  pip: { bins: ['pip', 'pip3', 'pipx', 'uv', 'poetry'], verbs: ['install', 'add'] },
+  crates: { bins: ['cargo'], verbs: ['add', 'install'] },
+  go: { bins: ['go'], verbs: ['get', 'install'] },
+  gem: { bins: ['gem'], verbs: ['install'] },
+};
+
+// Flags that consume a SEPARATE-TOKEN value (a file, url, or dir), so that value
+// is never mistaken for a package name (e.g. `pip install -r requirements.txt`).
+const VALUE_FLAGS = new Set([
+  '-r', '--requirement', '-c', '--constraint', '-e', '--editable',
+  '-i', '--index-url', '--extra-index-url', '-f', '--find-links',
+  '-t', '--target', '--prefix', '--root', '--python', '-d', '--dest',
+  '-w', '--workspace', '--registry', '-C', '--directory', '--chdir',
+  '--no-binary', '--only-binary',
+]);
+
+function basename(p) {
+  const s = String(p).split('/');
+  return s[s.length - 1];
+}
+
+// A positional that is NOT a public-registry name: local path, url, vcs ref, or a
+// file artifact. Go module paths (example.com/foo) look url-ish but ARE the named
+// module, so for go only a leading . / ~ disqualifies.
+function isLocalOrUrl(t, ecosystem) {
+  if (t.startsWith('.') || t.startsWith('/') || t.startsWith('~')) return true;
+  if (ecosystem === 'go') return false; // a bare module path is the name; gate it
+  if (t.includes('://')) return true;
+  if (/^(?:git\+|file:|https?:|hg\+|svn\+|bzr\+)/.test(t)) return true;
+  if (/\.(?:tgz|tar\.gz|whl|gz|zip|txt|toml|lock|cfg)$/.test(t)) return true;
+  return false;
+}
+
+// Best-effort bare name for the human-facing reason (detection does not depend on
+// this being exact). Strips pip version specifiers / extras and npm @version.
+function bareName(t) {
+  let n = t.split(/[=<>~!\[]/)[0]; // pip: pkg==1, pkg>=1, pkg[extra]
+  if (n.startsWith('@')) {
+    const at = n.indexOf('@', 1); // scoped @scope/pkg@1 → cut the version @
+    if (at !== -1) n = n.slice(0, at);
+  } else {
+    const at = n.indexOf('@'); // npm pkg@1.2.3
+    if (at !== -1) n = n.slice(0, at);
+  }
+  return n;
+}
+
+// Detect a public-registry install that NAMES at least one package, in a single
+// shell segment. Returns { ecosystem, packages: [names] } or null.
+function detectSegment(cmd) {
+  const toks = String(cmd).trim().split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i])) i++; // env prefix
+  if (i >= toks.length) return null;
+
+  const bin = basename(toks[i]);
+  let ecosystem = null;
+  for (const [name, spec] of Object.entries(ECOSYSTEMS)) {
+    if (spec.bins.includes(bin)) { ecosystem = name; break; }
+  }
+  // `python -m pip install …` → treat as pip.
+  if (!ecosystem && /^python3?$/.test(bin)) {
+    if (toks[i + 1] === '-m' && /^pip3?$/.test(toks[i + 2] || '')) {
+      ecosystem = 'pip';
+      i += 2; // land on `pip`
+    } else {
+      return null;
+    }
+  }
+  if (!ecosystem) return null;
+  i++; // past the binary (or the `pip` peeled above)
+
+  // `uv pip install …` → peel the `pip`.
+  if (bin === 'uv' && toks[i] === 'pip') i++;
+
+  const verb = toks[i];
+  if (!ECOSYSTEMS[ecosystem].verbs.includes(verb)) return null;
+  i++;
+
+  const packages = [];
+  for (let j = i; j < toks.length; j++) {
+    const t = toks[j];
+    if (t.startsWith('-')) {
+      if (VALUE_FLAGS.has(t)) j++; // consume its separate-token value
+      continue;
+    }
+    if (isLocalOrUrl(t, ecosystem)) continue;
+    packages.push(bareName(t));
+  }
+  if (packages.length === 0) return null; // lockfile/manifest install: nothing typed
+  return { ecosystem, packages };
+}
+
+// Agents chain commands (`cd app && npm install foo`), so check every shell
+// segment, not just the first. Split on the common separators (&& || ; | and
+// newlines); a registry name never contains one, so a stray split is harmless.
+// Returns the first segment's hit, or null.
+function detectInstall(cmd) {
+  for (const seg of String(cmd).split(/&&|\|\||;|\n|\|/)) {
+    const hit = detectSegment(seg);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+// The agent's "I have vetted these" acknowledgement.
+function isVerified(cmd) {
+  return SENTINEL.test(String(cmd));
+}
+
+function block(hit) {
+  const list = hit.packages.join(', ');
+  const reason =
+    `trailhead: this ${hit.ecosystem} install names package(s) not yet vetted (${list}). ` +
+    'Guard against slopsquatting before installing: verify each package is legitimate, weighing ' +
+    'name / typosquat similarity to popular packages, package age / first-seen date, download counts / popularity, ' +
+    'and repository metadata (present and matching). ' +
+    'STOP and ask the human on anything suspicious (block-and-ask): do not install on your own judgement. ' +
+    'Once vetted, re-run the exact command prefixed with `TRAILHEAD_VERIFIED_INSTALL=1` to proceed.';
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'UNVETTED_PACKAGE_INSTALL', reason }));
+  process.exit(2);
+}
+
+function run(data) {
+  let cmd = '';
+  try {
+    cmd = (JSON.parse(data).tool_input || {}).command || '';
+  } catch {
+    process.exit(0); // unparseable input: nothing to gate
+  }
+  try {
+    if (isVerified(cmd)) process.exit(0); // agent has vetted these
+    const hit = detectInstall(cmd);
+    if (hit) block(hit);
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends → give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { detectInstall, isVerified };

package/plugins/trailhead/hooks/trailhead-install-guard.test.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Tests for trailhead-install-guard.js. Run: node trailhead-install-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const HOOK = path.join(__dirname, 'trailhead-install-guard.js');
+const { detectInstall, isVerified } = require('./trailhead-install-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Run the hook end-to-end: pipe tool_input JSON on stdin, capture {code, out}.
+function runHook(command) {
+  const input = JSON.stringify({ tool_input: { command } });
+  try {
+    const out = execFileSync('node', [HOOK], { input });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- unit: detectInstall positives (a NAMED public-registry install) ---
+const pos = [
+  ['npm install lodash', 'npm', 'lodash'],
+  ['npm i react', 'npm', 'react'],
+  ['pnpm add vite', 'npm', 'vite'],
+  ['yarn add left-pad', 'npm', 'left-pad'],
+  ['bun add hono', 'npm', 'hono'],
+  ['pip install requests', 'pip', 'requests'],
+  ['pip3 install numpy', 'pip', 'numpy'],
+  ['python -m pip install flask', 'pip', 'flask'],
+  ['python3 -m pip install flask', 'pip', 'flask'],
+  ['uv add httpx', 'pip', 'httpx'],
+  ['uv pip install httpx', 'pip', 'httpx'],
+  ['poetry add django', 'pip', 'django'],
+  ['pipx install black', 'pip', 'black'],
+  ['cargo add serde', 'crates', 'serde'],
+  ['cargo install ripgrep', 'crates', 'ripgrep'],
+  ['go get example.com/foo/bar', 'go', 'example.com/foo/bar'],
+  ['go install golang.org/x/tools/cmd/stringer', 'go', 'golang.org/x/tools/cmd/stringer'],
+  ['gem install rails', 'gem', 'rails'],
+];
+for (const [cmd, eco, name] of pos) {
+  const d = detectInstall(cmd);
+  ok(`detects: ${cmd}`, d && d.ecosystem === eco && d.packages.includes(name));
+}
+
+// Scoped and versioned names are still names (bare name reported).
+ok('detects scoped npm name', (() => { const d = detectInstall('npm install @scope/pkg'); return d && d.packages[0] === '@scope/pkg'; })());
+ok('strips npm @version', (() => { const d = detectInstall('npm install lodash@4.17.21'); return d && d.packages[0] === 'lodash'; })());
+ok('strips pip == specifier', (() => { const d = detectInstall('pip install requests==2.0'); return d && d.packages[0] === 'requests'; })());
+ok('strips pip extra', (() => { const d = detectInstall('pip install requests[security]'); return d && d.packages[0] === 'requests'; })());
+ok('scoped versioned npm keeps scope', (() => { const d = detectInstall('npm install @scope/pkg@1.2.3'); return d && d.packages[0] === '@scope/pkg'; })());
+
+// --- unit: detectInstall negatives (no typed registry name) ---
+const neg = [
+  'npm install',                     // bare: from package.json/lock
+  'npm ci',                          // lockfile install
+  'pip install -r requirements.txt', // requirements file
+  'pip install --requirement req.txt',
+  'pip install -e .',                // editable local
+  'npm install ./local-tarball.tgz', // local path
+  'npm install file:../pkg',         // file: ref
+  'cargo build',                     // not an install verb
+  'go mod download',                 // not get/install
+  'bundle install',                  // unrecognised binary
+  'pip install git+https://github.com/x/y', // vcs url
+  'npm install --save-dev',          // flag only, no name
+  'ls -la',                          // unrelated
+  'go build ./...',                  // not get/install
+];
+for (const cmd of neg) {
+  ok(`ignores: ${cmd}`, detectInstall(cmd) === null);
+}
+
+// `-r`'s value must not be read as a package even with a trailing name absent.
+ok('consumes -r value, no phantom name', detectInstall('pip install -r requirements.txt') === null);
+
+// Compound commands: an install in any segment is caught, not just the first.
+ok('detects install after && chain', (() => { const d = detectInstall('cd app && npm install lodash'); return d && d.packages.includes('lodash'); })());
+ok('detects install after ; chain', (() => { const d = detectInstall('echo hi; pip install requests'); return d && d.packages.includes('requests'); })());
+ok('detects install in a piped tail', (() => { const d = detectInstall('true | cargo add serde'); return d && d.packages.includes('serde'); })());
+ok('compound with no install stays null', detectInstall('cd app && npm run build && ls') === null);
+
+// --- unit: isVerified ---
+ok('sentinel recognised', isVerified('TRAILHEAD_VERIFIED_INSTALL=1 npm install lodash'));
+ok('no sentinel', !isVerified('npm install lodash'));
+
+// --- end-to-end: block ---
+const b1 = runHook('npm install lodash');
+ok('blocks an unvetted named install (exit 2)', b1.code === 2 && /UNVETTED_PACKAGE_INSTALL/.test(b1.out));
+ok('block names the package', /lodash/.test(b1.out) && /"decision":"block"/.test(b1.out));
+const b2 = runHook('pip install some-obscure-pkg');
+ok('blocks a pip named install (exit 2)', b2.code === 2 && /some-obscure-pkg/.test(b2.out));
+
+// --- end-to-end: allow ---
+const a1 = runHook('TRAILHEAD_VERIFIED_INSTALL=1 npm install lodash');
+ok('sentinel allows a vetted install (exit 0)', a1.code === 0 && a1.out.trim() === '');
+const a2 = runHook('npm install');
+ok('bare install allowed (exit 0)', a2.code === 0 && a2.out.trim() === '');
+const a3 = runHook('ls -la');
+ok('non-install allowed (exit 0)', a3.code === 0 && a3.out.trim() === '');
+const a4 = runHook('pip install -r requirements.txt');
+ok('requirements-file install allowed (exit 0)', a4.code === 0 && a4.out.trim() === '');
+
+// --- end-to-end: unparseable stdin allowed ---
+const u = (() => {
+  try {
+    const out = execFileSync('node', [HOOK], { input: 'not json' });
+    return { code: 0, out: out.toString() };
+  } catch (e) { return { code: e.status, out: (e.stdout || '').toString() }; }
+})();
+ok('unparseable stdin allowed (exit 0)', u.code === 0);
+
+console.log(`✓ install-guard: ${passed} assertions passed`);

package/plugins/trailhead/hooks/trailhead-secret-guard.js

@@ -43,8 +43,17 @@ function ghIssueWrite(cmd) {
   let i = 0;
   while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i])) i++; // env prefix
   if (i >= toks.length || !/(^|\/)gh$/.test(toks[i])) return null;         // the gh binary
-  const sub = toks[i + 1];
-  const verb = toks[i + 2];
+  i++;
+  // Skip gh global flags before the subcommand, notably `-R`/`--repo <value>`
+  // (its separate-token value must be consumed too), so `gh -R o/r issue
+  // comment …` is still recognised as a write and gets scanned. Without this a
+  // secret could slip past simply by naming the repo up front.
+  while (i < toks.length && toks[i].startsWith('-')) {
+    if (/^(-R|--repo)$/.test(toks[i]) && !toks[i].includes('=')) i++;
+    i++;
+  }
+  const sub = toks[i];
+  const verb = toks[i + 1];
   if ((sub === 'issue' || sub === 'pr') && ['create', 'comment', 'edit', 'review'].includes(verb)) {
     return sub;
   }
@@ -53,10 +62,16 @@ function ghIssueWrite(cmd) {
 }
 
 // For gh issue/pr, the body may live in a --body-file <path>; read it too.
+// The path is quoted ("..."/'...') or bare. A bare path stops at whitespace AND
+// at shell metacharacters (; | & ( ) < > `): in a compound command like
+// `gh ... --body-file /tmp/x.md; echo done` the `;` abuts the path with no
+// space, so a naive [^\s]+ would swallow it into the filename and the read would
+// ENOENT, turning a clean write into a spurious could-not-scan (and, worse, a
+// real body left unscanned). Quoted paths keep those characters verbatim.
 function bodyFileText(cmd) {
-  const m = cmd.match(/(?:--body-file|(?<![-\w])-F)(?:=|\s+)(["']?)([^\s"']+)\1/);
+  const m = cmd.match(/(?:--body-file|(?<![-\w])-F)(?:=|\s+)(?:"([^"]+)"|'([^']+)'|([^\s"';|&()<>`]+))/);
   if (!m) return '';
-  const path = m[2];
+  const path = m[1] || m[2] || m[3];
   if (path === '-' || path.startsWith('<')) return ''; // stdin/heredoc already in the command string
   return fs.readFileSync(path, 'utf8').slice(0, 1_000_000);
 }

package/plugins/trailhead/hooks/trailhead-secret-guard.test.js

@@ -8,7 +8,7 @@ const fs = require('fs');
 const os = require('os');
 
 const HOOK = path.join(__dirname, 'trailhead-secret-guard.js');
-const { scan, ghIssueWrite } = require('./trailhead-secret-guard.js');
+const { scan, ghIssueWrite, bodyFileText } = require('./trailhead-secret-guard.js');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
@@ -36,7 +36,13 @@ ok('scan passes clean prose', scan('tutto ok, 368 test verdi') === null);
 ok('detects gh issue comment', ghIssueWrite('gh issue comment 5 --body "x"') === 'issue');
 ok('detects gh pr create', ghIssueWrite('gh pr create --body "x"') === 'pr');
 ok('detects gh api body=', ghIssueWrite('gh api repos/o/r/issues/5/comments -f body=x') === 'api');
+ok('detects gh -R o/r issue comment (global flag before subcommand)',
+  ghIssueWrite('gh -R owner/repo issue comment 5 --body x') === 'issue');
+ok('detects gh --repo=o/r pr create (attached global flag)',
+  ghIssueWrite('gh --repo=owner/repo pr create --body x') === 'pr');
 ok('ignores gh issue view (read)', ghIssueWrite('gh issue view 5 --json body') === null);
+ok('ignores gh -R o/r issue view (read, even with global flag)',
+  ghIssueWrite('gh -R owner/repo issue view 5 --json body') === null);
 ok('ignores non-gh commands', ghIssueWrite('echo ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789xx') === null);
 
 // --- end-to-end: block ---
@@ -53,6 +59,40 @@ const b3 = runHook(`gh issue comment 5 --body-file ${leaky}`);
 ok('blocks a secret inside --body-file (exit 2)', b3.code === 2 && /AWS access key/.test(b3.out));
 fs.unlinkSync(leaky);
 
+// --- unit: bodyFileText() path extraction ---
+// A bare path abutting a shell metacharacter in a compound command must NOT
+// swallow the metacharacter into the filename (regression: `.md;` -> ENOENT).
+{
+  const leak = path.join(os.tmpdir(), `sg-meta-${process.pid}.md`);
+  fs.writeFileSync(leak, 'Deploy: AKIAIOSFODNN7EXAMPLE\n');
+  ok('bare path stops at a trailing ; (compound command)',
+    /AKIAIOSFODNN7EXAMPLE/.test(bodyFileText(`gh issue edit 5 --body-file ${leak}; echo done`)));
+  ok('bare path stops at a trailing ) ',
+    /AKIAIOSFODNN7EXAMPLE/.test(bodyFileText(`(gh issue edit 5 --body-file ${leak})`)));
+  ok('bare path still works with a following && and space',
+    /AKIAIOSFODNN7EXAMPLE/.test(bodyFileText(`gh issue edit 5 --body-file ${leak} && echo ok`)));
+  // A quoted path keeps metacharacters verbatim (only the closing quote delimits).
+  const quoted = path.join(os.tmpdir(), `sg;meta-${process.pid}.md`);
+  fs.writeFileSync(quoted, 'Deploy: AKIAIOSFODNN7EXAMPLE\n');
+  ok('quoted path keeps an inner ; in the filename',
+    /AKIAIOSFODNN7EXAMPLE/.test(bodyFileText(`gh issue edit 5 --body-file "${quoted}"`)));
+  fs.unlinkSync(leak);
+  fs.unlinkSync(quoted);
+}
+
+// End-to-end: the compound-command shape that produced the spurious advisory
+// must now scan and BLOCK the real secret in the body.
+const leaky2 = path.join(os.tmpdir(), `sg-leaky2-${process.pid}.md`);
+fs.writeFileSync(leaky2, 'Deploy: AKIAIOSFODNN7EXAMPLE\n');
+const b4 = runHook(`gh issue edit 5 --body-file ${leaky2}; echo done`);
+ok('blocks a secret in --body-file even in a compound command (exit 2)',
+  b4.code === 2 && /AWS access key/.test(b4.out));
+fs.unlinkSync(leaky2);
+
+// A global flag before the subcommand must not let a secret slip past unscanned.
+const b5 = runHook('gh -R owner/repo issue comment 5 --body "t ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789xx"');
+ok('blocks an inline secret behind gh -R (exit 2)', b5.code === 2 && /"decision":"block"/.test(b5.out));
+
 // --- end-to-end: allow ---
 const a1 = runHook('gh issue comment 5 --body "tutto ok, 368 test verdi"');
 ok('allows a clean write (exit 0, no output)', a1.code === 0 && a1.out.trim() === '');

package/plugins/trailhead/skills/{trailhead/references/configuration.md → _shared/configuration-reference.md}

@@ -4,16 +4,18 @@ Effective config = built-in defaults ← global `~/.claude/trailhead/config.json
 
 | Key | Values (default **bold**) | Effect |
 |---|---|---|
-| `models.{plan,execute,research,review,debug}` | a model id (**inherit session**) | model for that activity, see note |
+| `models.{plan,execute,research,review,debug}` | a model id (**Balanced-profile default**) | model for that activity; an unset key resolves to its default **Balanced** tier, see note |
 | `models.codex.{plan,execute,research,review,debug}` | an OpenAI model id (**inherit session**) | per-activity subagent model on **Codex** (OpenAI ids), the honoured namespace there; independent of `models.*` (Claude ids); projected into `~/.codex/agents/trailhead-*.toml` and dispatched by `agent_type`. See note |
 | `ticket.language` | an ISO 639-1 code (**`en`**) | the language trailhead **writes** its GitHub prose in (ticket titles/bodies, engine comments, map body & commit descriptions), see note. Independent of the language the agent converses in |
-| `design` | **`disk`** \| `claude.ai/design` | mode for UI mockups (**Prototype**). `disk` = throwaway local HTML; `claude.ai/design` = push to a **design-system project** via DesignSync (`/design-sync` + `claude_design` MCP), its projectId created/reused at execution and cached in `design.project`. DesignSync drives only design-system projects, not regular ones. **On Codex** `claude.ai/design` **collapses to `disk`** (no `claude_design` MCP / `/design-sync` skill there; local HTML mockups instead), like the `models.*` collapse |
+| `design` | **`disk`** \| `claude.ai/design` \| `stitch` | mode for UI mockups (**Prototype**). `disk` = throwaway local HTML (any host); `claude.ai/design` = create/edit the mockup on claude.ai/design via Anthropic's **official Claude Design MCP** (`claude mcp add --scope user --transport http claude-design https://api.anthropic.com/v1/design/mcp`, auth `/design-login`), **Claude only**; `stitch` = create/edit the mockup via the **Google Stitch MCP** (`claude mcp add --scope user --transport http stitch https://stitch.googleapis.com/mcp`), the **cross-host** hosted option (Claude Code **and** Codex). A hosted mode's projectId is created/reused at execution and cached in `design.project`; which surface it uses is `design.surface`. If the configured mode's MCP isn't connected, Prototype offers a one-time install before falling back (see Prototype). **On Codex** `claude.ai/design` isn't available, so Prototype **offers to switch to `stitch`** (cross-host) before degrading to `disk`; `stitch` and `disk` run on Codex unchanged |
+| `design.surface` | **`canvas`** \| `design-system` | under a hosted `design` mode (`claude.ai/design` or `stitch`), which surface the mockup lives on. `canvas` = a single surface of screens to react to (under `claude.ai/design`: a `/design` **Artifact** or a hand-made web-app project, **not** MCP-created; under `stitch`: a Stitch project), editable visually and exportable as a live prototype. `design-system` = push components into a shared design-system project (a `PROJECT_TYPE_DESIGN_SYSTEM` synced via DesignSync `/design-sync`, or a Stitch design system), for a shared component library. **Back-compat:** unset, a cached `design.project` infers `design-system` (that's what the key meant before this key existed); with no cached project, `canvas`. See Prototype |
 | `design.approval` | **`explicit`** \| `auto` | must a mockup be explicitly approved before the build proceeds to UI code? |
 | `tdd` | **`seams`** \| `on` \| `off` | how the `build` engine tests |
 | `acceptance.browser` | **`auto`** \| `on` \| `off` | how **Acceptance testing** runs |
 | `testing.webapp` / `testing.url` | bool / url | is it browser-drivable, and where |
 | `plan_review` | **`off`** \| `on` \| CLI list (`gemini,codex`) | send `build` PLANs to external AI CLIs for review (**Cross-AI plan review**) |
 | `plan_review.rounds` | integer (**`2`**) | max converge-and-re-review rounds |
+| `code_review.rounds` | integer (**`2`**) | max fix-and-re-review rounds in **Code review** before the boundary HITL checkpoint |
 
 **Models.** Each key targets a specific activity, so you can send the heavy reasoning to a strong model and the cheap legwork to a fast one:
 - `plan` / `execute`: the `build`/`bug` engine's **Plan** and **Execute** steps (see below).
@@ -30,20 +32,36 @@ Effective config = built-in defaults ← global `~/.claude/trailhead/config.json
 
 **Inline update check (hookless hosts).** On a host without a hook bus (the descriptor's `hookBus == 'none'`) the `trailhead-check-update.js` SessionStart hook and the statusline flag are both absent, so the engine does the check **inline at session start**, co-located with the models-collapse notice above. It is lightweight and degrades silently: read the shared cache (`$XDG_CACHE_HOME/trailhead/update-check.json`, the same file the hook writes on Claude Code) and, if it reports an update, surface a one-line notice pointing at `/trailhead:update` (the pure `updateNotice(host, cache)` helper in `bin/lib/host-descriptor.js` is the canonical wording, and returns null on a host that already notifies via the hook, so it never double-fires); if the cache is absent or stale (older than a few hours), do a minimal throttled compare of the installed `VERSION` against the latest (npm registry or the GitHub release, per install channel) and rewrite the cache. Never block or fail the session on a network or parse error. `/trailhead:update` stays the on-demand installer.
 
-If a value is unset, inherit the session model (never hard-fail on an unknown id: warn and inherit).
+If a value is unset, it resolves to its **Balanced**-profile default for that activity (the default profile: a project with no config still gets the Balanced tier per key, resolved to a concrete id at load time, strong → `claude-opus-4-8`, standard → Sonnet-class, fast → Haiku-class). To use the session model instead of the Balanced default, set the key explicitly to `inherit session`. Never hard-fail on an unknown id: warn and inherit the session model.
 
 **Everything else runs in the main session on its own model, there is no key for it:** charting, grilling, naming the destination, framing and **writing the tickets**, graduating fog, and map/decision operations. That's deliberate: it's HITL/orchestration work (you reason *with* the user), so the model that writes a ticket is the one grilling you; it can't fan out to a subagent. Practical upshot: **run a charting session (`/trailhead:new`/`:adopt`/`:ticket`) on your strong model**. The `models.*` keys above govern only the fan-out activities, not the quality of the tickets themselves. **Store a full model id** (e.g. `claude-opus-5`, `claude-fable-5`), never a bare family alias like `opus`; a family now spans several live versions, so an alias can't say which one. **`models.plan` and `models.execute` are always distinct choices**: never collapse them into one shared model pick, even when the user would pick the same id for both.
 
+**Model-tier profiles.** Three profile seeds for the guided setup's Models step (§3), one philosophy: *smart at every level* (research is never the strongest tier; execute and debug are never the fastest). Choosing a profile **applies all five keys directly** (no further per-key questions); the separate **Manual** path is where `plan`/`execute`/the rest are picked one by one. **The default profile is `Balanced`** (the **(consigliato)** one): a project with no config resolves its five model keys as Balanced. **High** and **Low** are the alternatives, and **Manual** lets you set each key yourself (including `inherit session` per key). `fix` follows `execute` and codebase-map follows `research`, so neither needs its own profile entry.
+
+| profile | plan | execute | research | review | debug |
+|---|---|---|---|---|---|
+| **High** | strong | strong | standard | strong | strong |
+| **Balanced** | strong | standard | fast | strong | strong |
+| **Low** | standard | standard | fast | fast | standard |
+
+**Tier-class -> id**, resolved from the lineup actually reachable at setup time (verify, don't trust these verbatim):
+- **Claude** (`models.*`, ids only, no effort): strong = Opus-class, resolved to **`claude-opus-4-8`** by default (the newer `claude-opus-5` stays offered in the per-key menus, but is not the default pick) · standard = Sonnet-class · fast = Haiku-class.
+- **Codex** (`models.codex.*`, `{model, effort}`): strong = `gpt-5.6-sol` @ `high` (debug on **High** may be `xhigh`) · standard = `gpt-5.6-terra` @ `medium` · fast = `gpt-5.6-luna` @ `low`.
+
 **Ticket language.** `ticket.language` (ISO 639-1, default `en`) sets the language trailhead **writes** in on the Issues: ticket titles and bodies, engine comments (DISCUSS/PLAN/VERIFY/OPTIONS/REPRO/DIAGNOSIS/PAUSED/resolution), the map body sections, and commit message **descriptions**. It's fully decoupled from the language the agent *converses* in (its session/global setting); setting `ticket.language` never changes how the agent talks to the user. **Untouched by it:** code and identifiers, the fixed `trailhead:*` label names, config keys/values, and the conventional-commit type prefix (`feat:`/`fix:` stay English). The skill's own source docs (SKILL.md, `references/`) are not project prose and stay English.
 
 **tdd.** `seams` (default) = TDD at critical seams only; `on` = TDD for all behaviour with a definable input→output; `off` = tests after, or none for throwaway. The `build` engine's Plan/Execute honour this.
 
-**acceptance.browser.** `auto` (default) = drive the browser when `testing.webapp` + `testing.url` are set, else fall back to a guided UAT checklist; `on` = always attempt browser-driving; `off` = always hand the human a UAT checklist. **`off` disables *browser-driving*, not acceptance**: a user-facing change still gets a guided UAT checklist (see the Acceptance testing technique). The Verify step honours this.
+**acceptance.browser.** `auto` (default) = drive the browser when `testing.webapp` + `testing.url` are set; when `testing.webapp` is set but `testing.url` is unset, first try to auto-detect the target URL (running dev server, package scripts, dev-server/framework config, project config) and propose it, driving against the accepted URL, and fall back to a guided UAT checklist only when none can be determined; `on` = always attempt browser-driving, auto-detecting the URL the same way when `testing.url` is unset; `off` = always hand the human a UAT checklist. **`off` disables *browser-driving*, not acceptance**: a user-facing change still gets a guided UAT checklist (see the Acceptance testing technique). The Verify step honours this.
+
+**design.surface.** Under `design: claude.ai/design`, which Claude Design surface the mockup lives on. `canvas` (default) = a one-off screen to react to, edited visually and exportable as a live prototype; under `claude.ai/design` it is **not** MCP-driven (no MCP creates a regular canvas project): it's the built-in `/design` skill published as an **Artifact**, or a claude.ai/design project made by hand in the web app whose `/p/<id>` URL you paste. `design-system` = a `PROJECT_TYPE_DESIGN_SYSTEM` project driven by DesignSync (the `/design-sync` slice of the official Claude Design MCP), for a shared component library kept in sync. Unset, it infers from `design.project`: a cached project (which, before this key, was always a design system) means `design-system`; no cached project means `canvas`. The Prototype technique honours this; when the **`design-system`** surface's MCP isn't connected it **offers a one-time install** (`claude mcp add ... claude-design`, then `/design-login`) before falling to disk (the `canvas` surface needs no MCP, so no install offer). Under `design: stitch` the same key applies: `canvas` = a Stitch project with generated screens, `design-system` = a Stitch design system; the install offer and disk fallback work the same way (no intra-provider chain, the Stitch MCP either connects or falls to disk). Ignored under `design: disk`.
 
 **design.approval.** `explicit` (default) = a UI mockup must be **explicitly approved by the user** before the `build` engine writes any real UI code; surface the mockup and wait for a clear go-ahead. `auto` = surface the mockup and proceed without blocking on a confirmation (the user can still object). The Prototype technique honours this.
 
 **plan_review.** `off` (default) = build PLANs are not externally reviewed; `on` = review with every external AI CLI detected on the PATH; a comma list (`gemini,codex`) = only those. Needs the named CLIs installed; if none are available it's skipped, never failed. The `build` engine's Plan step runs **Cross-AI plan review** when this is on.
 
+**code_review.rounds.** Integer, default 2. The max fix-and-re-review rounds the **Code review** technique spends chasing **Critical** (blocking) findings during the `build`/`bug` Verify step. When the budget is exhausted with Critical findings still open, the technique never resolves or continues silently: it surfaces an explicit HITL checkpoint (run another 2 rounds vs proceed with the blockers recorded). Mirrors `plan_review.rounds`.
+
 Example `config.json` (same shape for the project `.trailhead/config.json` and the global `~/.claude/trailhead/config.json`):
 ```json
 { "models": { "plan": "claude-opus-4-8", "execute": "claude-sonnet-5" }, "tdd": "seams", "acceptance": { "browser": "auto" } }
@@ -57,13 +75,15 @@ Example `config.json` (same shape for the project `.trailhead/config.json` and t
 
 1. **Scope**: 🌍 Global default (`~/.claude/trailhead/config.json`) · 📁 This project (`.trailhead/config.json` at the repo root). Skip to global outside a repo.
 2. **🌐 Ticket language**: the language trailhead writes its GitHub prose & commit descriptions in (`ticket.language`, ISO 639-1). Offer 🇬🇧 English (`en`, default) · 🇮🇹 Italiano (`it`) · 🇪🇸 Español (`es`) · 🇫🇷 Français (`fr`) · 🇩🇪 Deutsch (`de`) · 🇵🇹 Português (`pt`), plus a free-code option for any other ISO 639-1 code. Note in the prompt that this is *not* the language the agent converses in.
-3. **🧠 Models**: **always two separate questions, one for `plan` and one for `execute`; never merge them into a single model pick.** Ask each as its own `AskUserQuestion` menu (current value pre-selected), and offer the **same versioned lineup** to both. Each option is a **full model id with its version**; never a bare family alias (`opus`/`sonnet`/`haiku`), which can't say *which* live version. Build the list from the models actually reachable **at setup time** (verify, don't trust this file verbatim), offering **at least the two most recent versions per family**, e.g. `claude-fable-5`, `claude-opus-5` / `claude-opus-4-8`, `claude-sonnet-5` / `claude-sonnet-4-8`, `claude-haiku-4-5`, plus **inherit session** (the default). If that lineup exceeds the menu's option cap, drill **family → version** or include a free-id "Other" so every recent version stays reachable. The rarer `research`/`review`/`debug` sit behind an "Advanced" option, each its own separate choice, same versioned rule.
-   - **Anti-pattern, never do this:** a single screen whose options are *combined* plan+execute presets, e.g. `🧠 Plan 4.8 / Exec Sonnet 5`, `🚀 Tutto Opus 5`, `Plan Opus 5 / Exec Sonnet 5`. That bundles the two decisions into one pick. Forbidden. Plan is asked, answered, and only then is Execute asked, as a second menu. Two questions, two answers, always.
-   - **On Codex (host-detected), ask `models.codex.*` instead of the Claude lineup.** Same discipline: `plan` and `execute` as two separate `AskUserQuestion` menus, never merged; the rarer `research`/`review`/`debug` behind Advanced, each its own choice. Offer OpenAI model ids verified reachable at setup time (do not trust this list verbatim): `gpt-5.6-sol` (flagship) / `gpt-5.6-terra` (balanced) / `gpt-5.6-luna` (fast), plus **inherit session** (default). Avoid the retiring `gpt-5.4` / `gpt-5.4-mini` and the deprecated `gpt-5.3-codex`. Write the answers to `models.codex.*`; the Claude `models.*` lineup is not asked on Codex (those ids cannot run there). After writing, tell the user to **re-run the installer** (the same `--host=codex` install command) so the pins are re-projected into `~/.codex/agents/trailhead-*.toml`: the menu updates `.trailhead/config.json`, the installer is what regenerates the TOMLs and enables `features.multi_agent_v2`.
-4. **🎨 Design**: 💾 Local disk · 🖼️ claude.ai/design (DesignSync → a **design-system** project). *Mode only, don't ask for a URL here; the concrete design-system project is created or reused at execution time via DesignSync, and its projectId cached in `design.project` (see Prototype).* Then **✅ Mockup approval**: 🖐️ Explicit (wait for a go-ahead before UI code) · ⏩ Auto (proceed without blocking).
+3. **🧠 Models**: a **profile** (Balanced by default) applied whole, or **Manual** for the per-key questions.
+   - **🎚️ Profile, asked first (and often the only Models question).** Present one `AskUserQuestion` menu: 🏔️ **High** · ⚖️ **Balanced (consigliato)** · 🍃 **Low** · ✍️ **Manual (specify each model)**. **On a project with no existing config, pre-select ⚖️ Balanced** (the default profile); when a config already exists, pre-select the profile its keys match (or **Manual** when they match none). **On High / Balanced / Low this is terminal:** seed the five model keys from the **Model-tier profiles** table above, resolving each tier-class to a concrete id **at setup time** (verify the lineup, don't trust ids verbatim), **write them, and do NOT ask the per-key questions**. Only **Manual** proceeds to the per-key questions below (where any key may be left at `inherit session`). **Host branch:** on **Claude** the profile seeds `models.*` with tier-class ids; on **Codex** it seeds `models.codex.*` as `{model, effort}` (effort is the Codex-only face), and after applying keep the **re-run the installer** instruction from the Codex per-key path below so the pins are re-projected into `~/.codex/agents/trailhead-*.toml`.
+   - **The per-key questions (Manual path only): always two separate questions, one for `plan` and one for `execute`; never merge them into a single model pick.** Ask each as its own `AskUserQuestion` menu (current value pre-selected), and offer the **same versioned lineup** to both. Each option is a **full model id with its version**; never a bare family alias (`opus`/`sonnet`/`haiku`), which can't say *which* live version. Build the list from the models actually reachable **at setup time** (verify, don't trust this file verbatim), offering **at least the two most recent versions per family**, e.g. `claude-fable-5`, `claude-opus-5` / `claude-opus-4-8`, `claude-sonnet-5` / `claude-sonnet-4-8`, `claude-haiku-4-5`, plus **inherit session** (the no-override option, the session model). If that lineup exceeds the menu's option cap, drill **family → version** or include a free-id "Other" so every recent version stays reachable. The rarer `research`/`review`/`debug` sit behind an "Advanced" option, each its own separate choice, same versioned rule.
+   - **Anti-pattern, never do this (in the Manual path):** a single screen whose options are *combined* plan+execute presets, e.g. `🧠 Plan 4.8 / Exec Sonnet 5`, `🚀 Tutto Opus 5`, `Plan Opus 5 / Exec Sonnet 5`. That bundles the two decisions into one pick. Forbidden. In Manual, Plan is asked, answered, and only then is Execute asked, as a second menu: two questions, two answers, always. (A **named tier profile** applied whole is **not** this anti-pattern: it is a coherent per-key tier assignment chosen deliberately, not an ad-hoc plan+execute combo, which is why picking a profile is terminal.)
+   - **On Codex (host-detected), the Manual path asks `models.codex.*` instead of the Claude lineup.** Same discipline: `plan` and `execute` as two separate `AskUserQuestion` menus, never merged; the rarer `research`/`review`/`debug` behind Advanced, each its own choice. Offer OpenAI model ids verified reachable at setup time (do not trust this list verbatim): `gpt-5.6-sol` (flagship) / `gpt-5.6-terra` (balanced) / `gpt-5.6-luna` (fast), plus **inherit session** (default). Avoid the retiring `gpt-5.4` / `gpt-5.4-mini` and the deprecated `gpt-5.3-codex`. Write the answers to `models.codex.*`; the Claude `models.*` lineup is not asked on Codex (those ids cannot run there). After writing, tell the user to **re-run the installer** (the same `--host=codex` install command) so the pins are re-projected into `~/.codex/agents/trailhead-*.toml`: the menu updates `.trailhead/config.json`, the installer is what regenerates the TOMLs and enables `features.multi_agent_v2`.
+4. **🎨 Design**: 💾 Local disk · 🖼️ claude.ai/design (Anthropic's official Claude Design MCP, Claude only) · 🧵 Stitch (Google Stitch MCP, cross-host: Claude Code + Codex). *Mode only, don't ask for a URL here; the concrete project is created or reused at execution time and its projectId cached in `design.project` (see Prototype).* If claude.ai/design or Stitch is picked, ask the **🖼️ Design surface**: 🖌️ Canvas (a single project of screens to react to; default; **who makes it:** on claude.ai/design you do, the `/design` Artifact or a hand-made web-app project, not MCP-driven; on Stitch the MCP generates the screens) · 🧩 Design system (push components into a shared design-system project, for a shared library; **the MCP creates and syncs it**) → `design.surface`. Then **✅ Mockup approval**: 🖐️ Explicit (wait for a go-ahead before UI code) · ⏩ Auto (proceed without blocking).
 5. **🧪 TDD**: 🎯 Seams only · ✅ On (all definable behaviour) · ⛔ Off.
 6. **🖥️ Acceptance testing**: 🤖 Auto · ▶️ Always browser · 🙋 Guided UAT only. If browser is enabled, ask **🔗 base URL** and confirm it's a web app.
-7. **🧑‍⚖️ Plan review**: **before presenting this menu, first probe the PATH for known external AI CLIs** (e.g. `gemini`, `codex`, and any others the Cross-AI plan review technique recognises): run the detection, then build the menu from what was actually found. Never present this step with a hard-coded two-option list; the options are computed from the probe:
+7. **🧑‍⚖️ Plan review**: **before presenting this menu, first probe the PATH for known external AI CLIs** (probe **every** CLI in the Cross-AI plan review roster, do not shorten the list: `claude`, `gemini`, `codex`, `qwen`, `kimi`, `agy`, `opencode`, `cursor-agent`, `coderabbit`, plus any OpenAI-compatible local server configured; `kimi` counts only when `kimi --help` mentions `--output-format`, per the technique): `command -v` each one, then build the menu from what was actually found. **Exclude the current host's own CLI** (never offer `codex` when running on Codex, nor `claude` when running on Claude Code): a session reviewing a plan with its own model is not cross-AI, so the host's own CLI must never appear as an option. Never present this step with a hard-coded two-option list; the options are computed from the probe:
    - **No CLI found**: offer only ⛔ Off, and say in the prompt that no external AI CLI was detected on the PATH (so the other choices would do nothing).
    - **One CLI found**: ⛔ Off · 🤝 Use `<name>`. (With a single CLI, "all" and "pick specific" collapse to the same thing, so don't show both.)
    - **Two or more found**: ⛔ Off · 🤝 All detected (`<name>`, `<name>`, …) · 🎯 Pick specific. Always show all three; never drop *Pick specific*. On *Pick specific*, ask **which CLIs** as a **multi-select** listing each detected CLI by name (never a free-text field). List the actual names found by the probe, not the placeholder examples from this file.

package/plugins/trailhead/skills/_shared/configuration.md

@@ -0,0 +1,8 @@
+## Configuration
+
+Three layers, **nearest wins**, key by key; a key unset at one layer inherits the next:
+- **Project**: a `.trailhead/config.json` file at the repo root: overrides for this project, committed so a team shares one config. **Config never lives in the map issue**: the map is an index of decisions, while config is the user's to change at any time, so it stays in a plain file (and never asserted into the map by the agent).
+- **Global**: `~/.claude/trailhead/config.json` (honour `$CLAUDE_CONFIG_DIR`): your standing defaults across every project.
+- **Defaults**: the built-in values documented in `configuration-reference.md`.
+
+Load the effective config at the start of a work session, **from the map's project root** (`.trailhead/config.json` at the superproject repo root) plus the global file, **before** any isolation workspace is set up. **Config is a property of the project/map, not the working directory**: an `isolation: worktree`/`clone` workspace **inherits** the config loaded here and must **never re-resolve it from the isolated copy's own root**, because a per-ticket clone (a submodule clone especially) has no `.trailhead/` of its own and would silently fall back to defaults (this is exactly how a `design: claude.ai/design` project ends up wrongly using `disk` in a clone). Config **writes** too (e.g. caching `design.project`) target the project's `.trailhead/config.json` in the original checkout, never the clone. **The main session orchestrates and holds the HITL moments** (the `build`/`bug` Discuss's "stop and ask", Verify's acceptance/UAT); **every model key runs as a subagent** (`plan`, `execute` (an *executor subagent* implementing with atomic commits on `models.execute`), `research`, `review`, `debug`) so the whole per-activity model split applies in one session whatever model it runs on. Run Execute inline only when `models.execute` is unset or equals the session model. **On a subagent-less host** (`subagentToolkit == none`) there is nothing to fan out into: every activity runs inline. **Separately, on a host that can't honour the model keys** (`honorsModelKeys == false`, e.g. Codex, whose subagents run on its own OpenAI models) every `models.*` key collapses to the single session model even though the activities still fan out; when any `models.*` is set there the engine surfaces a **one-time** session-start notice that the split is not taking effect (the keys stay in `.trailhead/config.json` for when the project next runs on Claude Code). On Codex the per-activity split is available through a parallel `models.codex.*` namespace (OpenAI model ids), the honoured namespace there (projected into per-technique `~/.codex/agents/*.toml` and dispatched at runtime by `agent_type`), while `models.*` (Claude ids) still collapse to the single session model; the collapse notice points at `models.codex.*` and goes silent once it is set. A host without a hook bus (`hookBus == none`) also runs a lightweight inline update check at session start (no SessionStart hook, no statusline). See `configuration-reference.md`. The **keys, their values, the model/tdd/acceptance semantics, and the guided menu setup live in `configuration-reference.md`**: read it when running `/trailhead:config` or when you need a key's exact meaning. `/trailhead:config` with no args runs the guided setup; `config get` prints the merged config; `config set <key> <value>` writes one key.

package/plugins/trailhead/skills/_shared/multi-map.md

@@ -0,0 +1,27 @@
+## Multiple maps on one repo (parking & concurrency)
+
+By default a repo has **one live map** and the frontier is the whole repo (as everywhere above). But you can **park a map to work another**, and a teammate can chart a second map on the same repo and work it concurrently. When more than one `trailhead:map` is open, each map carries **its own frontier**, kept separate by two mechanisms wired together (the same "one fact, two views" pattern as a blocker's native edge + label):
+
+- **Native sub-issue**: every ticket is a **sub-issue of its map** (`gh api --method POST repos/{owner}/{repo}/issues/<map>/sub_issues -F sub_issue_id=<ticket .id>`). This is the structure GitHub renders (the map shows its children + a progress bar); it carries the `Parent:` line's meaning as a real edge.
+- **Per-map label `trailhead:map-<n>`** (n = the map issue's own number): on **every one of its tickets** (not on the map issue itself, which is identified by its number, and would only be redundantly "a member of itself"). This is the **queryable key** that scopes the frontier to one query, because native sub-issues aren't cheaply filterable in a single search (exactly as with `blocked_by`), so the label carries the query.
+
+Both are set at chart and on every ticket **in the same pass** (create the ticket → set its map parent → add its map label), so they can't drift.
+
+**Scoped frontier** (one query, per map):
+```bash
+gh issue list --label "trailhead:ticket" --label "trailhead:map-<n>" --state open \
+  --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified"
+```
+
+**Active map.** Which map a session works is the **active map**: a `.trailhead/active-map` marker at the working root (one line `#<n>`, **gitignored**, per-session local state like `session-ticket`, never committed). `/trailhead:work` and `/trailhead:map` default to it; naming a map/ticket explicitly always overrides. Each checkout/clone (so each teammate) has its own.
+
+**Park & switch** = **pause** the in-flight ticket (`/trailhead:pause`, a `PAUSED` checkpoint), then point the active map at the other's number. Nothing else to save: every map lives on the Issues, durable. Resume later with `/trailhead:resume`, or just `/trailhead:work` once that map is active again.
+
+**Discovery.** `gh issue list --label "trailhead:map" --state open` enumerates the live maps. `/trailhead:map` with **no active map and more than one open** lists them and asks which; `/trailhead:map <n>` shows that one and makes it active.
+
+**Pinning with several maps.** No map is ever pinned. The 3 pinned slots are the permanent repo anchors: **dashboard + codebase + conventions**. Every open map is found via the `trailhead:map` label and listed in the pinned [dashboard](../trailhead-view/SKILL.md#render-the-dashboard-dashboard), so all of them stay reachable regardless of how many are live, without contending for a slot.
+
+**Team.** A teammate charts a new map → it gets its own `trailhead:map-<m>` + sub-issue parentage → their sessions scope to it. The two frontiers **never mix** (distinct labels). Per-ticket **claim/collision** rules are unchanged (the assignee is still the claim). Two maps can still touch the **same code**: the `Scope:` line + `isolation:` serialisation from [Working as a team](teamwork.md#working-as-a-team) now apply **across maps too**, not just within one.
+
+**One-map compatibility.** With a single open map the frontier stays **repo-wide** (minus `trailhead:whiteboard` tickets, which carry their own frontier, see [The whiteboard](../trailhead-view/SKILL.md#render-the-whiteboard-whiteboard)); the map label + sub-issue are still applied at chart, so concurrency is ready the moment a second map appears. An older map charted before this (tickets lacking the label) needs a one-time **backfill** (add `trailhead:map-<n>` to its open tickets, set their sub-issue parent) only if you add a second map on that repo.
+

package/plugins/trailhead/skills/_shared/out-of-scope.md

@@ -0,0 +1,11 @@
+# Out of scope vs deferred
+
+The full test and re-routing protocol for the map's *Out of scope* section. SKILL.md → **Out of scope** keeps the core rule and a one-line test; read this file when you are about to file something under *Out of scope*, when re-routing a deferred line, or when running the inbox sweep.
+
+## Out of scope vs deferred (ask, never bury)
+*Out of scope* is for work ruled beyond the destination **for good**: this effort never does it. It is **not** a parking lot for work that *will* happen but hangs on something **outside this map**, a feature, function, or milestone not ticketed here (e.g. a billing / *bolletta* module that lives elsewhere or comes later, and the items that wait on it). Before filing anything under *Out of scope*, apply the test: **will this actually get done once X exists?** **The tells of a deferred line (any one is enough):** it **names a gate or trigger** (*gated by X*, *quando X*, *once X exists*, *dipende da X / waits on X*); it carries a **this-only scope qualifier** that rules it out *here* but not for good (*per questo slice*, *for now*, *in this milestone*, *not in this map*), which means wanted-later, not rejected; it's a **feature the product will plausibly still want** (a later milestone, another map); or **an existing `trailhead:seed` is gated on it** (some seed's trigger / `## Blocked by` names this line), which makes it a **live gate by definition**. Any one of these is deferred: never wave it through as "genuinely beyond the destination". Only work **decided against for the product** (won't ever be built, wrong approach, explicitly cut, with **no** "for this slice / for now" qualifier) is truly out of scope. **A line that is the gate of a live seed can never be "ruled out"**: finding one means the cluster is mis-wired (the gate was left behind when its dependents became seeds), so re-route the gate too (see below), or those seeds' triggers dangle. If yes, it isn't out of scope, it's **deferred**, so don't close-and-forget it. **Ask the user how to capture it, and which map it belongs to** (this map, or a future / other map); **never decide silently, and every move out of *Out of scope* is user-confirmed** (you propose, the user picks the tier and the map). Route along the **capture spectrum**: a **`seed`** gated on its trigger (tie it to what it waits on, e.g. *when the bolletta exists*), an **`idea`** to revisit, or a **`todo`** if it's already defined work to do now. **If it belongs to a future map** (defined work wanted for the product, but beyond this effort's arc), don't fabricate a map that isn't charted yet, but **do capture it as a real artifact, asking the user which**: a **`seed`** (a gated todo, a tracked issue that survives the map, is queryable by label, and can be the native `blocked_by` of its dependents) or an **`idea`** (a fog line, lighter, for a maybe-later). **Never leave it as a bare *Out of scope* text line**: that's the fragile case (a finished map's *Out of scope* is easy to lose, and a dependent wired to a text line has no real target). Leave only a one-line *Out of scope* **breadcrumb pointing at the artifact** (`→ future map: <name>, see <seed/idea link>`). It then **graduates into the current map** the moment this effort actually needs it (it "comes up on its own"), or **the next map charted on this repo harvests it**, its chart step asking which parked seeds/todos/ideas to pull in (see `../trailhead-chart/references/charting.md`, Mode 1 / Mode 1-bis). Whichever way, **the gate and its dependents move together** (a dependent seed's trigger points at the gate's artifact, a live target), never split across "ruled out" and re-routed.
+
+**Re-route the gate, not just its dependents.** When the thing a deferred item waits on (its gate X) is itself an *Out of scope* / deferred line, X is deferred by the same test: **re-route X first** (its own `seed`/`idea`/`todo`, or a named future-milestone / another-map pointer), then **tie the dependents to X's new form**, never to a line that stays in *Out of scope*. A seed's trigger must point at a **live** target: a ticket/seed here, a named milestone/map, or a real external condition; a seed gated on a dead "ruled out" line has a trigger that can never fire. **Move a gate and its dependents together**, so the whole cluster leaves *Out of scope* at once (e.g. the *bolletta* becomes its own seed, and the "gated by the bolletta" items become seeds wired to it, none left behind as "ruled out").
+
+## Stale lines noticed later
+Only genuinely-beyond-the-destination work stays in *Out of scope*. The same test applies to **stale *Out of scope* lines** noticed later: `/trailhead:map` (read-only) **flags** any **un-parked** deferred line as an advisory (like blocked-by drift, it changes nothing) **and suggests running `/trailhead:inbox` to re-route them**, while `inbox` or an explicit user go-ahead does the **actual re-route**, a line that's really deferred becoming a seed/idea/todo instead of lingering as "ruled out". A line **already parked** (annotated `→ future map` with its dependent seeds wired to a live trigger) is settled: neither surface flags it again.

package/plugins/trailhead/skills/_shared/principles.md

@@ -0,0 +1,8 @@
+## Principles
+
+- **Execution inside the map (default).** Unlike a plan-only approach ("plan, don't do"), here the map carries **construction** within it: after the decision tickets, build tickets graduate from the fog and are **executed** as children of the map. The destination is the **working** artifact (a deployed app), not a spec document; the spec is a waypoint. *Override:* a project that must stop at the spec declares it in the map's `## Notes` (that wins over this default).
+- **Refer by name.** Every map and ticket is an issue, so it has a **title**. In everything the human reads, refer by name, never by a bare `#number`. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish (a name wraps its link) but they ride *inside* the name. **One exception: a command the user must run.** In `/trailhead:work <ticket>` the argument is machine input, not prose; give the **bare number** there (a long title, with its punctuation and jargon, is awkward and error-prone to type). Name the ticket in the surrounding sentence, put the number in the command.
+- **Result-oriented output.** In the chat, report **what was done and the next step**: name tickets, give the concrete next command. Never expose trailhead's internal machinery: Mode labels (`Mode 1`), protocol/step names (`DISCUSS`/`PLAN`/`VERIFY`, "the build engine", "graduate the fog", "the frontier"), wrapper/SKILL.md mechanics, or the conventions and config you are silently obeying: the git mode (`main`/`pr`), the isolation/worktree decision, submodule commit mechanics (commit-inside + gitlink bump), claim/assignment plumbing, and **how work fans out to subagents** (whether a step ran inline or as a subagent, the role name `executor`, the model `claude-sonnet-5`, the config key `models.execute`). To the user it is just **"an agent"**: say "I'll hand this to an agent with the exact spec, then run the code review over the whole diff", never "an executor on `claude-sonnet-5` per `models.execute`". Just act, then report the outcome. Surface a convention only when it **changes what the user must do** (a UAT they run, a release awaiting their command, a genuine claim collision with *another* login) or when they explicitly ask.
+- **No em-dashes.** Write with ordinary punctuation: commas, colons, semicolons, parentheses, periods. Never use an em-dash (U+2014), and never a hyphen standing in for a comma. This holds for **everything trailhead produces**: ticket titles and bodies, engine comments, the map body, commit descriptions, chat output, and the skill's own source docs. En-dashes in numeric ranges (`1–2`) and the arrow `→` in trailhead's notation stay; only the em-dash is banned.
+- **One ticket per session: hard rule.** Resolve **at most one** ticket per session; once one is resolved, do **not** start a second; end the session instead. The only exceptions: `research` tickets (AFK, run in parallel) and `capture` operations (they resolve nothing). On resolving a ticket, close the session with the **[Session handoff](session-handoff.md)** ritual.
+- **Git per the repo's conventions.** The default is commit straight to `main`, conventional commits, no feature branch/PR, but the repo's `trailhead:conventions` issue governs: honour its `git:` (`main` | `pr`), `release:` (`command` | `auto`), and `isolation:` (`none` | `worktree`) header. Never `Co-Authored-By`. **Every commit made while resolving a ticket carries a `Refs: #<n>` trailer** (the ticket's issue number) as its last line, so GitHub threads the commit into that ticket's timeline (the commits show up *in* the ticket). Use a **non-closing** reference (`Refs:`): never a closing keyword (`fixes`/`closes`/`resolves #n`), because the ticket is closed **explicitly at Resolve** after Verify passes, not by a commit landing on the trunk. (Charting/config commits not tied to a ticket carry no `Refs:`.)