@marcomigozzi/trailhead 0.13.0 → 0.14.0

package/plugins/trailhead/skills/trailhead-work/references/ticket-engines.md

@@ -6,6 +6,8 @@ Every ticket is **HITL** (human in the loop, speaking for themselves) or **AFK**
 
 Technique names below (**Grilling**, **Domain vocabulary**, **Prototype**, **Research**, **TDD**, **Code review**, **Acceptance testing**, **Debug**) are indexed in `../../_shared/techniques.md`; their full protocols live in `_shared/`, read from `../../_shared/techniques/<name>.md`.
 
+**Work state (every type).** Keep `.trailhead/work-state.json` current with the `set --step` call in the **Work state file** paragraph of `../../_shared/teamwork.md`: `build` Discuss/Plan/Execute/Verify/Resolve set `discuss`/`plan`/`execute`/`verify`/`resolve`; `bug` Repro and Diagnose set `discuss`, Fix `execute`, Verify `verify`, Resolve `resolve`; `decision`, `prototype` and `task` stay `discuss` until `resolve`. A loop back from Verify to Execute (or Fix) sets `execute` again, and a UAT follow-up (`UAT of:`) sets `verify`. `research` tickets never write it: they run AFK and possibly in parallel, and the single file tracks only the one ticket in play.
+
 ## UAT follow-ups (any type)
 A ticket whose body carries `UAT of: <parent>` is a UAT follow-up, **whatever its type label**, including a graduated seed (a `trailhead:seed` that dropped `trailhead:seed` + `trailhead:blocked` on graduating, keeping whatever type label it had, or none). `work`, `quick`, and `auto` all dispatch through this file, so this check runs **before** the per-type engines below. It resolves via the **Acceptance testing** technique (`../../_shared/techniques/acceptance-testing.md`), starting with the drive-mode ask; the record is a `VERIFY` comment on the follow-up itself, never on the parent. It closes only on a confirmed pass, with a resolution comment linking back to the parent.
 
@@ -30,7 +32,7 @@ The ticket that *builds*. Lean cycle, all in **ticket comments**:
 
 1. **Discuss**: **never auto-grill.** Start from Plan. If reading the ticket surfaces blocking ambiguity, **stop and ask the user** whether they want a **Grilling** round: don't launch it on your own initiative. Only on their assent run the short round and post a `DISCUSS` comment with the closed choices. The user may also ask for it themselves at any time. Advisory choices raised here **offer** the delegate/defer options, per the injection recipe in `../../_shared/choices.md`.
 2. **Plan**: a `PLAN` comment: the steps, the seams, the files touched, the verification criteria. Apply **TDD** per `config.tdd` (`seams`/`on`/`off`). Produce this plan via a *planner subagent* on `config.models.plan` (dispatch the **`trailhead-plan`** agent, read-only, passing `config.models.plan` as the model override; inline when the model is unset or equals the session model; Execute then runs as its own subagent, see below). If `config.plan_review` is on, run **Cross-AI plan review** before Execute: send the plan to external AI CLIs and converge on their concerns. Now that the files/seam are known, run the **undeclared-coupling check** (`../../_shared/teamwork.md`) against in-progress tickets. **Plan to sufficiency:** stop once you can name the steps, seams, and files with confidence, and never re-read a file already read in this planning pass; act when you have enough to plan, rather than re-deriving what the pass already established. **The single exception:** under an accepted `lean` skip (see the Size triage above), produce a short inline plan here instead of the planner subagent, and skip Cross-AI plan review; absent that accepted skip, this step runs in full as described.
-3. **Execute**: **if this ticket changes user-facing UI (a new screen, a redesign, a changed layout), run the Prototype technique FIRST, before any real UI code**: surface a mockup to react to (its clickable link always in the same message as the approval question, per the Prototype technique), routed by `config.design` (disk / artifacts / stitch) and gated by `config.design.approval` (`explicit` waits for a go-ahead, `auto` proceeds after surfacing). **Route by `config.design` and never shortcut a hosted mode to a local disk mockup**: when `config.design` is `artifacts` (or the legacy `claude.ai/design`) or `stitch`, the mockup is built there (reusing a cached `design.project`); `disk` is only for `config.design: disk` or the technique's explicit, announced fallback, never a convenience default. Read `config.design` before producing anything. For a redesign or new screen the default is to offer mockups; don't jump straight to code on a UI ticket. **Once the mockup is approved, reproduce it with 100% fidelity** (layout, spacing, sizing, colour, type, copy, and every state), never a loose approximation "in the spirit of" it; if part of the approved mockup is genuinely infeasible, stop and raise it rather than silently deviate (full statement in the **Prototype** technique, `../../_shared/techniques/prototype.md`). **Make fidelity verifiable, not a hope:** before finishing Execute, enumerate the approved mockup's elements and states, confirm each is reproduced, and **record that enumerated fidelity list as a ticket comment** (noting any element raised as infeasible with its resolution), so Verify works from a durable checklist instead of reconstructing intent. At Verify, **Acceptance testing** checks the built screen against the approved mockup (element by element, state by state) and **Goal-backward verification** carries fidelity as an explicit goal claim (see `../../_shared/techniques/acceptance-testing.md` and `../../_shared/techniques/verify.md`). Then implement with **atomic commits** (conventional commits, each with a `Refs: #<n>` trailer for this ticket, see **Principles** in `../../_shared/principles.md`; the trailer is also what scopes Verify's review and goal check, per **Ticket diff** in `../../_shared/techniques/code-review.md`), following the repo's `trailhead:conventions` `git:`, straight to `main` by default, or a feature branch + PR when `git: pr`. **Under `isolation: worktree`, do the work in this ticket's `git worktree`** (`trailhead/t<n>` branch), integrating to the trunk at Resolve (see `../../_shared/teamwork.md`). One commit = one verifiable step. Run this via an **executor subagent on `config.models.execute`** (dispatch the **`trailhead-executor`** agent, full tools that can Edit/Write/commit, passing `config.models.execute` as the model override; inline when the model is unset or equals the session model); the commits land on `main`, visible. **Before installing any new dependency, run the verify-before-install gate** (slopsquatting barrier): check the package's legitimacy (name / typosquat similarity to popular packages, age / first-seen date, download counts, repository metadata present and matching) and **stop and ask the user on a suspicious result** (block-and-ask), never installing on your own judgement. On a host with a hook bus the `trailhead-install-guard` `PreToolUse` hook enforces this, blocking a named public-registry install (npm / PyPI / crates.io / Go / RubyGems) until it is vetted; once vetted, proceed by re-running the exact install command prefixed with `TRAILHEAD_VERIFIED_INSTALL=1`. New scope surfacing mid-execute is captured/split, not worked here.
+3. **Execute**: **if this ticket changes user-facing UI (a new screen, a redesign, a changed layout), run the Prototype technique FIRST, before any real UI code**: surface a mockup to react to (its clickable link always in the same message as the approval question, per the Prototype technique; the guard also accepts a link inside the approval question itself, the prose stays preferred), routed by `config.design` (disk / artifacts / stitch) and gated by `config.design.approval` (`explicit` waits for a go-ahead, `auto` proceeds after surfacing). **Route by `config.design` and never shortcut a hosted mode to a local disk mockup**: when `config.design` is `artifacts` (or the legacy `claude.ai/design`) or `stitch`, the mockup is built there (reusing a cached `design.project`); `disk` is only for `config.design: disk` or the technique's explicit, announced fallback, never a convenience default. Read `config.design` before producing anything. For a redesign or new screen the default is to offer mockups; don't jump straight to code on a UI ticket. **Once the mockup is approved, reproduce it with 100% fidelity** (layout, spacing, sizing, colour, type, copy, and every state), never a loose approximation "in the spirit of" it; if part of the approved mockup is genuinely infeasible, stop and raise it rather than silently deviate (full statement in the **Prototype** technique, `../../_shared/techniques/prototype.md`). **Make fidelity verifiable, not a hope:** before finishing Execute, enumerate the approved mockup's elements and states, confirm each is reproduced, and **record that enumerated fidelity list as a ticket comment** (noting any element raised as infeasible with its resolution), so Verify works from a durable checklist instead of reconstructing intent. At Verify, **Acceptance testing** checks the built screen against the approved mockup (element by element, state by state) and **Goal-backward verification** carries fidelity as an explicit goal claim (see `../../_shared/techniques/acceptance-testing.md` and `../../_shared/techniques/verify.md`). Then implement with **atomic commits** (conventional commits, each with a `Refs: #<n>` trailer for this ticket, see **Principles** in `../../_shared/principles.md`; the trailer is also what scopes Verify's review and goal check, per **Ticket diff** in `../../_shared/techniques/code-review.md`), following the repo's `trailhead:conventions` `git:`, straight to `main` by default, or a feature branch + PR when `git: pr`. **Under `isolation: worktree`, do the work in this ticket's `git worktree`** (`trailhead/t<n>` branch), integrating to the trunk at Resolve (see `../../_shared/teamwork.md`). One commit = one verifiable step. Run this via an **executor subagent on `config.models.execute`** (dispatch the **`trailhead-executor`** agent, full tools that can Edit/Write/commit, passing `config.models.execute` as the model override; inline when the model is unset or equals the session model); the commits land on `main`, visible. **Before installing any new dependency, run the verify-before-install gate** (slopsquatting barrier): check the package's legitimacy (name / typosquat similarity to popular packages, age / first-seen date, download counts, repository metadata present and matching) and **stop and ask the user on a suspicious result** (block-and-ask), never installing on your own judgement. On a host with a hook bus the `trailhead-install-guard` `PreToolUse` hook enforces this, blocking a named public-registry install (npm / PyPI / crates.io / Go / RubyGems) until it is vetted; once vetted, proceed by re-running the exact install command prefixed with `TRAILHEAD_VERIFIED_INSTALL=1`. New scope surfacing mid-execute is captured/split, not worked here.
 4. **Verify**: a `VERIFY` comment: run the tests / the plan's criterion; then the **Code review** technique, scoped to the ticket's own commits per its **Ticket diff** rule (`../../_shared/techniques/code-review.md`: the `Refs: #<n>` set, read per commit, recomputed each round, an empty set surfaced as an error, never a `<base>...HEAD` range) (its subagent reviews *adversarially*: it doesn't defer to a `CLAUDE.md` convention or a "settled decision" memory), and carries the review's counts line and findings ledger, per code-review.md, **run in the background and collected by polling, never a blind blocking wait** (a hard engine default on every host, see *Reviews never block the session* in `../../_shared/techniques.md`); **read the review's leading `status:` tag to branch deterministically: `status: clean` -> proceed to Resolve, `status: issues_found` -> iterate the fix-and-re-review loop (or run the HITL checkpoint) before resolving**; then the **Goal-backward verification** technique on `config.models.verify` (does the change deliver what the ticket promised, backward from its `Question` and the `PLAN`'s criteria; the read-only `trailhead-verify` subagent, on the same **Ticket diff** set), **run in the background and collected by polling** like Code review, branching on its leading `status:` tag (`status: met` -> proceed, `status: gaps_found` -> loop back to Execute for the gap or run the HITL checkpoint before resolving, `status: inconclusive` as the leading tag (all gaps cleared) -> a per-reason-class HITL checkpoint with no auto-retry, never auto-resolving over the unevaluated goal); then **Acceptance testing** if the change is user-facing, opening with the drive-mode ask (`../../_shared/techniques/acceptance-testing.md`): AI-driven, or **walk the user through a guided UAT conversationally, one step at a time**, never a checklist dumped in a comment: interactive by design, so it runs inline, not backgrounded. Report the outcome honestly (if a test fails, say so). **The single exception:** under an accepted `lean` skip, run a lighter inline review pass instead of the full Code-review subagent and a quick inline goal check instead of the full Goal-backward verification subagent (or skip either only when the change is truly cosmetic); the lighter inline review still uses the same finding IDs, counts line, and ledger, and the same no-`open` gate, per code-review.md; the tests / criterion and the honest outcome report still run regardless. At a HITL checkpoint here, an advisory sub-choice (which fix, how to proceed) **offers** the delegate option, per the injection recipe in `../../_shared/choices.md`; the accept/resolve decision stays the human's.
 5. **Resolve**: a resolution comment with what was done → `gh issue close` → update `Decisions so far` on the map (a body read-modify-write: obey the **Fail-safe body rewrites** rule in `../../_shared/substrate.md`). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (opens with the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. On (a), run the guided walkthrough now and resolve **only on a confirmed pass** (a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, this guard doesn't fire. **Post-commit self-check (before the comment goes out).** For each commit the comment cites, confirm the hash resolves (`git cat-file -e <hash>^{commit}`, or `git show --stat <hash>`) and that every file the comment names as touched actually appears in that commit's diff (`git -c core.quotepath=false show --name-only --format= <hash>`, with `core.quotepath=false` so a non-ASCII filename compares plainly instead of in git's C-quoted form); correct or drop any citation that fails the check, so a hallucinated or mis-stated commit never lands in the tracker record. **If this change materially altered the codebase** (a new module/layer, dependency, seam, or build/test command), **patch the affected facet of the `trailhead:codebase` issue** (see **Codebase** in `../../_shared/substrate.md`) in place (a line or two, not a re-map). Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): `/clear` + next command.
 

package/plugins/trailhead/templates/trailhead-work-state.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead work state (self-contained, ships in templates/ so it reaches every
+// install channel: bin/trailhead.js copies templates/ wholesale for Claude/npm
+// and Codex). Writes and removes <repo>/.trailhead/work-state.json, the state
+// of the ticket in play that the skills update at every step. #205.
+//
+// CLI:
+//   node trailhead-work-state.js set [--repo <dir>] [--map <n>|none] [--ticket <n>]
+//        [--title <t>] [--step <step>] [--auto true|false] [--auto-done <n>]
+//   node trailhead-work-state.js clear [--repo <dir>]
+// --repo defaults to cwd. `set` merges the given fields onto the existing file
+// (only --step at each step change); a --ticket other than the one on file
+// starts from an empty state. File shape:
+//   { map, ticket, title, step, auto, autoDone, session, updatedAt }
+// autoDone: tickets resolved so far in the autonomous run (non-negative
+// integer, default 0; reset to 0 whenever auto is false).
+// Prints one JSON line {"status","path","state"?,"message"?}.
+//   status: written | cleared | absent | skipped
+// Exit 0 on every normal outcome and on any unexpected I/O error (it must
+// never block the caller: status skipped with the message); exit 2 only on a
+// usage or validation error (nothing is written).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const STATE_DIR = '.trailhead';
+const STATE_FILE = 'work-state.json';
+const STEPS = ['discuss', 'plan', 'execute', 'verify', 'resolve', 'paused'];
+const TITLE_MAX = 200;
+
+const isPosInt = (v) => Number.isInteger(v) && v > 0;
+
+// Strict parse of a positive integer from a CLI string; null if invalid.
+function parsePosInt(text) {
+  return /^[1-9]\d*$/.test(text) ? Number(text) : null;
+}
+
+// Strict parse of a non-negative integer from a CLI string; null if invalid.
+function parseNonNegInt(text) {
+  return /^(0|[1-9]\d*)$/.test(text) ? Number(text) : null;
+}
+
+// Title on a single line: control characters and newlines become spaces,
+// spaces collapsed, trimmed, capped at TITLE_MAX characters.
+function cleanTitle(text) {
+  return String(text).replace(/[\u0000-\u001f\u007f\s]+/g, ' ').trim().slice(0, TITLE_MAX);
+}
+
+// Keeps only the valid fields of an arbitrary object: an invalid field is
+// dropped (treated as absent), never carried into the new state.
+function sanitizeState(raw) {
+  const out = {};
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  if (raw.map === null || isPosInt(raw.map)) out.map = raw.map;
+  if (isPosInt(raw.ticket)) out.ticket = raw.ticket;
+  if (typeof raw.title === 'string') out.title = cleanTitle(raw.title);
+  if (STEPS.includes(raw.step)) out.step = raw.step;
+  if (typeof raw.auto === 'boolean') out.auto = raw.auto;
+  if (Number.isInteger(raw.autoDone) && raw.autoDone >= 0) out.autoDone = raw.autoDone;
+  return out;
+}
+
+// Merges the patch onto the existing state. A different ticket starts from
+// empty (no inherited title/map). Returns the normalised state, or
+// { error } when ticket or step is missing.
+function mergeState(existing, patch, { session = null, now = new Date() } = {}) {
+  const base = sanitizeState(existing);
+  const start = patch.ticket !== undefined && base.ticket !== undefined && base.ticket !== patch.ticket ? {} : base;
+  const merged = { ...start, ...patch };
+  if (merged.ticket === undefined) return { error: 'usage: set needs a ticket (pass --ticket)' };
+  if (merged.step === undefined) return { error: 'usage: set needs a step (pass --step)' };
+  const auto = merged.auto === undefined ? false : merged.auto;
+  return {
+    map: merged.map === undefined ? null : merged.map,
+    ticket: merged.ticket,
+    title: merged.title === undefined || merged.title === '' ? null : merged.title,
+    step: merged.step,
+    auto,
+    // A run that is not autonomous has no counter.
+    autoDone: auto && merged.autoDone !== undefined ? merged.autoDone : 0,
+    session,
+    updatedAt: now.toISOString(),
+  };
+}
+
+function parseArgs(argv) {
+  const command = argv[0];
+  if (command !== 'set' && command !== 'clear') {
+    return { error: `usage: expected "set" or "clear", got: ${command === undefined ? '(nothing)' : command}` };
+  }
+  let repo = null;
+  const patch = {};
+  const allowed = command === 'set' ? ['--repo', '--map', '--ticket', '--title', '--step', '--auto', '--auto-done'] : ['--repo'];
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!allowed.includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const value = argv[i];
+    if (flag === '--repo') repo = value;
+    else if (flag === '--map') {
+      if (value === 'none') patch.map = null;
+      else if (parsePosInt(value) !== null) patch.map = parsePosInt(value);
+      else return { error: `usage: --map must be a positive integer or "none", got: ${value}` };
+    } else if (flag === '--ticket') {
+      if (parsePosInt(value) === null) return { error: `usage: --ticket must be a positive integer, got: ${value}` };
+      patch.ticket = parsePosInt(value);
+    } else if (flag === '--title') patch.title = cleanTitle(value);
+    else if (flag === '--step') {
+      if (!STEPS.includes(value)) return { error: `usage: --step must be one of ${STEPS.join(', ')}, got: ${value}` };
+      patch.step = value;
+    } else if (flag === '--auto') {
+      if (value !== 'true' && value !== 'false') return { error: `usage: --auto must be true or false, got: ${value}` };
+      patch.auto = value === 'true';
+    } else if (flag === '--auto-done') {
+      if (parseNonNegInt(value) === null) return { error: `usage: --auto-done must be a non-negative integer, got: ${value}` };
+      patch.autoDone = parseNonNegInt(value);
+    }
+  }
+  return { command, repo, patch };
+}
+
+// Reads the existing file; missing or corrupt = no state (never a crash).
+function readExisting(file, fsMod) {
+  try {
+    return JSON.parse(fsMod.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Atomic write: a unique temp in the same dir, then rename over the file
+// (never an in-place truncate); the temp is removed if anything fails.
+function writeAtomic(dir, file, text, fsMod) {
+  fsMod.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${STATE_FILE}.${process.pid}-${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    fsMod.writeFileSync(tmp, text);
+    fsMod.renameSync(tmp, file);
+  } catch (err) {
+    try { fsMod.unlinkSync(tmp); } catch { /* pulizia best effort */ }
+    throw err;
+  }
+}
+
+function writeResult(stdout, result) {
+  stdout.write(JSON.stringify(result) + '\n');
+}
+
+function main(argv, { cwd, stdout, env, fs: fsMod, now } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const env_ = env || process.env;
+  const fs_ = fsMod || fs;
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    process.stderr.write(parsed.error + '\n');
+    return 2;
+  }
+
+  const repoDir = parsed.repo ? path.resolve(cwd_, parsed.repo) : cwd_;
+  const dir = path.join(repoDir, STATE_DIR);
+  const file = path.join(dir, STATE_FILE);
+  try {
+    if (parsed.command === 'clear') {
+      if (!fs_.existsSync(file)) {
+        writeResult(out, { status: 'absent', path: file });
+        return 0;
+      }
+      fs_.unlinkSync(file);
+      writeResult(out, { status: 'cleared', path: file });
+      return 0;
+    }
+
+    const sessionEnv = env_.CLAUDE_CODE_SESSION_ID;
+    const session = typeof sessionEnv === 'string' && sessionEnv !== '' ? sessionEnv : null;
+    const state = mergeState(readExisting(file, fs_), parsed.patch, { session, now: now || new Date() });
+    if (state.error) {
+      process.stderr.write(state.error + '\n');
+      return 2;
+    }
+    writeAtomic(dir, file, JSON.stringify(state, null, 2) + '\n', fs_);
+    writeResult(out, { status: 'written', path: file, state });
+    return 0;
+  } catch (err) {
+    writeResult(out, { status: 'skipped', path: file, message: 'error: ' + (err && err.message ? err.message : String(err)) });
+    return 0;
+  }
+}
+
+module.exports = { STEPS, sanitizeState, mergeState, parseArgs, main };
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, env: process.env });
+  process.exit(code);
+}