traceticket 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TraceTicket contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# TraceTicket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**From messy client call to verified ticket, with receipts.**
+
+Turn a client call transcript into tickets a developer can build without asking anything.
+**The LLM proposes; gates dispose.** Every claim traces to a verbatim quote, every request is checked against the product, the client is grilled on anything vague, parallel agents review before a ticket ships, and a human signs off.
+
+## Quick start
+
+```
+npx traceticket init              # run once in your repo; auto-detects Claude Code / Cursor / others
+npx traceticket init --target all
+```
+
+Restart your IDE, then run:
+
+```
+/call-to-tickets path/to/transcript.txt
+```
+
+| You type | What happens |
+|---|---|
+| `npx traceticket init` | Installs the skills, agents and commands into your repo |
+| `/call-to-tickets <transcript>` | The whole workflow, from transcript to approved tickets |
+| `/grill-client <run>` | Restart the multiple-choice questions on a run |
+| `/review-tickets <run>` | Re-run the independent review |
+| `/run-report <run>` | Rebuild the report |
+
+The package installs the command `traceticket` (the older name `sdlc-kit` still works). Everything it installs calls `npx traceticket`.
+
+**No setup for product context.** `traceticket docs` finds the repo's own PRDs, specs, ADRs, glossaries and READMEs (skipping `node_modules`, build output and agent instruction files), and the product analyst reads them and searches the code. Evidence can quote a doc line or a code line; Gate P checks the quote is really in that file. When the docs and the code disagree, the code wins and the drift is reported. Pass `--product <dir>` only to narrow it to one folder.
+
+## The workflow
+
+```
+W1 Intake      ingest → extractor → Gate A grounding → verifier (Gate A2)
+W2 Product     docs (find PRDs, specs, ADRs) → product analyst (docs + code) → Gate P evidence
+W3 Grill       Gate B clarity → question planner → grill ⇄ client → Gate G
+                 └ answers become spans, W1-W2 re-run on them
+W4 Tickets     ticket writer → Gate C ready
+W5 Review      reviewer → Gate R → developer (one ticket only) → Gate D ── questions → W3
+W6 Report      emit → report → eval
+```
+
+| Gate | Checks | By |
+|---|---|---|
+| A | quote is a verbatim substring of its span | script |
+| A2 | requirement claims no more than its quote | `sdlc-verifier` agent, fresh context |
+| P | every product-fit label quotes the product docs verbatim | script |
+| B | vague words, missing actor/trigger, conflicts | script |
+| G | every question answered from a client span, or parked with a reason | script |
+| C | schema, Given/When/Then, grounded and non-vague AC, product fit, nothing open | script |
+| R | no unresolved blocking review finding at confidence ≥ 8 | `sdlc-reviewer` agent + script |
+| D | a developer who sees only the ticket has no questions | `sdlc-developer` agent + script |
+
+## What gets installed
+
+| Path | What |
+|---|---|
+| `.sdlc/skills/*/SKILL.md` | 11 skills, written to the [agent-skills anatomy](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md): Overview, When to Use, Workflow, Rationalizations, Red Flags, Verification |
+| `.sdlc/agents/*.md` | 7 agents in [ECC](https://github.com/affaan-m/everything-claude-code) format, each opening with a Prompt Defense Baseline |
+| `.sdlc/references/` | Definition of Ready, JSON contracts, ticket template, question format, vague lexicon, prompt defense |
+| `.claude/skills`, `.claude/agents`, `.claude/commands` | Claude Code: `/call-to-tickets`, `/grill-client`, `/review-tickets`, `/run-report` |
+| `.cursor/rules/sdlc.mdc`, `.cursor/skills/`, `.cursor/agents/`, `.cursor/commands/` | Cursor: the same four commands |
+| `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`, ... | Codex, Gemini, Copilot, Windsurf, Cline, opencode |
+
+The grill follows Matt Pocock's [grilling / grill-with-docs](https://github.com/mattpocock/skills) pattern (rounds, recommended answers, facts looked up not asked, glossary updated as terms resolve). Stop points, completion statuses and the confidence-8 review bar come from [gstack](https://github.com/garrytan/gstack). The "does it need to exist? does it exist? extend? smallest slice?" ladder and "say what you skipped" rule come from [Ponytail](https://github.com/DietrichGebert/ponytail).
+
+## CLI
+
+Every command prints JSON. Must-pass gates exit 1 on failure, so agents and CI use the same checks.
+
+```
+traceticket ingest <file> --run r1                  numbered immutable spans (S1-L1 ...)
+traceticket ingest answers-1.txt --run r1 --append  client answers become quotable spans
+traceticket gate grounding|product|clarity|grill|ready|review|devcheck --run r1 [--product dir]
+traceticket emit --run r1 [--gh]                    tickets.md for tickets that passed C, R and D
+traceticket report --run r1                         REPORT.md built from run JSON only
+traceticket eval --run r1 --key answer_key.json     catch rate, recall, product-fit accuracy, inventions
+traceticket status --run r1
+```
+
+## Demo fixture
+
+`examples/shiftdesk/`: a made-up scheduling product (`product/`: features, glossary, an ADR), a client call with 14 planted defects (contradictions, a decision reversal, vague thresholds, scope creep, a product conflict, an already-built feature, glossary aliases and a prompt injection), a scripted client (`client_answers.md`) and an answer key. `golden-run/` is a full run produced by the agents, replayed through every gate in CI.
+
+## Make your own workflow
+
+Edit `workflow/workflow.json` (steps with `kind: tool | llm | human`, `skill`, `agent`, `gate`, `in`, `out`) and add skills under `workflow/skills/`. Every adapter regenerates from it. New host? Add one entry to `ADAPTERS` in `src/adapters.js`.
+
+## Develop
+
+`npm test` (Node 18+, zero dependencies). The tests also check that every skill and agent keeps the required sections.

package/bin/cli.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { runDir, readJson, writeJson } from '../src/util.js';
+import { ingestFile, nextBlock } from '../src/ingest.js';
+import { grounding, entailment, clarity, product, grill, ready, review, devcheck } from '../src/gates.js';
+import { emit, emittable, toMarkdown } from '../src/emit.js';
+import { approvalRequest, checkApproval } from '../src/approval.js';
+import { evaluate } from '../src/eval.js';
+import { loadRun, report, blockedTickets } from '../src/report.js';
+import { install, detect, ALL, workflowDir } from '../src/adapters.js';
+import { discover, repoReader } from '../src/context.js';
+import { mergeCandidates, readShards, readDevchecks, LENS_NAMES } from '../src/merge.js';
+import { nextRound, openIn, uiBatches, questionsMd, parseReplies, answerLines, applyAnswers } from '../src/grill.js';
+
+const HELP = `TraceTicket: from messy client call to verified ticket, with receipts
+
+  npx traceticket init [--target a,b|all] [--dry-run]   install into this repo (auto-detects IDE/agent)
+  traceticket ingest <file> --run <name>                    number the source into spans.json
+  traceticket ingest <answers> --run <name> --append        add client answers as new spans (source: client)
+  traceticket merge candidates --run <name>                 join the 3 parallel extractors' candidates.<lens>.json (fails if any lens did not run)
+  traceticket merge devcheck --run <name>                   join the parallel developer checks devcheck/<ticket>.json (fails if a READY ticket has none)
+  traceticket gate grounding --run <name>                   Gate A  verbatim quote check (needs merge.json: extraction must have fanned out)
+  traceticket docs --run <name> [--product dir]             find PRDs, specs, ADRs, glossaries, READMEs in the repo -> context.json
+  traceticket gate product   --run <name> [--product dir]   Gate P  product-fit evidence quotes a repo file verbatim (default: repo root)
+  traceticket gate entailment --run <name>                  Gate A2 verifier output is complete, cites id and span, no overclaim reaches product fit
+  traceticket gate clarity   --run <name> [--glossary a,b]  Gate B  vague / missing actor, trigger / conflicts
+  traceticket gate grill     --run <name>                   Gate G  every question answered from a span, or parked
+  traceticket gate ready     --run <name>                   Gate C  schema, Gherkin, grounding, product fit, nothing open
+  traceticket gate review    --run <name> [--threshold 8]   Gate R  no unresolved blocking review finding
+  traceticket gate devcheck  --run <name>                   Gate D  developer could build it without asking
+  traceticket questions --run <name> [--round N]            write questions-round-N.md and print payloads for the host's multiple-choice UI
+  traceticket answers --run <name> [--file f]               record pasted replies (Q3: B ...) from stdin or a file as client spans and update questions.json
+  traceticket render --run <name> [--ticket T-001]           print ticket Markdown to read (files nothing, needs no approval)
+  traceticket approval --run <name>                         write approval.md for a human to sign (APPROVED by <name>)
+  traceticket emit --run <name> [--gh]                      tickets.md for tickets that passed C, R, D and a human approval (--gh files issues)
+  traceticket report --run <name>                           REPORT.md built from the run JSON
+  traceticket eval --run <name> --key <answer_key.json>     score the run against an answer key
+  traceticket status --run <name>                           show which steps have produced output
+
+targets: ${ALL.join(', ')}
+Every command prints JSON. Must-pass gates (P, G, C, R, D) exit 1 on failure; filter gates (A, B) exit 1 when they flag anything.`;
+
+function parse(argv) {
+  const pos = [], flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) { const k = argv[i].slice(2); flags[k] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true; }
+    else pos.push(argv[i]);
+  }
+  return { pos, flags };
+}
+const out = (o) => console.log(JSON.stringify(o, null, 2));
+const need = (f, k) => { if (!f[k] || f[k] === true) { console.error(`missing --${k}`); process.exit(2); } return f[k]; };
+const list = (dir, file, field) => readJson(path.join(dir, file))[field];
+const readJsonIf = (p) => (fs.existsSync(p) ? readJson(p) : null);
+// READY tickets that review did not already hold: each needs a developer check.
+function devcheckRequired(dir) {
+  const ready = readJsonIf(path.join(dir, 'ready.json')) ?? [];
+  const held = new Set((readJsonIf(path.join(dir, 'review_check.json')) ?? []).filter((r) => !r.pass).map((r) => r.ticket));
+  return ready.filter((r) => r.status === 'READY' && !held.has(r.id)).map((r) => r.id);
+}
+
+// Evidence paths are relative to --product when given, otherwise to the repo root (docs and code alike).
+function productRoot(flags) {
+  const dir = path.resolve(flags.product && flags.product !== true ? flags.product : process.env.SDLC_ROOT || '.');
+  if (!fs.existsSync(dir)) throw new Error(`product context not found at ${dir}`);
+  return dir;
+}
+
+const GATE_OUT = { grounding: 'grounding.json', entailment: 'entailment_check.json', product: 'product_check.json', clarity: 'clarity.json', grill: 'grill.json',
+  ready: 'ready.json', review: 'review_check.json', devcheck: 'devcheck_check.json' };
+
+function runGate(sub, dir, flags) {
+  const spans = () => list(dir, 'spans.json', 'spans');
+  if (sub === 'grounding') {
+    if (!fs.existsSync(path.join(dir, 'merge.json')))
+      return [{ id: 'extraction', pass: false, status: 'NOT_FANNED_OUT', reason: 'merge.json is missing: extraction must run all three lens extractors in parallel, then `traceticket merge candidates --run <run>`' }];
+    return grounding(spans(), list(dir, 'candidates.json', 'candidates'));
+  }
+  if (sub === 'entailment') {
+    const run = loadRun(dir);
+    if (!run.entailment) throw new Error('entailment.json not found: the verifier has not run');
+    return entailment(run.candidates, run.grounding ?? [], run.entailment, run.product_fit ?? []);
+  }
+  if (sub === 'clarity') return clarity(list(dir, 'candidates.json', 'candidates'), { glossary: flags.glossary ? String(flags.glossary).split(',') : [] });
+  if (sub === 'product') {
+    const run = loadRun(dir);
+    const skip = new Set([...(run.grounding ?? []).filter((r) => !r.pass).map((r) => r.id),
+      ...(run.entailment ?? []).filter((v) => v.verdict === 'unsupported').map((v) => v.id)]);
+    return product(repoReader(productRoot(flags)), run.candidates, run.product_fit ?? [], { skip, context: readJsonIf(path.join(dir, 'context.json')) });
+  }
+  if (sub === 'grill') return grill(spans(), list(dir, 'questions.json', 'questions'));
+  if (sub === 'ready') {
+    const q = path.join(dir, 'questions.json');
+    return ready(spans(), list(dir, 'tickets.json', 'tickets'), { questions: fs.existsSync(q) ? readJson(q).questions : [] });
+  }
+  if (sub === 'review') return review(list(dir, 'review.json', 'findings'), { threshold: flags.threshold ? +flags.threshold : 8 });
+  if (sub === 'devcheck') return devcheck(list(dir, 'devcheck.json', 'verdicts'), { required: devcheckRequired(dir) });
+  throw new Error(`gate must be one of: ${Object.keys(GATE_OUT).join(' | ')}`);
+}
+
+const { pos, flags } = parse(process.argv.slice(2));
+const [cmd, sub] = pos;
+try {
+  if (!cmd || cmd === 'help' || flags.help) { console.log(HELP); }
+  else if (cmd === 'init') {
+    const targets = !flags.target ? detect() : flags.target === 'all' ? ALL : String(flags.target).split(',');
+    out({ targets, installed: install(targets, process.cwd(), { dryRun: !!flags['dry-run'] }), next: 'Restart your IDE, then run: /call-to-tickets <transcript file>' });
+  }
+  else if (cmd === 'ingest') {
+    const file = path.join(runDir(need(flags, 'run')), 'spans.json');
+    if (flags.append) {
+      const cur = readJson(file);
+      const added = ingestFile(sub, { start: nextBlock(cur.spans), source: flags.source && flags.source !== true ? flags.source : 'client' });
+      writeJson(file, { ...cur, spans: [...cur.spans, ...added] });
+      out({ added: added.length, ids: added.map((s) => s.id), total: cur.spans.length + added.length });
+    } else {
+      const spans = ingestFile(sub, { source: 'input' });
+      writeJson(file, { source: path.basename(sub), spans });
+      out({ spans: spans.length });
+    }
+  }
+  else if (cmd === 'docs') {
+    const ctx = discover(productRoot(flags));
+    writeJson(path.join(runDir(need(flags, 'run')), 'context.json'), ctx);
+    out({ counts: ctx.counts, truncated: ctx.truncated, top: ctx.files.filter((f) => f.kind !== 'doc').slice(0, 25).map((f) => `${f.kind}: ${f.path}`) });
+  }
+  else if (cmd === 'gate') {
+    const dir = runDir(need(flags, 'run'));
+    const res = runGate(sub, dir, flags);
+    writeJson(path.join(dir, GATE_OUT[sub]), res);
+    out(res);
+    if (res.some((r) => !r.pass)) process.exitCode = 1;
+  }
+  else if (cmd === 'questions') {
+    const dir = runDir(need(flags, 'run'));
+    const questions = readJson(`${dir}/questions.json`).questions;
+    const round = flags.round && flags.round !== true ? +flags.round : questions.some((q) => !q.status || q.status === 'open') ? nextRound(questions) : null;
+    const qs = round ? openIn(questions, round) : [];
+    if (!qs.length) out({ status: 'NO_OPEN_QUESTIONS' });
+    else {
+      const file = `${dir}/questions-round-${round}.md`;
+      fs.writeFileSync(file, questionsMd(flags.run, round, qs));
+      out({ round, count: qs.length, file, batches: uiBatches(qs),
+        how: 'Ask each batch with the host multiple-choice tool (Cursor AskQuestion, Claude Code AskUserQuestion), then STOP. Record the replies with `traceticket answers`. The .md file can also be sent to the client as is.' });
+    }
+  }
+  else if (cmd === 'answers') {
+    const dir = runDir(need(flags, 'run'));
+    const qf = `${dir}/questions.json`, sf = `${dir}/spans.json`;
+    const qj = readJson(qf);
+    const text = flags.file && flags.file !== true ? fs.readFileSync(flags.file, 'utf8') : fs.readFileSync(0, 'utf8');
+    const replies = parseReplies(text);
+    if (!replies.size) { console.error('error: no "Q3: answer" lines found in the pasted replies'); process.exit(2); }
+    const round = flags.round && flags.round !== true ? +flags.round : Math.min(...[...replies.keys()].map((id) => qj.questions.find((q) => q.id === id)?.round ?? 1));
+    const { text: lines, used, problems } = answerLines(qj.questions, round, replies);
+    if (problems.length) { console.error(`error: ${problems.join('; ')}`); process.exit(2); }
+    let n = 1; while (fs.existsSync(`${dir}/answers-${n}.txt`)) n++;
+    const file = `${dir}/answers-${n}.txt`;
+    fs.writeFileSync(file, lines);
+    const cur = readJson(sf);
+    const added = ingestFile(file, { start: nextBlock(cur.spans), source: 'client' });
+    writeJson(sf, { ...cur, spans: [...cur.spans, ...added] });
+    const updated = applyAnswers(qj.questions, used, added.map((s) => s.id));
+    writeJson(qf, { ...qj, questions: updated });
+    const open = updated.filter((q) => !q.status || q.status === 'open');
+    out({ file, recorded: used.map((u, i) => ({ id: u.id, status: u.parked ? 'parked' : 'answered', span: added[i].id })), still_open: open.map((q) => q.id),
+      next: open.length ? 'ask the next round with `traceticket questions`' : 'no open questions: re-run extract (parallel), product fit and clarity on the new spans, then `traceticket gate grill`' });
+  }
+  else if (cmd === 'render') {
+    const dir = runDir(need(flags, 'run'));
+    const tickets = readJson(`${dir}/tickets.json`).tickets;
+    const held = new Set((readJsonIf(path.join(dir, 'review_check.json')) ?? []).filter((r) => !r.pass).map((r) => r.ticket));
+    const ready = new Set((readJsonIf(path.join(dir, 'ready.json')) ?? []).filter((r) => r.status === 'READY').map((r) => r.id));
+    const pick = flags.ticket && flags.ticket !== true
+      ? tickets.filter((t) => t.id === flags.ticket)
+      : tickets.filter((t) => ready.has(t.id) && !held.has(t.id));
+    if (!pick.length) throw new Error(flags.ticket ? `no ticket ${flags.ticket}` : 'no READY ticket to render');
+    console.log(pick.map(toMarkdown).join('\n---\n\n'));
+  }
+  else if (cmd === 'merge') {
+    const dir = runDir(need(flags, 'run'));
+    if (sub === 'candidates') {
+      const { shards, problems, meta } = readShards(dir);
+      if (problems.length) { console.error(`error: extraction did not fan out. ${problems.join('; ')}`); process.exit(1); }
+      const { candidates, summary } = mergeCandidates(readJsonIf(path.join(dir, 'candidates.json'))?.candidates ?? [], shards);
+      const skipped = LENS_NAMES.flatMap((l) => meta[l].skipped.map((s) => `${l}: ${s}`));
+      writeJson(path.join(dir, 'candidates.json'), { candidates, status: 'DONE', skipped });
+      writeJson(path.join(dir, 'merge.json'), { ...summary, lenses: LENS_NAMES, shardStatus: Object.fromEntries(LENS_NAMES.map((l) => [l, meta[l].status])) });
+      out(summary);
+    } else if (sub === 'devcheck') {
+      const { verdicts, skipped, problems } = readDevchecks(dir);
+      const missing = devcheckRequired(dir).filter((id) => !verdicts.some((v) => v.ticket === id));
+      if (problems.length || missing.length) {
+        console.error(`error: developer checks did not all run. ${[...problems, ...missing.map((id) => `devcheck/${id}.json is missing: no developer agent ran for ${id}`)].join('; ')}`);
+        process.exit(1);
+      }
+      writeJson(path.join(dir, 'devcheck.json'), { verdicts, status: 'DONE', skipped });
+      out({ verdicts: verdicts.length });
+    } else throw new Error('merge must be candidates | devcheck');
+  }
+  else if (cmd === 'approval') {
+    const dir = runDir(need(flags, 'run'));
+    const set = emittable(readJson(`${dir}/tickets.json`).tickets, readJson(`${dir}/ready.json`), blockedTickets(loadRun(dir)));
+    const file = `${dir}/approval.md`;
+    if (!set.length) out({ tickets: [], status: 'NOTHING_TO_APPROVE', note: 'no ticket passed Gates C, R and D' });
+    else {
+      const cur = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+      const state = checkApproval(cur, set);
+      if (!state.ok) fs.writeFileSync(file, approvalRequest(flags.run, set));
+      out({ file, tickets: set.map((t) => t.id), status: state.ok ? `APPROVED by ${state.by}` : 'PENDING', ...(state.by && !state.ok && { voided: state.reason }) });
+    }
+  }
+  else if (cmd === 'emit') {
+    const dir = runDir(need(flags, 'run'));
+    const tickets = readJson(`${dir}/tickets.json`).tickets, results = readJson(`${dir}/ready.json`), blocked = blockedTickets(loadRun(dir));
+    const set = emittable(tickets, results, blocked);
+    if (set.length) {
+      const file = `${dir}/approval.md`;
+      const ap = checkApproval(fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '', set);
+      if (!ap.ok) { console.error(`error: emit needs human approval: ${ap.reason}`); process.exit(1); }
+    }
+    const r = emit(tickets, results, { gh: !!flags.gh, blocked });
+    fs.writeFileSync(`${dir}/tickets.md`, r.markdown);
+    out({ ready: r.ready, skipped: r.skipped, file: `${dir}/tickets.md` });
+  }
+  else if (cmd === 'report') {
+    const dir = runDir(need(flags, 'run'));
+    fs.writeFileSync(`${dir}/REPORT.md`, report(loadRun(dir), flags.run));
+    out({ file: `${dir}/REPORT.md` });
+  }
+  else if (cmd === 'eval') {
+    const dir = runDir(need(flags, 'run'));
+    const res = evaluate(readJson(need(flags, 'key')), loadRun(dir));
+    writeJson(`${dir}/eval.json`, res);
+    out(res);
+  }
+  else if (cmd === 'status') {
+    const dir = runDir(need(flags, 'run'));
+    const wf = readJson(path.join(workflowDir, 'workflow.json'));
+    out(wf.steps.map((s) => ({ step: s.id, kind: s.kind, done: fs.existsSync(path.join(dir, s.out)) })));
+  }
+  else { console.error(HELP); process.exit(2); }
+} catch (e) { console.error(`error: ${e.message}`); process.exit(2); }

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "traceticket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "From messy client call to verified ticket, with receipts. Parallel AI agents propose, scripts check every quote, humans approve. Installs into Claude Code, Cursor, Copilot, Windsurf, Codex, Gemini and any AGENTS.md-aware agent.",
+  "type": "module",
+  "bin": {
+    "traceticket": "bin/cli.js",
+    "sdlc-kit": "bin/cli.js"
+  },
+  "files": ["bin", "src", "workflow"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "keywords": [
+    "traceticket", "requirements", "user-stories", "gherkin", "acceptance-criteria", "transcript",
+    "ai-agents", "claude-code", "cursor", "agents-md", "quality-gates", "sdlc", "jira", "backlog"
+  ],
+  "license": "MIT"
+}

package/src/adapters.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const workflowDir = path.join(here, '..', 'workflow');
+const load = () => JSON.parse(fs.readFileSync(path.join(workflowDir, 'workflow.json'), 'utf8'));
+const read = (...p) => fs.readFileSync(path.join(workflowDir, ...p), 'utf8');
+const ls = (...p) => fs.readdirSync(path.join(workflowDir, ...p));
+const ORCHESTRATOR = 'transcript-to-tickets';
+
+export function renderSteps(wf = load()) {
+  let phase = '';
+  return wf.steps.map((s, i) => {
+    const head = s.phase !== phase ? `\n### ${(phase = s.phase)}\n\n` : '';
+    const tag = [s.kind, s.gate && `Gate ${s.gate}`, s.isolated && 'isolated', s.optional && 'optional'].filter(Boolean).join(', ');
+    const how = s.run ? `Run \`${s.run}\`.`
+      : `Follow \`.sdlc/skills/${s.skill}/SKILL.md\`${s.agent ? ` (delegate to the \`${s.agent}\` agent)` : ''}. Writes \`${s.out}\`.`;
+    const loop = s.loop ? `\n   Loop: ${s.loop}` : '';
+    if (s.kind === 'parallel') {
+      const spawn = s.spawn.map((x) => `\`${x.agent}\`${x.each ? ` once per ${x.each}${x.values ? ` (${x.values.join(', ')})` : ''}` : ' once'} → writes \`${x.out}\``).join('; ');
+      const hostRule = 'Send all spawns in ONE turn (one message with several agent calls). Never start them one after another, and never replace the fan-out with a single agent.';
+      return `${head}${i + 1}. **${s.id}** [parallel${s.always ? ', always' : ''}${s.gate ? `, Gate ${s.gate}` : ''}] ${s.desc}\n   Spawn in parallel: ${spawn}. ${hostRule} Follow \`.sdlc/skills/${s.skill}/SKILL.md\`.${loop}`;
+    }
+    return `${head}${i + 1}. **${s.id}** [${tag}] ${s.desc}\n   ${how}${loop}`;
+  }).join('\n');
+}
+
+const withSteps = (md) => md.replace('<!-- steps -->', `## Steps\n\nArtifacts live in \`${load().dir}\`. Run steps in order; do not skip or reorder.\n${renderSteps()}`);
+const stripFm = (md) => md.replace(/^---\n[\s\S]*?\n---\n+/, '');
+const skill = (name) => (name === ORCHESTRATOR ? withSteps : (x) => x)(read('skills', name, 'SKILL.md'));
+
+// One canonical instruction body (the orchestrator skill), rendered into every host's native format.
+export const renderBody = () => stripFm(skill(ORCHESTRATOR));
+
+const fm = (obj) => `---\n${Object.entries(obj).map(([k, v]) => `${k}: ${v}`).join('\n')}\n---\n\n`;
+const DESC = 'Turn a client transcript, email or one-liner into grounded, product-checked, client-confirmed tickets.';
+const MARK = (id) => [`<!-- sdlc-kit:${id}:start -->`, `<!-- sdlc-kit:${id}:end -->`];
+const skillFiles = (root) => ls('skills').map((n) => [`${root}/${n}/SKILL.md`, skill(n)]);
+
+// Thin slash commands that load a skill (Addy Osmani / ECC pattern: commands are shims, skills hold the process).
+// Verb-first names, one canonical command per job.
+const COMMANDS = {
+  'call-to-tickets': [ORCHESTRATOR, '<transcript file> [--product <dir>] [--client <answers.md>]'],
+  'grill-client': ['client-grilling', '<run>'],
+  'review-tickets': ['ticket-readiness-review', '<run>'],
+  'run-report': ['run-reporting', '<run>'],
+};
+const command = ([name, hint]) => fm({ description: read('skills', name, 'SKILL.md').match(/description: (.+)/)[1].split('. ')[0] + '.', 'argument-hint': hint })
+  + `Use the \`${name}\` skill (\`.sdlc/skills/${name}/SKILL.md\`) and follow it exactly.\n\nInput: $ARGUMENTS\n`;
+// Cursor custom commands are plain Markdown; whatever is typed after the command is the input.
+const cursorCommand = (cmd, [skill, hint]) => `# /${cmd} ${hint}\n\nUse the \`${skill}\` skill (\`.sdlc/skills/${skill}/SKILL.md\`) and follow it exactly.\n\nInput: the text the user typed after the command (${hint}).\n`;
+
+// Cursor agents take name, model and description; tools are not declared and the model follows the user's choice.
+const cursorAgent = (md) => md.replace(/^tools: .*\n/m, '').replace(/^model: .*$/m, 'model: inherit');
+
+// kind 'files' writes files we own; kind 'section' upserts a marked block in a shared file.
+export const ADAPTERS = {
+  claude: { kind: 'files', files: () => [...skillFiles('.claude/skills'), ...ls('agents').map((a) => [`.claude/agents/${a}`, read('agents', a)])] },
+  'claude-command': { kind: 'files', files: () => Object.entries(COMMANDS).map(([c, v]) => [`.claude/commands/${c}.md`, command(v)]) },
+  cursor: { kind: 'files', files: (b) => [['.cursor/rules/sdlc.mdc', fm({ description: DESC, alwaysApply: 'false' }) + b], ...skillFiles('.cursor/skills'),
+    ...ls('agents').map((a) => [`.cursor/agents/${a}`, cursorAgent(read('agents', a))]),
+    ...Object.entries(COMMANDS).map(([c, v]) => [`.cursor/commands/${c}.md`, cursorCommand(c, v)])] },
+  windsurf: { kind: 'files', files: (b) => [['.windsurf/rules/sdlc.md', fm({ trigger: 'model_decision', description: DESC }) + b]] },
+  cline: { kind: 'files', files: (b) => [['.clinerules/sdlc.md', b]] },
+  copilot: { kind: 'section', path: '.github/copilot-instructions.md', id: 'copilot' },
+  agents: { kind: 'section', path: 'AGENTS.md', id: 'agents' }, // Codex, Aider, Zed, Jules, opencode, etc.
+  gemini: { kind: 'section', path: 'GEMINI.md', id: 'gemini' },
+  opencode: { kind: 'files', files: (b) => [['.opencode/command/sdlc.md', fm({ description: DESC }) + b + '\nInput: $ARGUMENTS\n']] },
+};
+
+export const ALL = Object.keys(ADAPTERS);
+
+export function install(targets, cwd = process.cwd(), { dryRun = false } = {}) {
+  const body = renderBody();
+  const written = [];
+  const put = (rel, content) => { if (dryRun) return; const f = path.join(cwd, rel); fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, content); };
+
+  // Shared, host-independent assets: every host's instructions point here.
+  for (const [p, c] of skillFiles('.sdlc/skills')) put(p, c);
+  for (const a of ls('agents')) put(`.sdlc/agents/${a}`, read('agents', a));
+  for (const r of ls('references')) put(`.sdlc/references/${r}`, read('references', r));
+  put('.sdlc/workflow.json', read('workflow.json'));
+  put('.sdlc/INSTRUCTIONS.md', body);
+  written.push('.sdlc/');
+
+  // Runs hold client transcripts and answers: keep them out of git in every repo we install into.
+  const gi = path.join(cwd, '.gitignore');
+  const cur = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+  if (!/^\/?\.sdlc\/runs\/?$/m.test(cur)) {
+    put('.gitignore', `${cur}${cur && !cur.endsWith('\n') ? '\n' : ''}\n# TraceTicket: runs hold client transcripts\n.sdlc/runs/\n`);
+    written.push('.gitignore (+ .sdlc/runs/)');
+  }
+
+  for (const t of targets) {
+    const a = ADAPTERS[t];
+    if (!a) throw new Error(`unknown target "${t}". Valid: ${ALL.join(', ')}`);
+    if (a.kind === 'files') for (const [p, c] of a.files(body)) { put(p, c); written.push(p); }
+    else {
+      const [s, e] = MARK(a.id);
+      const block = `${s}\n${body}${e}\n`;
+      const f = path.join(cwd, a.path);
+      const cur = fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '';
+      const re = new RegExp(`${s}[\\s\\S]*?${e}\\n?`);
+      put(a.path, re.test(cur) ? cur.replace(re, block) : (cur ? cur.replace(/\n*$/, '\n\n') : '') + block);
+      written.push(a.path);
+    }
+  }
+
+  return written;
+}
+
+// Pick targets from what the repo already uses.
+export function detect(cwd = process.cwd()) {
+  const has = (p) => fs.existsSync(path.join(cwd, p));
+  const t = [];
+  if (has('.claude') || has('CLAUDE.md')) t.push('claude', 'claude-command');
+  if (has('.cursor')) t.push('cursor');
+  if (has('.opencode') || has('opencode.json')) t.push('opencode');
+  if (has('.gemini') || has('GEMINI.md')) t.push('gemini');
+  if (has('.windsurf') || has('.windsurfrules')) t.push('windsurf');
+  if (has('.clinerules')) t.push('cline');
+  if (has('.github')) t.push('copilot');
+  t.push('agents'); // always: the universal fallback
+  return t;
+}

package/src/approval.js

@@ -0,0 +1,53 @@
+import crypto from 'node:crypto';
+import { norm } from './util.js';
+import { toMarkdown } from './emit.js';
+
+// A human signs off on the exact ticket set that will be emitted. The fingerprint covers what a reader
+// approves (id, summary, story, scenarios and their quotes), so editing a ticket after approval voids it.
+export const ticketSetHash = (tickets) => crypto.createHash('sha256').update(JSON.stringify(
+  tickets.map((t) => [t.id, t.summary ?? t.title, t.story, t.acceptance_criteria?.map((a) => [a.scenario, a.given, a.when, a.then, a.gherkin, a.source])]),
+)).digest('hex').slice(0, 16);
+
+// The whole review packet in one file: a human reads the tickets here and signs at the bottom.
+export function approvalRequest(run, tickets) {
+  const list = tickets.map((t) => `- [ ] ${t.id}: ${t.summary ?? t.title} (${t.acceptance_criteria?.length ?? 0} scenarios, ${t.product_fit?.label ?? 'no fit'})`).join('\n');
+  return `# Approval to emit: ${run}
+
+Ticket set: sha256:${ticketSetHash(tickets)}
+
+Approving files these ${tickets.length} ticket(s). Read each one below, check that every quote is what the client really said, then sign at the bottom.
+
+## Checklist
+
+${list}
+
+## Decision (human only)
+
+Replace the status line at the bottom with one of:
+
+- \`APPROVED by <your name>\` to file these tickets
+- \`REJECTED by <your name>: <reason>\` to send them back
+
+Agents must never edit this file. \`traceticket emit\` refuses to run without a signature, and any change to the tickets afterwards voids it.
+
+Status: PENDING
+
+---
+
+## Tickets
+
+${tickets.map(toMarkdown).join('\n---\n\n')}`;
+}
+
+// Returns { ok, by, reason }. The placeholder "<name>" and an empty name never count.
+export function checkApproval(text, tickets) {
+  if (!text) return { ok: false, reason: 'approval.md does not exist: run `traceticket approval --run <run>`, then have a human approve it' };
+  const rej = /^REJECTED by (.+?)\s*$/m.exec(text);
+  if (rej) return { ok: false, rejected: true, reason: `rejected by ${norm(rej[1])}: fix the tickets, then run \`traceticket approval --run <run>\` again` };
+  const m = /^APPROVED by (.+?)\s*$/m.exec(text);
+  const by = m && norm(m[1]);
+  if (!by || /^<.*>$/.test(by) || by.toLowerCase() === 'name') return { ok: false, reason: 'approval.md has no "APPROVED by <name>" line from a human' };
+  const h = /^Ticket set: sha256:([0-9a-f]+)\s*$/m.exec(text)?.[1];
+  if (h !== ticketSetHash(tickets)) return { ok: false, by, reason: 'the tickets changed after approval (ticket set fingerprint differs): run `traceticket approval --run <run>` and approve again' };
+  return { ok: true, by };
+}

package/src/context.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Folders that never hold product truth (dependencies, build output, our own run data).
+export const SKIP = new Set(['node_modules', '.git', '.sdlc', 'dist', 'build', 'out', '.next', '.nuxt', 'coverage',
+  'vendor', '.venv', 'venv', '__pycache__', 'target', '.idea', '.vscode', '.claude', '.cursor', '.turbo', '.cache',
+  'test-results', 'playwright-report', 'storybook-static']);
+const DOC_EXT = /\.(md|mdx|markdown|rst|txt|adoc)$/i;
+// A folder or file must be named for the kind (docs/prd/, PRD-swaps.md, requirements.md), not merely contain the word.
+const named = (words, prefixes) => new RegExp(`(^|/)(${words})(/|\\.[a-z]+$)|(^|/)(${prefixes})[-_ ]`, 'i');
+const KIND = [
+  ['prd', named('prds?|frds?|srs|requirements?|product[-_ ]?requirements?|brd|mrd', 'prd|frd|srs|brd|mrd')],
+  ['adr', named('adrs?|decisions?|decision[-_ ]?records?', 'adr')],
+  ['spec', named('specs?|rfcs?|design|architecture|features?|roadmap|user[-_ ]?stories', 'spec|rfc')],
+  ['glossary', /(^|\/)((project|product|domain)[_-])?(context|overview|glossary|domain|ubiquitous[-_ ]?language)\.(md|mdx)$/i],
+  ['readme', /(^|\/)readme\.(md|mdx|rst|txt)$/i],
+];
+// Housekeeping files, dependency lists and agent instruction files describe the repo's tooling, not the product.
+const NOISE = /(^|\/)((changelog|license|licence|code_of_conduct|contributing|security|skill|agents|claude|gemini|copilot-instructions)\.(md|txt)|requirements[\w.-]*\.txt)$/i;
+
+// A README inside a docs tree describes a feature (docs/authentication/README.md), so it ranks with specs.
+const kindOf = (rel) => {
+  const k = KIND.find(([, re]) => re.test(rel))?.[0] ?? 'doc';
+  return k === 'readme' && /(^|\/)docs?\/.+\//i.test(rel) ? 'spec' : k;
+};
+// Dot-folders (.git, .agents, .cursor, .github ...) hold tooling and config. Only their top-level
+// overview/context/glossary files count (e.g. .agents/PROJECT_OVERVIEW.md); the rest is skipped.
+const skipDir = (name) => name.startsWith('.') || SKIP.has(name);
+const CONTEXT_FILE = /^((project|product|domain)[_-])?(overview|context|glossary)\.(md|mdx)$/i;
+
+// Finds the documents that describe what the product does: PRDs, specs, ADRs, glossaries, READMEs.
+// Paths are relative to root and use forward slashes, so agents and gates cite them the same way.
+export function discover(root, { limit = 1000 } = {}) {
+  const files = [];
+  const add = (dir, name) => {
+    const rel = path.relative(root, path.join(dir, name)).split(path.sep).join('/');
+    if (DOC_EXT.test(name) && !NOISE.test(rel)) files.push({ path: rel, kind: kindOf(rel), bytes: fs.statSync(path.join(dir, name)).size });
+  };
+  // Inside a dot-folder, only its top-level overview/context/glossary files (e.g. .agents/PROJECT_OVERVIEW.md).
+  const peek = (dir) => { for (const e of fs.readdirSync(dir, { withFileTypes: true })) if (e.isFile() && CONTEXT_FILE.test(e.name)) add(dir, e.name); };
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) {
+        if (!skipDir(e.name)) walk(path.join(dir, e.name));
+        else if (e.name.startsWith('.') && !SKIP.has(e.name)) peek(path.join(dir, e.name));
+        continue;
+      }
+      add(dir, e.name);
+    }
+  };
+  walk(root);
+  const rank = ['prd', 'spec', 'adr', 'glossary', 'readme', 'doc'];
+  files.sort((a, b) => rank.indexOf(a.kind) - rank.indexOf(b.kind) || a.path.localeCompare(b.path));
+  const counts = Object.fromEntries(rank.map((k) => [k, files.filter((f) => f.kind === k).length]));
+  return { root: '.', counts, truncated: files.length > limit, files: files.slice(0, limit) };
+}
+
+// Never accepted as evidence, so an agent has no reason to open them.
+const SECRET = /^\.env(\..*)?$|\.(pem|key|p12|pfx)$|^(id_rsa|id_ed25519)|secret|credential/i;
+
+// Reads a repo file for evidence checks. Refuses paths outside root, inside SKIP folders, or that look like secrets.
+export function repoReader(root) {
+  const base = path.resolve(root);
+  return (rel) => {
+    if (!rel || typeof rel !== 'string') return null;
+    const abs = path.resolve(base, rel);
+    if (abs !== base && !abs.startsWith(base + path.sep)) return null;
+    const parts = path.relative(base, abs).split(path.sep);
+    const peekable = parts.length === 2 && parts[0].startsWith('.') && !SKIP.has(parts[0]) && CONTEXT_FILE.test(parts[1]);
+    if (!peekable && parts.slice(0, -1).some(skipDir)) return null;
+    if (SECRET.test(path.basename(abs))) return null;
+    try { return fs.statSync(abs).isFile() ? fs.readFileSync(abs, 'utf8') : null; } catch { return null; }
+  };
+}