spectoflow 0.13.4 → 0.14.0

package/README.md

@@ -157,6 +157,11 @@ runs a skill. Improve a skill without touching the agent.
 Agents and skills follow real domain standards, cited in-file — TDD, OWASP ASVS/Top 10, C4/ADR,
 INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liners.
 
+A `governance` capability adds a **Spec Source Guardian** (skill `audit-source`): it keeps the spec
+(intent) and the code/tests (reality) coherent — flagging drift in both directions, never auto-fixing,
+surfacing findings to the Attention tab, and gating only at `done`/Major. It ships with a zero-dep
+drift helper (`lib/spec-drift.js`) and an opt-in Claude Code `Stop` hook (`hooks/spec-drift.js`).
+
 ## Language
 
 `.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable from the CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.13.4",
+  "version": "0.14.0",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",

package/templates/agents/spec-source-guardian.md

@@ -0,0 +1,58 @@
+---
+name: spec-source-guardian
+title: Spec Source Guardian
+capability: governance
+uses: [audit-source]
+description: Keeps the spec (intent) and the code/tests (reality) in sync — flags drift, never silently fixes.
+standards: [traceability matrix, EARS acceptance criteria, spec-anchored]
+---
+# Spec Source Guardian
+
+Stable team persona (the "who") for the `governance` capability. The *how* lives in the `audit-source`
+skill (see `uses`). Delegate here to keep the **source of truth coherent**: the spec is the intent of
+record, the code and tests are the enforced reality, and this role makes sure they don't drift apart.
+
+## Mandate
+Audit the alignment **spec ↔ plan ↔ code ↔ tests** in both directions, and surface divergence as
+advisory findings. It guards *coherence and traceability*, not spec authorship (that is the
+business-analyst) and not code quality (that is the code-reviewer). It **never edits** the spec or the
+code to "fix" drift — natural language is too ambiguous to auto-sync safely; it flags, and a human or
+the owning capability resolves.
+
+## Operating standards
+- **Spec-anchored, not spec-as-source.** Treat the spec as intent + decisions + acceptance criteria;
+  keep the code the source of truth and the **tests the enforcer**. Why: regenerating a system from
+  prose is lossy and unpredictable (Thoughtworks); the durable value is the spec's decisions and the
+  tests that pin them down, not the prose replacing the code.
+- **Traceability, both directions.** Flag *orphan work* (code/tasks with no spec/decision backing) and
+  *dead spec* (requirements with no implementation or test). Why: drift hides in whichever direction
+  is unwatched; a one-way check misses half of it.
+- **Acceptance criteria as the contract (EARS).** Verify the new/changed behaviour is expressed as
+  testable acceptance criteria and that a test actually encodes them. Why: a decision no test enforces
+  will silently rot; the test is what keeps intent and reality bound.
+- **Advisory by default; gate only at `done` / Major.** Findings post to the Attention tab; only a
+  Major or a `done` is gated on unresolved drift (see `policy.md`). Why: blocking every edit is noise
+  and pushes teams to bypass the guardian entirely.
+
+## Definition of done
+An audit exists that names each drift finding (direction + spec/plan/code/test involved + why), posts
+it to Attention, and records a verdict (**aligned** or **drift**). No unresolved *warn*-level drift is
+left unacknowledged when a Major or a `done` is declared.
+
+## Handoff
+Posts findings to the group chat and the Attention tab via the `::spectoflow` sentinels (exact syntax
+owned by the `audit-source` skill's Output contract). Drift returns to the owning capability
+(business-analyst to update the spec, developer/qa to add the missing test) — it is not fixed here.
+
+## Guardrails
+- Never edit a spec or code to reconcile drift — flag it; the owner decides how to resolve.
+- Never auto-generate code from the spec, or rewrite the spec from the code — no lossy auto-sync.
+- Never gate an ordinary edit; only a Major or a `done` may be gated, and only on unresolved drift.
+- Prefer a `need` / Attention item over a hard block when intent is genuinely ambiguous.
+
+## References
+- Thoughtworks — "Spec-driven development": code stays the source of truth, spec drives generation —
+  https://www.thoughtworks.com/en-us/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices
+- Sean Grove (OpenAI), "The New Code" — specifications as the durable, versioned artifact —
+  https://lawwu.github.io/transcripts/8rABwKRsec4.html
+- EARS (Easy Approach to Requirements Syntax) for testable acceptance criteria.

package/templates/capabilities.md

@@ -3,7 +3,11 @@
 A capability is a role; an agent implements it; a skill is the procedure it runs. Workflows ask for a
 capability, never a named agent — this keeps spectoflow agent-agnostic.
 
-Palette: intake · research · analysis · architecture · planning · testing · implementation · security · quality · design · operations.
+Palette: intake · research · analysis · architecture · planning · testing · implementation · security · quality · design · operations · governance.
+
+`governance` is the odd one out: it is **advisory, not a workflow step**. The `spec-source-guardian`
+(skill `audit-source`) watches that the spec (intent) and the code/tests (reality) stay coherent, and
+surfaces drift to the Attention tab; it gates only at `done`/Major (see `policy.md`), never mid-edit.
 
 | Project type | Active capabilities |
 |---|---|

package/templates/dashboard/public/app.js

@@ -328,6 +328,7 @@ function renderBoard(){
     board.append(renderPhase(ph,pl.file,filtered));
   }));
   if(!shown) board.append(noMatchState());
+  updatePhaseToggleAll();
 }
 // Kanban view — one column per status, filtered by the text search (columns already are the statuses).
 function renderKanban(board, tasks){
@@ -435,16 +436,26 @@ function backlogRow(r){
   return tr;
 }
 
-// ---- collapsed-phase state (persisted per phase title, guarded for private mode) ----
-function loadCollapsed(){
-  try{ const raw=localStorage.getItem('spf-collapsed'); const arr=raw?JSON.parse(raw):[]; return new Set(Array.isArray(arr)?arr:[]); }
+// ---- phase expand state: we track which phases are EXPANDED (default = none), so on a big
+// project the board opens compact — just phase headers with progress — and the user opens what
+// they need. Persisted per phase title (guarded for private mode). ----
+function loadExpanded(){
+  try{ const raw=localStorage.getItem('spf-expanded'); const arr=raw?JSON.parse(raw):[]; return new Set(Array.isArray(arr)?arr:[]); }
   catch{ return new Set(); }
 }
-function saveCollapsed(set){ try{ localStorage.setItem('spf-collapsed', JSON.stringify([...set])); }catch{} }
-let collapsedPhases=loadCollapsed();
+function saveExpanded(set){ try{ localStorage.setItem('spf-expanded', JSON.stringify([...set])); }catch{} }
+let expandedPhases=loadExpanded();
+function allPhaseTitles(){ const t=new Set(); (P.plans||[]).forEach(pl=> pl.phases.forEach(ph=> t.add(ph.title))); return [...t]; }
+function updatePhaseToggleAll(){
+  const btn=$('#phaseToggleAll'); if(!btn) return;
+  const titles=allPhaseTitles();
+  const allOpen = titles.length>0 && titles.every(t=> expandedPhases.has(t));
+  btn.textContent = allOpen ? 'Collapse all' : 'Expand all';
+  btn.dataset.state = allOpen ? 'open' : 'closed';
+}
 
 function renderPhase(ph,file,filteredTasks){
-  const isCollapsed=collapsedPhases.has(ph.title);
+  const isCollapsed=!expandedPhases.has(ph.title);
   const sec=el('section','phase'+(isCollapsed?' is-collapsed':''));
   const head=el('div','phase-head'); head.tabIndex=0; head.setAttribute('role','button'); head.setAttribute('aria-expanded',String(!isCollapsed));
   head.append(el('span','chevron'));
@@ -458,8 +469,8 @@ function renderPhase(ph,file,filteredTasks){
   const toggle=()=>{
     const now=sec.classList.toggle('is-collapsed');
     head.setAttribute('aria-expanded',String(!now));
-    if(now) collapsedPhases.add(ph.title); else collapsedPhases.delete(ph.title);
-    saveCollapsed(collapsedPhases);
+    if(now) expandedPhases.delete(ph.title); else expandedPhases.add(ph.title);
+    saveExpanded(expandedPhases); updatePhaseToggleAll();
   };
   head.addEventListener('click',toggle);
   head.addEventListener('keydown',e=>{ if(e.key==='Enter'||e.key===' '){ e.preventDefault(); toggle(); } });
@@ -953,6 +964,14 @@ $$('#statusChips .fchip').forEach(b=> b.addEventListener('click', ()=>{ filter.s
 $('#search').addEventListener('input', e=>{ filter.q=e.target.value; renderBoard(); });
 // board view switch — List (phase-grouped) vs Kanban (columns by status), persisted per viewer
 $$('#boardViewToggle .vt-btn').forEach(b=> b.addEventListener('click', ()=>{ boardView=b.dataset.view; try{ localStorage.setItem('spf-board-view',boardView); }catch{} renderBoard(); }));
+// expand / collapse all phases (List view) — keeps a big board compact by default
+const phaseToggleAllBtn=$('#phaseToggleAll');
+if(phaseToggleAllBtn) phaseToggleAllBtn.addEventListener('click', ()=>{
+  const titles=allPhaseTitles();
+  const allOpen = titles.length>0 && titles.every(t=> expandedPhases.has(t));
+  if(allOpen) expandedPhases.clear(); else titles.forEach(t=> expandedPhases.add(t));
+  saveExpanded(expandedPhases); renderBoard();
+});
 // backlog: independent filters + sortable column headers — client-side only (reset to page 1 on change)
 $$('#backlogStatusChips .fchip').forEach(b=> b.addEventListener('click', ()=>{ backlogFilter.status=b.dataset.status; backlogPage=1; renderBacklog(); }));
 $('#backlogSearch').addEventListener('input', e=>{ backlogFilter.q=e.target.value; backlogPage=1; renderBacklog(); });

package/templates/dashboard/public/index.html

@@ -65,6 +65,7 @@
             <button class="vt-btn active" data-view="list" title="Grouped by phase"><span class="tab-ico" data-icon="backlog"></span><span>List</span></button>
             <button class="vt-btn" data-view="kanban" title="Columns by status"><span class="tab-ico" data-icon="board"></span><span>Kanban</span></button>
           </div>
+          <button class="mini-btn" id="phaseToggleAll" title="Expand or collapse all phases">Expand all</button>
           <input type="search" id="search" class="search" placeholder="Filter tasks…" autocomplete="off" />
         </div>
         <div class="board" id="board"></div>

package/templates/dashboard/public/styles.css

@@ -815,3 +815,9 @@ body.booting .wf-step2 { opacity:0; animation:rise .4s cubic-bezier(.2,.8,.2,1)
 .kanban-col-body { display:flex; flex-direction:column; gap:8px; padding:10px; }
 .kanban-empty { color:var(--faint); font-size:12px; text-align:center; padding:10px 0; }
 .kanban .task { width:auto; }
+
+/* ---- board compactness: expand/collapse-all button + kanban column scroll (v0.13.5) ---- */
+.mini-btn { font:inherit; font-size:11.5px; padding:5px 12px; border:1px solid var(--line); border-radius:999px; background:var(--surface); color:var(--muted); cursor:pointer; flex-shrink:0; }
+.mini-btn:hover { color:var(--ink); border-color:var(--cool); }
+.main:has(.board.is-kanban) #phaseToggleAll { display:none; }   /* phases are a List concept */
+.kanban-col-body { max-height:64vh; overflow-y:auto; }          /* keep columns compact on a big project */

package/templates/hooks/spec-drift.js

@@ -0,0 +1,58 @@
+'use strict';
+/*
+ * Claude Code "Stop" hook (OPT-IN) — the spec-source-guardian's watchdog.
+ *
+ * At the end of an agent turn it runs the deterministic spec-drift check on the git working tree and
+ * appends any source-of-truth signals to the dashboard's Attention tab. Advisory only: it NEVER edits
+ * code or specs and NEVER fails the agent (always exits 0).
+ *
+ * Enable it by adding this to your project's .claude/settings.json (spectoflow does NOT wire it
+ * automatically, to avoid clobbering your settings):
+ *
+ *   {
+ *     "hooks": {
+ *       "Stop": [
+ *         { "hooks": [ { "type": "command", "command": "node .spectoflow/hooks/spec-drift.js" } ] }
+ *       ]
+ *     }
+ *   }
+ *
+ * Deduped against still-open Attention items, so it never spams.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { classifyChange, coverageSignals } = require('../lib/spec-drift');
+
+let input = '';
+process.stdin.on('data', (c) => { input += c; });
+process.stdin.on('end', () => { try { run(); } catch { /* never fail the agent */ } process.exit(0); });
+
+function run() {
+  const root = process.cwd();
+  let changed = [];
+  try {
+    changed = execFileSync('git', ['status', '--porcelain', '-uall'], { cwd: root, encoding: 'utf8' })
+      .split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+  } catch {}
+  const ls = (d) => { try { return fs.readdirSync(path.join(root, d)).filter((f) => f.endsWith('.md')); } catch { return []; } };
+  const signals = [...classifyChange(changed), ...coverageSignals({ specs: ls('specs'), plans: ls('plans') })];
+  if (!signals.length) return;
+
+  const rp = path.join(root, '.spectoflow', 'runtime.json');
+  let rt = {};
+  try { rt = JSON.parse(fs.readFileSync(rp, 'utf8')); } catch {}
+  rt.attention = rt.attention || [];
+  const open = new Set(rt.attention.filter((a) => a.status !== 'resolved').map((a) => a.text));
+  let added = false;
+  for (const s of signals) {
+    const text = 'Source-of-truth: ' + s.msg;
+    if (open.has(text)) continue;
+    rt.attention.unshift({
+      id: 'att' + Date.now().toString(36) + Math.floor(Math.random() * 1e3).toString(36),
+      at: new Date().toISOString(), by: 'spec-source-guardian', source: 'agent', status: 'open', text,
+    });
+    added = true;
+  }
+  if (added) { try { fs.writeFileSync(rp, JSON.stringify(rt, null, 2) + '\n'); } catch {} }
+}

package/templates/lib/spec-drift.js

@@ -0,0 +1,68 @@
+'use strict';
+/*
+ * spec-drift — a small, ZERO-DEPENDENCY helper for the spec-source-guardian.
+ *
+ * It computes deterministic, ADVISORY signals about source-of-truth drift between the spec (intent)
+ * and the code/tests (reality). It never edits anything and never blocks — natural-language specs
+ * can't be auto-synced safely, so this only *flags* divergence for a human (or the guardian agent)
+ * to judge. That is the honest, spec-anchored stance: the spec stays the intent of record, the code
+ * and tests stay the enforced reality, and a guardian keeps them from silently drifting apart.
+ *
+ * Pure, unit-tested functions: classifyChange(paths), coverageSignals({specs, plans}).
+ * CLI: `node spec-drift.js` — inspects the git working tree + specs/plans and prints signals, and
+ * emits `::spectoflow attention msg=…` lines that the dashboard turns into Attention items.
+ */
+
+const CODE_EXT = /\.(js|jsx|ts|tsx|py|go|rs|java|rb|php|c|cc|cpp|h|hpp|cs|kt|swift|scala|sql|sh)$/i;
+const isSpec = (p) => /(^|\/)specs?\//.test(p);
+const isPlan = (p) => /(^|\/)plans?\//.test(p);
+const isFramework = (p) => /(^|\/)\.spectoflow\//.test(p);
+const isTest = (p) => (/(^|[._-])(test|spec|e2e)s?([._-]|\/|$)/i.test(p) || /(^|\/)(tests?|__tests__)\//i.test(p)) && !isSpec(p) && !isPlan(p);
+const isCode = (p) => CODE_EXT.test(p) && !isFramework(p) && !isTest(p);
+
+// Advisory drift signals for the set of paths changed in one unit of work → [{level, msg}].
+function classifyChange(paths) {
+  const list = (paths || []).map(String);
+  const has = (fn) => list.some(fn);
+  const codeOrTest = has((p) => (isCode(p) || isTest(p)) && !isSpec(p) && !isPlan(p) && !isFramework(p));
+  const specOrPlan = has((p) => isSpec(p) || isPlan(p));
+  const out = [];
+  if (codeOrTest && !specOrPlan)
+    out.push({ level: 'warn', msg: 'code/tests changed but no specs/ or plans/ file was updated — confirm the spec still matches, or update it.' });
+  if (has(isSpec) && !has(isCode) && !has(isTest))
+    out.push({ level: 'info', msg: 'a spec changed but no code/tests followed — make sure a plan task and tests carry the new intent.' });
+  return out;
+}
+
+// Coverage signals from the presence of spec/plan markdown files (not their content) → [{level, msg}].
+function coverageSignals({ specs, plans } = {}) {
+  const s = (specs || []).length, p = (plans || []).length;
+  const out = [];
+  if (p > 0 && s === 0)
+    out.push({ level: 'warn', msg: 'plans/ has work but specs/ is empty — the plan has no spec to trace back to (source of truth missing).' });
+  if (s > 0 && p === 0)
+    out.push({ level: 'info', msg: 'specs/ exists but plans/ is empty — the spec is not yet broken into traceable, testable tasks.' });
+  return out;
+}
+
+module.exports = { classifyChange, coverageSignals, isCode, isTest, isSpec, isPlan };
+
+// ---- CLI ------------------------------------------------------------------
+if (require.main === module) {
+  const fs = require('fs'), path = require('path'), { execFileSync } = require('child_process');
+  const root = process.cwd();
+  let changed = [];
+  try {
+    changed = execFileSync('git', ['status', '--porcelain', '-uall'], { cwd: root, encoding: 'utf8' })
+      .split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+  } catch {}
+  const ls = (d) => { try { return fs.readdirSync(path.join(root, d)).filter((f) => f.endsWith('.md')); } catch { return []; } };
+  const signals = [...classifyChange(changed), ...coverageSignals({ specs: ls('specs'), plans: ls('plans') })];
+  if (!signals.length) { console.log('spec-drift: no source-of-truth signals — spec and reality look aligned.'); process.exit(0); }
+  console.log('spec-drift — advisory source-of-truth signals (judge, do not auto-apply):');
+  for (const s of signals) {
+    console.log(`  [${s.level}] ${s.msg}`);
+    console.log(`::spectoflow attention msg=Source-of-truth: ${s.msg}`);
+  }
+  process.exit(0);
+}

package/templates/policy.md

@@ -6,6 +6,10 @@ Orthogonal to mode. Even in autopilot, these require **explicit human approval**
 - **Destructive migration** (irreversible drop/alter, data deletion, purge).
 - **Security change** (auth, permissions, secrets, network exposure, session lifetime).
 - **Committing spend / external side effect** (payment, purchase, mass send).
+- **Source-of-truth drift at `done` / Major** (governance) — before a Major, or before a task flips to
+  `done`, the `spec-source-guardian`'s drift check must be clean (or the drift explicitly accepted):
+  the change is reflected in the spec **and** covered by a test. This gate *acknowledges*, it does not
+  auto-fix — unresolved drift blocks the "done" until resolved or accepted.
 
 When a step hits a gate: stop, explain the act and its risk in one line, ask [Approve / Cancel /
 Modify], and record the decision in the runtime log. Overridable per project (add or relax gates).

package/templates/skills/audit-source/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: audit-source
+description: Audit spec ↔ code ↔ tests alignment; surface drift as advisory findings, never auto-fix.
+capability: governance
+inputs: The specs/, plans/, code and tests; optionally the recent change set (git diff).
+outputs: A drift report + Attention items; a verdict (aligned / drift).
+standard: spec-anchored traceability
+---
+# Audit source-of-truth
+
+Scoped audit that keeps the **spec (intent)** and the **code/tests (reality)** coherent by flagging
+drift in both directions. Advisory — it reports, it never edits or auto-syncs.
+
+## When to use
+- Before a Major or a `done` (the governance gate in `policy.md`).
+- After a batch of changes, to catch drift early (a `Stop` hook can trigger it — see `hooks/`).
+- On demand: "is the spec still the source of truth for what's built?"
+
+## Method
+1. **Build the trace.** For each spec section/decision, find the plan task(s), the code, and the
+   test(s) that carry it; for each plan task and code change, find the spec section it serves.
+2. **Flag both directions.**
+   - *Orphan work* — code or a task with no spec/decision backing → the decision is undocumented.
+   - *Dead spec* — a requirement with no implementation or no test → intent that will rot.
+3. **Check the enforcer.** Confirm the new/changed behaviour has **acceptance criteria** (EARS /
+   Given-When-Then) and that a **test actually encodes them** — tests are what bind intent to reality.
+4. **Run the deterministic helper** (optional, zero-dep): `node .spectoflow/lib/spec-drift.js` — it
+   inspects the git working tree + specs/plans and prints coupling/coverage signals (e.g. "code
+   changed but no specs/ or plans/ updated"). Treat its output as signals to judge, not verdicts.
+5. **Judge, don't auto-apply.** Where intent is ambiguous, raise a `need` rather than guess. Never
+   regenerate code from the spec or rewrite the spec from the code.
+
+## Output contract
+Write findings as a report / task comment (granular, one line at a time), each carrying: the drift
+direction, the spec/plan/code/test involved, and why it matters. End with a verdict: **aligned** or
+**drift**. Surface to the orchestrator, group chat, and the **Attention tab** with:
+
+```
+::spectoflow role=governance kind=review msg=<verdict + counts>
+::spectoflow attention msg=Source-of-truth: <one drift finding, actionable>
+```
+
+The `attention` line becomes an item in the dashboard's Attention tab (the user can edit, resolve, or
+**validate → task**). Do not edit the spec or the code to reconcile drift — that is the owner's call.
+
+## Quality bar
+- [ ] Trace built **both directions** (orphan work *and* dead spec), not just one.
+- [ ] Each new/changed behaviour has testable acceptance criteria **and** a test that encodes them.
+- [ ] Findings are actionable (name the spec section / task / file, and the resolution owner).
+- [ ] Nothing was auto-fixed, regenerated, or silently reconciled.
+- [ ] A clear verdict (aligned / drift) is stated; unresolved *warn* drift is surfaced to Attention.
+
+## References
+- Thoughtworks — spec-driven development (code as source of truth, tests as enforcer) —
+  https://www.thoughtworks.com/en-us/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices
+- Augment Code — spec-anchored vs spec-as-source, drift & traceability —
+  https://www.augmentcode.com/guides/spec-as-source-of-truth-rebuildable-codebase