create-issflow 1.1.0 → 1.2.1

package/README.md

@@ -25,7 +25,7 @@ Flags:
 The portable kit (every tool) in `<project>/.claude/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
-- `commands/` — `/overview` `/propose` `/phase` `/change-request` `/replan` `/quick` `/synthesize` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
+- `commands/` — `/overview` `/propose` `/phase` `/ui-audit` `/qa-audit` `/security-audit` `/change-request` `/replan` `/quick` `/synthesize` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
 - `skills/` — caveman · grill-me · karpathy-guidelines · ux-design
 - `hooks/` — session-start · pre-compact · subagent-stop
 - `istartsoft-flow/METHODOLOGY.md` — the full methodology (single source of truth)

package/bin/cli.js

@@ -107,8 +107,21 @@ function copyTemplateCommands(destDir) {
 // ---- adapters (keep the methodology single-source — these POINT at it) ------
 
 function adapterClaude() {
+  // Claude Code auto-loads CLAUDE.md only — NOT AGENTS.md. Without a CLAUDE.md
+  // the methodology never enters context on its own (the SessionStart hook still
+  // injects the per-session summary, but the full single-source doc would not
+  // load). A one-line `@AGENTS.md` import gives Claude Code the full baseline
+  // while keeping ONE source of truth — no rule is restated here (anti-drift).
+  const c0 = conflicts;
+  writeFile('CLAUDE.md', claudeMd());
+  if (conflicts > c0) warnings.push('claude: you already keep a CLAUDE.md — ours was written as CLAUDE.md.issflow-new. Add a line `@AGENTS.md` to your CLAUDE.md so the methodology auto-loads.');
+  // Context-budget watchdog config (consumed by .claude/hooks/context-guard.js).
+  // Shipped default window:0 = auto-detect; flow-config.json lives at .claude root,
+  // outside build.js's copied DIRS, so the installer writes it here.
+  writeFile('.claude/flow-config.json', flowConfig());
   const HOOKS = {
     SessionStart: [{ matcher: 'startup|clear|compact', hooks: [{ type: 'command', command: 'node .claude/hooks/session-start.js' }] }],
+    PreToolUse:   [{ matcher: '*',                     hooks: [{ type: 'command', command: 'node .claude/hooks/context-guard.js' }] }],
     PreCompact:   [{ matcher: 'auto|manual',           hooks: [{ type: 'command', command: 'node .claude/hooks/pre-compact.js' }] }],
     SubagentStop: [{ hooks: [{ type: 'command', command: 'node .claude/hooks/subagent-stop.js' }] }],
   };
@@ -176,7 +189,7 @@ function adapterAider() {
 const ADAPTERS = { claude: adapterClaude, codex: adapterCodex, cursor: adapterCursor, gemini: adapterGemini, aider: adapterAider };
 
 const NEXT_STEPS = {
-  claude: 'Open Claude Code — the SessionStart hook fires automatically. Run /overview to bootstrap.',
+  claude: 'Open Claude Code — CLAUDE.md (@AGENTS.md) loads the methodology and the SessionStart hook fires automatically. Run /overview to bootstrap.',
   codex:  'Open Codex CLI — it reads AGENTS.md. Start by running the /overview procedure (.claude/commands/overview.md).',
   cursor: 'Open Cursor — the rule applies automatically. Run the /overview command to bootstrap.',
   gemini: 'Open Gemini CLI — it reads GEMINI.md. Run the SESSION-OPEN ritual, then the overview procedure.',
@@ -198,8 +211,9 @@ function agentsMd() {
     '## Roles — `.claude/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
-    '/overview · /propose · /phase · /change-request · /replan · /quick · /synthesize ·',
-    '/store-wisdom · /log-issue · /log-decision · /unstuck', '',
+    '/overview · /propose · /phase · /ui-audit · /qa-audit · /security-audit ·',
+    '/change-request · /replan · /quick · /synthesize · /runbook · /store-wisdom · /log-issue ·',
+    '/log-decision · /unstuck', '',
     '## Skills — `.claude/skills/` (loaded on demand)', '',
     'caveman · grill-me · karpathy-guidelines · ux-design · security (Secure SDLC) · code-standards', '',
     '## Autonomy', '',
@@ -224,6 +238,40 @@ function agentsMd() {
   ].join('\n');
 }
 
+function claudeMd() {
+  return [
+    '# CLAUDE.md — iStartSoftFlow (Claude Code entry)', '',
+    '@AGENTS.md', '',
+    'The import above is the single source of truth — it points to',
+    '`.claude/istartsoft-flow/METHODOLOGY.md` (read on demand). Do NOT restate any',
+    'rule here; this file only wires Claude-native mechanisms (anti-drift invariant).', '',
+    '## Claude-native wiring (automatic — see `.claude/settings.json`)', '',
+    '- **SessionStart** hook injects git state + `docs/STATE.md` + open `docs/ISSUES.md`',
+    '  + the rule summary each session — read those first.',
+    '- **PreCompact** + **SubagentStop** hooks run their rituals automatically.',
+    '- Commands in `.claude/commands/` run as `/name`; agents in `.claude/agents/` are',
+    '  native subagents.', '',
+  ].join('\n');
+}
+
+function flowConfig() {
+  return JSON.stringify({
+    context: {
+      window: 0,
+      warnPct: 60,
+      gatePct: 78,
+      _note: 'Context-budget watchdog (.claude/hooks/context-guard.js, PreToolUse hook). '
+        + 'window 0 = auto-detect from the model id (200000 for standard models). '
+        + 'Some 1M-context models report their id WITHOUT a [1m] tag, so auto-detect '
+        + 'assumes 200000 and may false-gate around 156k — if you run a 1M model, set '
+        + 'window:1000000 here by hand. warnPct = soft non-blocking nudge; gatePct = hard '
+        + 'block on NEW build work (Edit/Write-to-source/feature Task). Checkpoint paths '
+        + '(docs/**, STATE/ISSUES/snapshots), the synthesizer subagent, and all Bash are '
+        + 'never blocked.',
+    },
+  }, null, 2) + '\n';
+}
+
 // ---- main -------------------------------------------------------------------
 
 function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Scaffold the iStartSoftFlow AI-coding workflow into a project. Stack-agnostic, tool-agnostic (Claude Code, Codex, Cursor, Gemini, Aider), non-destructive.",
   "bin": {
     "create-issflow": "bin/cli.js"

package/template/.claude/commands/qa-audit.md

@@ -0,0 +1,53 @@
+---
+description: Holistic QA audit — sweep the WHOLE product's functional quality (test-coverage gaps, regression health, flaky tests, critical-flow e2e, error/edge handling), score it, and produce a prioritized findings report. On-demand or before a release. NOT the per-phase gate — the phase gate runs one phase's real suite; this audits the entire test estate + behaviour.
+argument-hint: [optional scope]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Purpose: a whole-product FUNCTIONAL QA audit — the QA counterpart of `/ui-audit`.
+The per-phase gate (rule 5) proves ONE phase's real suite is green; this audit checks
+the health + coverage of the ENTIRE test estate and the product's behaviour, end to
+end. Run before a release, after big changes, or on request.
+
+QA = "does it WORK right?" — a DIFFERENT axis from UI audit ("does it LOOK / meet
+standards right?"). Passing one never implies the other.
+
+## PRE-FLIGHT
+Read `docs/ENDPOINTS.md` (the surface), `docs/PLAN.md` (acceptance specs), and the
+`tests/` + `e2e/` suites. The acceptance criteria + ENDPOINTS are the rubric.
+
+## STEP 1 — INVENTORY
+List the public surface (endpoints, exported functions, CLI, message contracts) and
+the critical user flows (from OVERVIEW). These are what MUST be covered.
+
+## STEP 2 — SWEEP  (dispatch a worker to keep context lean)
+- **Coverage** — every ENDPOINTS entry + acceptance criterion has a real-API
+  regression test? List gaps. Untested branches / error paths?
+- **Critical flows** — does e2e cover the must-work journeys (auth, the core slice,
+  payments / data)?
+- **Regression health** — run the full REAL corpus (`scripts/regression.sh --real`).
+  Any reds?
+- **Flakiness** — tests that pass only on rerun (timing) — flag; don't hide.
+- **Negative / edge** — are abuse cases + edge inputs asserted, not just the happy path?
+- **Contract drift** — do the mock suites still match the real API?
+- **Test integrity** — tests written BLIND from the spec (no overfit)? None edited to pass?
+
+## STEP 3 — SCORE + FINDINGS
+Rate each dimension PASS / WARN / FAIL. Per finding:
+- **severity**: BLOCKER (red real test · uncovered critical flow) · MAJOR (coverage
+  gap · flaky) · MINOR (polish)
+- **location**: suite + case (or the uncovered surface)
+- **issue** + **fix**: the concrete change
+
+## STEP 4 — REPORT
+Write `docs/qa-audit-<YYYY-MM-DD>.md`: coverage map · per-dimension scoreboard ·
+findings sorted by severity · prioritized fix list. Log BLOCKER / MAJOR to
+`docs/ISSUES.md`.
+**VERDICT: SHIP | FIX-FIRST** — never ship with a red real test or an uncovered
+critical flow.
+
+## STEP 5 — REMEDIATE
+AUTO: dispatch `test-author` (BLIND) to fill coverage gaps, `debugger` for reds
+(budget 3), then re-run. Park what's blocked + report. Tests are written by
+`test-author` for impartiality — never weaken a test to make it pass.

package/template/.claude/commands/runbook.md

@@ -0,0 +1,38 @@
+---
+description: Capture an operational/incident scenario in docs/RUNBOOK.md — one grep-able markdown so prod-debug knowledge isn't re-derived under pressure.
+argument-hint: [scenario, or "from the incident we just solved"]
+---
+
+Caveman ULTRA mode.
+
+Distill an operational scenario into docs/RUNBOOK.md. Scenario: $ARGUMENTS
+
+This is the runbook pattern Anthropic's Security + Data-Infra teams converged on
+independently: consolidate stack traces, dashboard signals, and the exact
+remediation commands into ONE searchable file so the next incident is a lookup,
+not a re-investigation.
+
+If $ARGUMENTS says "from the incident we just solved" (or similar), distill the
+debugging session in context — symptom, the REAL root cause, the commands that
+fixed it — instead of asking the user to re-type it.
+
+Append an entry to docs/RUNBOOK.md (create the file if missing). Canonical format:
+```
+
+### <scenario title — searchable, literal symptom keywords>
+
+- trigger: <what you observe first — alert, error string, dashboard signal>
+- diagnose: <steps/commands to confirm the real root cause>
+- remediate: <the exact commands/actions that fix it>
+- verify: <how to confirm recovery — what "healthy" looks like>
+- refs: <dashboard URLs, docs, related docs/ISSUES.md titles>
+
+```
+Rules:
+- title carries literal symptom keywords -> grep finds it mid-incident.
+- remediate must be runnable as-is; no "investigate further".
+- mark any step that is irreversible / PROD-writing with ⚠ so it's never run blind.
+- cross-link the matching docs/ISSUES.md entry instead of duplicating root-cause prose.
+- newest scenario at the TOP.
+
+Confirm the entry back in 2 lines.

package/template/.claude/commands/security-audit.md

@@ -0,0 +1,56 @@
+---
+description: Holistic security audit — sweep the WHOLE product against the security cookbook (OWASP Top 10 / ASVS / WSTG / secrets / SCA / SAST / supply chain), score it, and produce a prioritized findings report. On-demand or before a release. NOT the per-phase gate — rule 11 checks one phase while coding; this audits the whole attack surface.
+argument-hint: [optional scope]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Purpose: a whole-product SECURITY audit — the security counterpart of `/ui-audit`
+and `/qa-audit`. The per-phase gate (rule 11) checks secrets/SCA/SAST + secure coding
+on ONE phase; this audit sweeps the ENTIRE attack surface and the product's security
+posture. Run before a release, after auth/data changes, or on request — and before
+the pre-deploy pentest, not instead of it.
+
+Security = "is it SAFE?" — a different axis from QA ("does it work?") and UI
+("does it look right?"). Passing those never implies this.
+
+## PRE-FLIGHT
+Read the rubric: `.claude/skills/security/SKILL.md` (the Secure SDLC cookbook) and
+its `references/` (OWASP Top 10 / ASVS / WSTG / ISO 27001 / SLSA). The cookbook IS the
+checklist — audit against it; don't invent criteria.
+
+## STEP 1 — INVENTORY (attack surface)
+Map it from `docs/ENDPOINTS.md` + the code: entry points (routes, inputs, file
+uploads, webhooks), trust boundaries, auth/session, data stores + PII, secrets,
+third-party deps, and outbound calls.
+
+## STEP 2 — SWEEP  (dispatch a worker to keep context lean)
+- **OWASP Top 10** — broken access control, crypto failures, injection (SQLi/XSS/
+  cmd), insecure design, misconfiguration, vulnerable components, auth failures,
+  integrity failures, logging/monitoring gaps, SSRF.
+- **AuthN / AuthZ** — every protected route enforces it; no IDOR; least privilege.
+- **Secrets** — none in code/history/config/prompts (run gitleaks/trufflehog if present).
+- **Dependencies (SCA)** — known CVEs (run `npm audit` / `pip-audit` / `osv-scanner`).
+- **SAST** — run semgrep / CodeQL if present; review hotspots otherwise.
+- **Input validation + output encoding** at every boundary; safe file handling.
+- **Crypto** — strong algorithms, no hardcoded keys, secrets at rest/in transit.
+- **Supply chain (SLSA)** — pinned deps, build integrity, no untrusted scripts.
+- **Logging / monitoring** — security events logged; no sensitive data in logs.
+- **Threat-model coverage** — were the design-stage abuse cases actually tested?
+
+## STEP 3 — SCORE + FINDINGS
+Rate each area PASS / WARN / FAIL. Per finding:
+- **severity**: CRITICAL · HIGH · MEDIUM · LOW (map to CVSS where it helps)
+- **location**: endpoint / file / dependency
+- **issue** + the OWASP/ASVS reference it breaks + **fix**
+
+## STEP 4 — REPORT
+Write `docs/security-audit-<YYYY-MM-DD>.md`: attack-surface map · per-area scoreboard ·
+findings sorted by severity · prioritized remediation. Log HIGH/CRITICAL to
+`docs/ISSUES.md`.
+**VERDICT: SHIP | FIX-FIRST** — never ship with an open HIGH or CRITICAL.
+
+## STEP 5 — REMEDIATE
+A security fix is security-sensitive (autonomy hard-stop): in AUTO, fix and re-audit
+but SURFACE the change for human sign-off before it lands. Park what's blocked +
+report. A clean `/security-audit` is a precondition for the pre-deploy pentest gate.

package/template/.claude/commands/ui-audit.md

@@ -0,0 +1,54 @@
+---
+description: Holistic UI audit — sweep the WHOLE product's UI against the ux-design cookbook (+ a11y / responsive / consistency), score it, and produce a prioritized findings report. On-demand or before a release. This is NOT the per-phase gate — the `ux-design` gate checks one screen at phase close (pass/block); this audit sweeps every screen and reports accumulated drift.
+argument-hint: [optional scope — a route, or "all"]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Purpose: a periodic, WHOLE-PRODUCT UI audit — distinct from the inline `ux-design`
+gate. The gate validates ONE screen at phase close; this AUDIT sweeps EVERY screen,
+scores the product, and surfaces drift that accumulated across changes. Run before a
+release, after big UI work, or on request.
+
+## PRE-FLIGHT
+Read the rubric: `.claude/skills/ux-design/SKILL.md` (the cookbook) and
+`references/wireframe-template.md` (the frame). The cookbook IS the checklist —
+do not invent new criteria; audit against it.
+
+## STEP 1 — INVENTORY
+List every screen / route / major component to audit (from the router, the
+wireframe baseline, or `$ARGUMENTS`). Audit shared components once.
+
+## STEP 2 — SWEEP  (dispatch a worker per area to keep context lean)
+Score each screen against the cookbook dimensions:
+- design tokens · 8-pt spacing · type scale (no raw hex/px)
+- iconography — a real SVG set, **NEVER emoji**
+- accessibility (WCAG 2.1 AA): contrast ≥ 4.5:1, visible focus, keyboard reach,
+  semantic HTML, labels / alt / aria, 44×44 targets, `prefers-reduced-motion`
+- state matrix: default · hover · focus · active · disabled · loading · empty · error
+- responsive breakpoints (no overflow / break)
+- content & i18n (no hardcoded strings; growth-safe)
+- consistency / wireframe conformance (no drift BETWEEN screens)
+Run automated tools if the project has them (axe-core / Lighthouse / pa11y) and fold
+their output in; otherwise do the manual cookbook sweep.
+
+## STEP 3 — SCORE + FINDINGS
+Rate each dimension PASS / WARN / FAIL. For every finding record:
+- **severity**: BLOCKER (a11y / contrast / unusable) · MAJOR (drift / missing state)
+  · MINOR (polish)
+- **location**: screen + element
+- **issue** + the cookbook rule it breaks
+- **fix**: the concrete change
+
+## STEP 4 — REPORT
+Write `docs/ui-audit-<YYYY-MM-DD>.md`:
+- coverage (screens audited) · a per-dimension scoreboard · the findings table sorted
+  by severity · a prioritized fix list.
+- Log BLOCKER / MAJOR findings to `docs/ISSUES.md`.
+- **VERDICT: SHIP | FIX-FIRST** — a release must not ship with open BLOCKERs.
+
+## STEP 5 — REMEDIATE
+AUTO: fix MINOR / MAJOR that don't change the visual direction, re-audit them, log.
+A new visual direction or a design-token change → confirm with the user first
+(hard rule 9 — UI conforms to the frame; new direction is a human call).
+Hand back the report + what was fixed vs parked.

package/template/.claude/hooks/context-guard.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+// PreToolUse context watchdog (iStartSoftFlow). Two tiers, one hook:
+//   warnPct  -> non-blocking nudge (additionalContext) once per climb into the band
+//   gatePct  -> HARD block of NEW build work (Edit/Write-to-source/feature Task)
+// Reads REAL token usage from the transcript. Fail-OPEN: any error -> allow,
+// never wedge the tool loop on a hook bug.
+const path = require('path');
+const fs = require('fs');
+
+const silent = () => process.exit(0);
+const out = (obj) => { process.stdout.write(JSON.stringify(obj)); process.exit(0); };
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (d) => (input += d));
+process.stdin.on('end', () => {
+  let evt;
+  try { evt = JSON.parse(input); } catch (_) { return silent(); }
+  try { run(evt); } catch (_) { silent(); }
+});
+
+function run(evt) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || evt.cwd || '.';
+  let ctx;
+  try { ctx = require(path.join(projectDir, '.claude/hooks/lib/ctx.js')); } catch (_) { return silent(); }
+  const cfg = ctx.loadConfig(projectDir);
+  const warn = cfg.warnPct || 60;
+  const gate = cfg.gatePct || 78;
+
+  const u = ctx.contextUsage(evt.transcript_path, cfg);
+  if (!u) return silent();
+
+  const tool = evt.tool_name || '';
+  const ti = evt.tool_input || {};
+  const band = u.pct >= gate ? 'gate' : u.pct >= warn ? 'warn' : 'ok';
+  const BLOCKABLE = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Task']);
+
+  // HARD GATE — block new build mutations; reason is fed to the model.
+  if (band === 'gate' && BLOCKABLE.has(tool) && !isEscape(tool, ti)) {
+    return out({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: gateReason(u, gate),
+      },
+    });
+  }
+
+  // NON-BLOCKING WARN — emit once each time we climb into a higher band.
+  const bandFile = path.join(projectDir, 'docs/.snapshots/.ctx-band');
+  const rank = (b) => (b === 'gate' ? 2 : b === 'warn' ? 1 : 0);
+  let prev = 'ok';
+  try { prev = (fs.readFileSync(bandFile, 'utf8').trim() || 'ok'); } catch (_) {}
+
+  if (rank(band) !== rank(prev)) {
+    try { fs.mkdirSync(path.dirname(bandFile), { recursive: true }); fs.writeFileSync(bandFile, band); } catch (_) {}
+  }
+  if (rank(band) > rank(prev) && band !== 'ok') {
+    return out({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: band === 'gate' ? gateReason(u, gate) : warnReason(u, warn, gate),
+      },
+    });
+  }
+  return silent();
+}
+
+// Checkpoint/logging writes + the synthesizer ritual are never blocked, so the
+// model always has an escape path out of the gate.
+function isEscape(tool, ti) {
+  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit' || tool === 'NotebookEdit') {
+    const fp = ti.file_path || ti.path || ti.notebook_path || '';
+    return /(^|\/)docs\//.test(fp) || /STATE\.md|ISSUES\.md|\.snapshots\//.test(fp);
+  }
+  if (tool === 'Task') return (ti.subagent_type || '').toLowerCase() === 'synthesizer';
+  return false;
+}
+
+const fmt = (n) => (n >= 1000 ? Math.round(n / 1000) + 'k' : String(n));
+
+function gateReason(u, gate) {
+  return [
+    `⛔ CONTEXT GATE — ${u.pct}% (${fmt(u.tokens)}/${fmt(u.window)} tok), เกิน ${gate}% = หยุดเปิดงาน build ใหม่.`,
+    'ทำก่อนไปต่อ:',
+    '  1) ปิด/commit งานค้างให้จบ (Bash/git ไม่ถูก block)',
+    '  2) /synthesize  (อัด handoff docs — subagent นี้ไม่ถูก block)',
+    '  3) /clear       (session ใหม่ บางลง)',
+    'build ต่อหลัง clear. กลาง irreversible op? ใช้ Bash ปิดให้จบก่อน clear.',
+    'ปลดล็อกชั่วคราว: เพิ่ม gatePct ใน .claude/flow-config.json.',
+  ].join('\n');
+}
+
+function warnReason(u, warn, gate) {
+  return [
+    `⚠️ CONTEXT ${u.pct}% (${fmt(u.tokens)}/${fmt(u.window)} tok) — แตะ warn band ${warn}%.`,
+    `วางแผนปิด phase: ทยอย /synthesize → /clear ก่อนถึง gate ${gate}% (เลยจุดนั้น hook block งาน build ใหม่).`,
+    'Delegate งาน noisy ให้ subagent เพื่อกัน context โต.',
+  ].join('\n');
+}

package/template/.claude/hooks/lib/ctx.js

@@ -0,0 +1,82 @@
+'use strict';
+// Shared context-budget math for iStartSoftFlow watchdog hooks.
+// Reads the live Claude Code transcript (JSONL) and reports how full the
+// model's context window currently is — from the REAL token usage the API
+// reported, not a heuristic. Pure Node, cross-platform.
+const fs = require('fs');
+
+// Known context windows by model-id substring. First match wins. The 1M
+// Opus/Sonnet variants advertise "[1m]" in the model id.
+const WINDOWS = [
+  [/\[1m\]|-1m\b|:1m\b|1m-/i, 1000000],
+  [/opus|sonnet|haiku|claude/i, 200000],
+];
+
+function inferWindow(model) {
+  if (!model) return 200000;
+  for (const [re, w] of WINDOWS) if (re.test(model)) return w;
+  return 200000;
+}
+
+// Read project flow config; returns the `context` block or {}.
+function loadConfig(projectDir) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(projectDir + '/.claude/flow-config.json', 'utf8'));
+    return (cfg && cfg.context) || {};
+  } catch (_) { return {}; }
+}
+
+// Read only the last `bytes` of a file (the recent assistant turns live at the
+// tail of the JSONL — no need to load a multi-MB transcript on every tool).
+function readTail(p, bytes) {
+  const fd = fs.openSync(p, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - bytes);
+    const len = size - start;
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, start);
+    return { text: buf.toString('utf8'), partial: start > 0 };
+  } finally { fs.closeSync(fd); }
+}
+
+// Scan lines (newest first) for the most recent assistant usage block.
+// input_tokens + cache_read + cache_creation == the full prompt size actually
+// sent == current context occupancy.
+function scanUsage(text, dropFirst) {
+  const lines = text.split('\n');
+  const lo = dropFirst ? 1 : 0; // first line may be a truncated tail fragment
+  for (let i = lines.length - 1; i >= lo; i--) {
+    const ln = lines[i].trim();
+    if (!ln) continue;
+    let obj;
+    try { obj = JSON.parse(ln); } catch (_) { continue; }
+    const m = obj && obj.message;
+    if (m && m.role === 'assistant' && m.usage && typeof m.usage.input_tokens === 'number') {
+      return { usage: m.usage, model: m.model || obj.model || null };
+    }
+  }
+  return null;
+}
+
+function contextUsage(transcriptPath, cfg) {
+  if (!transcriptPath) return null;
+  let hit;
+  try {
+    const tail = readTail(transcriptPath, 512 * 1024);
+    hit = scanUsage(tail.text, tail.partial);
+    if (!hit && tail.partial) {
+      // usage not in the tail window — fall back to a full read (rare).
+      hit = scanUsage(fs.readFileSync(transcriptPath, 'utf8'), false);
+    }
+  } catch (_) { return null; }
+  if (!hit) return null;
+  const u = hit.usage;
+  const tokens = (u.input_tokens || 0)
+    + (u.cache_read_input_tokens || 0)
+    + (u.cache_creation_input_tokens || 0);
+  const window = (cfg && cfg.window) ? cfg.window : inferWindow(hit.model);
+  return { tokens, window, model: hit.model, pct: Math.round((tokens / window) * 100) };
+}
+
+module.exports = { contextUsage, inferWindow, loadConfig, readTail, scanUsage };

package/template/.claude/istartsoft-flow/METHODOLOGY.md

@@ -174,6 +174,15 @@ Named procedures, each with a canonical body in `.claude/commands/<name>.md`.
   coverage gate.
 - **quick [change]** — small, obvious, non-phase change; no agent chain. Stays
   non-TDD. Runs the mock regression corpus after the change.
+- **ui-audit** — whole-product UI audit against the `ux-design` cookbook (a11y /
+  responsive / consistency); scored findings report. Periodic / pre-release. Distinct
+  from the per-phase ux-design gate (one screen) — this sweeps every screen.
+- **qa-audit** — whole-product FUNCTIONAL QA audit (coverage gaps, regression health,
+  flaky tests, critical-flow e2e, edge/error handling); scored report. The QA
+  counterpart of `ui-audit`. Distinct from the per-phase real-suite gate.
+- **security-audit** — whole-product SECURITY audit against the `security` cookbook
+  (OWASP/ASVS/WSTG/secrets/SCA/SAST/supply-chain); scored report. On-demand; a
+  precondition for the pre-deploy pentest. Distinct from the per-phase rule-11 gate.
 - **unstuck** — deep re-research after a circuit breaker (auto-run once in AUTO on
   first stuck; human-triggered in GUIDED).
 - **synthesize** — compress STATE.md, dedup ISSUES.md, prune snapshots. Run
@@ -332,6 +341,26 @@ development run that follows the spec and logs every problem so it never recurs.
 
 -----
 
+## Quality model (orthogonal axes — each audited)
+
+Quality is checked on independent axes. Passing one NEVER implies another. Each has a
+STANDARD, an inline GATE (per phase), and — for the user-facing ones — a holistic
+AUDIT (whole product, pre-release):
+
+| Axis | Question | Standard | Inline gate (per phase) | Whole-product audit |
+|------|----------|----------|-------------------------|---------------------|
+| **Functional / QA** | does it WORK? | blind TDD, RED-first (rules 5–6) | real suite green + regression corpus | full REAL corpus (final phase) · `/qa-audit` |
+| **UI / UX** | is it usable + on-brand? | `ux-design` cookbook | the ux-design check (rule 9) | `/ui-audit` |
+| **Security** | is it safe? | `security` cookbook (OWASP/ASVS/ISO) | secrets/SCA/SAST + secure coding (rule 11) | `/security-audit` · pentest + review before deploy |
+| **Code** | is it consistent? | `code-standards` (naming/architecture) | lint/format + idiom (rule 12) | — |
+
+**QA is the test discipline**, not a single agent: `test-author` (blind tests) +
+`e2e-runner` (functional E2E) + the phase gate + the regression corpus + `debugger`.
+UI audit checks *presentation*; QA checks *behaviour* — a button can pass one and
+fail the other.
+
+-----
+
 ## Shared KB (optional)
 
 If `.claude/kb-config.json` exists, the SESSION-OPEN ritual pulls the KB and loads
@@ -392,7 +421,7 @@ the same everywhere — only the *wiring* differs.
 
 | Host | Entry file | Commands | Subagents | Lifecycle hooks | Shared KB |
 |------|-----------|----------|-----------|-----------------|-----------|
-| **Claude Code** (reference) | `AGENTS.md` + `.claude/` | `.claude/commands/` | native | SessionStart · PreCompact · SubagentStop (with context injection) | yes |
+| **Claude Code** (reference) | `CLAUDE.md` (`@AGENTS.md`) + `.claude/` | `.claude/commands/` | native | SessionStart · PreToolUse (context-budget watchdog) · PreCompact · SubagentStop | yes |
 | **Codex CLI** | `AGENTS.md` (native) | `.claude/commands/` (read as prompts) | read as reference | model-run | yes |
 | **Cursor** | `.cursor/rules/` + `AGENTS.md` | `.cursor/commands/` | reads `.claude/agents/` | `.cursor/hooks.json` (sessionStart · subagentStop) | yes |
 | **Gemini CLI** | `GEMINI.md` + `AGENTS.md` | `.claude/commands/` (read as prompts) | read as reference | model-run | yes |

package/template/.claude/skills/ux-design/SKILL.md

@@ -31,6 +31,10 @@ confirmed with the user before building — design is where human taste matters.
 - Reviewing a UI diff (the "ตรวจ" pass).
 - CLOSE gate of any frontend phase — the cookbook check MUST pass.
 
+This skill is the STANDARD + the inline GATE (one screen, at phase close). For a
+WHOLE-PRODUCT sweep against this same cookbook — periodic or before a release — run
+`/ui-audit` (same rubric, broader scope, a scored report).
+
 Order: **wireframe first** (does the layout match the baseline frame?) ->
 **cookbook** (do the details obey the system?). Never invent layout the
 wireframe does not have. If the design truly needs a frame the wireframe lacks,