@sun-asterisk/sungen 3.2.2-beta.5 → 3.2.2-beta.7

package/dist/cli/commands/journey.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerJourneyCommand(program: Command): void;
+//# sourceMappingURL=journey.d.ts.map

package/dist/cli/commands/journey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/journey.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsC7D"}

package/dist/cli/commands/journey.js

@@ -0,0 +1,92 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerJourneyCommand = registerJourneyCommand;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const journey_1 = require("../../harness/journey");
+const unit_paths_1 = require("../../harness/unit-paths");
+function findScreenDir(name) {
+    const candidates = [
+        path.join(process.cwd(), 'qa', 'screens', name),
+        path.join(process.cwd(), 'qa', 'flows', name),
+        path.join(process.cwd(), 'qa', 'api', name),
+    ];
+    for (const c of candidates)
+        if (fs.existsSync(c))
+            return c;
+    return null;
+}
+function registerJourneyCommand(program) {
+    program
+        .command('journey')
+        .description('Durable "you are here" board (#381): obligations + what-to-review + next, synthesised read-only from the audit report + ledger already on disk.')
+        .option('-s, --screen <name>', 'Screen / flow / api unit name')
+        .option('--waive <obligation>', 'Waive an obligation (e.g. OB-coverage) — requires --reason')
+        .option('--reason <text>', 'The reason a waived obligation is acceptable (mandatory with --waive)')
+        .option('--json', 'Output the raw JSON report')
+        .action((options) => {
+        try {
+            const name = options.screen;
+            if (!name)
+                throw new Error('Provide --screen <name>');
+            if (!findScreenDir(name))
+                throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+            const report = options.waive
+                ? (0, journey_1.waive)(process.cwd(), name, options.waive, options.reason || '')
+                : (0, journey_1.runJourney)(process.cwd(), name);
+            const outDir = path.join(process.cwd(), '.sungen', 'journey');
+            fs.mkdirSync(outDir, { recursive: true });
+            const slug = (0, unit_paths_1.reportSlug)(name);
+            fs.writeFileSync(path.join(outDir, `${slug}.json`), JSON.stringify(report, null, 2), 'utf-8');
+            const board = (0, journey_1.renderJourneyBoard)(report);
+            fs.writeFileSync(path.join(outDir, `${slug}.board.md`), board, 'utf-8');
+            if (options.json) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else {
+                console.log('');
+                console.log(board);
+                console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, `${slug}.board.md`))}`);
+                console.log('');
+            }
+        }
+        catch (error) {
+            console.error('Error:', error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=journey.js.map

package/dist/cli/commands/journey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey.js","sourceRoot":"","sources":["../../../src/cli/commands/journey.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -17,6 +17,7 @@ const add_flow_1 = require("./commands/add-flow");
 const dashboard_1 = require("./commands/dashboard");
 const audit_1 = require("./commands/audit");
 const depth_lint_1 = require("./commands/depth-lint");
+const journey_1 = require("./commands/journey");
 const ingest_1 = require("./commands/ingest");
 const eval_1 = require("./commands/eval");
 const manifest_1 = require("./commands/manifest");
@@ -55,6 +56,7 @@ async function main() {
     (0, dashboard_1.registerDashboardCommand)(program);
     (0, audit_1.registerAuditCommand)(program);
     (0, depth_lint_1.registerDepthLintCommand)(program);
+    (0, journey_1.registerJourneyCommand)(program);
     (0, manifest_1.registerManifestCommand)(program);
     (0, ledger_1.registerLedgerCommand)(program);
     (0, feedback_1.registerFeedbackCommand)(program);

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/harness/journey.d.ts

@@ -0,0 +1,34 @@
+export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived';
+export interface Obligation {
+    id: string;
+    title: string;
+    status: ObStatus;
+    detail: string;
+    waivedReason?: string;
+}
+export interface JourneyReport {
+    unit: string;
+    generatedFrom: string[];
+    youAreHere: string;
+    phasesDone: string[];
+    gateStatus: string | null;
+    score: number | null;
+    obligations: Obligation[];
+    needsYou: string[];
+    nextSuggested: string;
+}
+/**
+ * The public entry: compute fresh, then RECONCILE with the persisted state —
+ *  - auto-close is automatic (fresh recompute reflects the current artifacts);
+ *  - an active waiver (evidence unchanged) sets status='waived' (carries the reason);
+ *  - a STALE waiver (audit changed since it was waived) is re-surfaced for re-decision (anti-amnesia).
+ * Then persist the current evidence cursor.
+ */
+export declare function runJourney(projectRoot: string, unit: string): JourneyReport;
+/**
+ * Waive an obligation — REQUIRES a reason (anti-amnesia: a waiver leaves a recorded "why").
+ * Records the current evidence cursor so reconcile can invalidate it if the audit changes.
+ */
+export declare function waive(projectRoot: string, unit: string, obId: string, reason: string): JourneyReport;
+export declare function renderJourneyBoard(r: JourneyReport): string;
+//# sourceMappingURL=journey.d.ts.map

package/dist/harness/journey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey.d.ts","sourceRoot":"","sources":["../../src/harness/journey.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AA0HD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAqB3E;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAepG;AAID,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAkB3D"}

package/dist/harness/journey.js

@@ -0,0 +1,251 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runJourney = runJourney;
+exports.waive = waive;
+exports.renderJourneyBoard = renderJourneyBoard;
+/**
+ * Journey board (epic #381, story S1) — the durable, read-only "you are here" view.
+ *
+ * Reconstructs the QA's position from artifacts ALREADY on disk (no recomputation, no context
+ * needed): the audit report (`.sungen/reports/<slug>-audit.json`) supplies the obligation status
+ * via its calibration axes + gate + findings; the ledger (`.sungen/ledger/<slug>.jsonl`) supplies
+ * the phase history ("you are here"). The output answers the three QA questions — what's next /
+ * what to review / what's doubtful — and persists `.sungen/journey/<slug>.{json,board.md}`.
+ *
+ * S1 = the read-only synthesis. S2 (this file) adds the **writable lifecycle**: persisted
+ * waivers (reason-required, anti-amnesia), reconcile (auto-close satisfied; re-surface a waiver
+ * when its evidence changed), via `runJourney` + `waive`. Gate-bound predicates + inter-phase
+ * gates are S3. Pure-deterministic, no AI.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const unit_paths_1 = require("./unit-paths");
+function readJSON(p) {
+    try {
+        return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf-8')) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLedgerPhases(p) {
+    if (!fs.existsSync(p))
+        return [];
+    const out = [];
+    for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const d = JSON.parse(line);
+            if (d.step)
+                out.push(String(d.step));
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
+/** Findings that ask for HUMAN judgment (the review-queue seed), vs pure machine-repair targets. */
+function isHumanFinding(f) {
+    return /@manual|MANUAL-|DEPTH-DEFERRED|UNSOURCEABLE|CAPABILITY-SUGGESTION|judgment|oracle|review/i.test(f);
+}
+const SAT = 0.8; // axis at/above this = satisfied (below = needs-work)
+function computeFresh(projectRoot, unit) {
+    const slug = (0, unit_paths_1.reportSlug)(unit);
+    const audit = readJSON(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+    const phases = readLedgerPhases(path.join(projectRoot, '.sungen', 'ledger', `${slug}.jsonl`));
+    const from = [];
+    if (audit)
+        from.push('audit');
+    if (phases.length)
+        from.push('ledger');
+    const youAreHere = phases.length ? phases[phases.length - 1] : 'not started';
+    const ran = (p) => phases.some((s) => s === p || s.startsWith(p));
+    const obligations = [];
+    const needsYou = [];
+    if (!audit) {
+        // Nothing measured yet — the journey hasn't really begun.
+        obligations.push({ id: 'OB-create', title: 'Generate test cases', status: 'pending', detail: 'No audit report yet — run /sungen:create-test.' });
+        return {
+            unit, generatedFrom: from, youAreHere, phasesDone: phases, gateStatus: null, score: null,
+            obligations, needsYou, nextSuggested: 'Run `/sungen:create-test ' + unit + '` to begin.',
+        };
+    }
+    const ax = (audit.calibration && audit.calibration.axes) || {};
+    const depthThreshold = (audit.depth && audit.depth.threshold) || SAT;
+    const ob = (id, title, val, thr, detail) => ({
+        id, title,
+        status: val === undefined ? 'pending' : val >= thr ? 'satisfied' : 'needs-work',
+        detail: val === undefined ? detail : `${Math.round(val * 100)}% (need ${Math.round(thr * 100)}%) — ${detail}`,
+    });
+    obligations.push(ob('OB-spec', 'Spec readiness', ax.specFR, 1, 'FR/sections sufficient to design from'));
+    obligations.push(ob('OB-coverage', 'Viewpoint coverage', ax.coverage, SAT, 'critical themes covered'));
+    obligations.push(ob('OB-depth', 'Assertion depth', ax.businessDepth, depthThreshold, 'business-critical scenarios assert data'));
+    obligations.push(ob('OB-trace', 'Traceability', ax.taxonomy ?? ax.traceability, SAT, 'scenarios trace to viewpoints'));
+    // Automation obligation: automatable @manual still pending a driver = needs-work.
+    const autoPending = audit.automatableManual && audit.automatableManual.automatable > 0;
+    obligations.push({
+        id: 'OB-automation', title: 'Automation coverage',
+        status: autoPending ? 'needs-work' : 'satisfied',
+        detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
+    });
+    // Human sign-off: always pending until S5 explicit signoff; carries the review-queue count.
+    const manualCount = (audit.manualOracle && audit.manualOracle.total) || 0;
+    obligations.push({
+        id: 'OB-signoff', title: 'Human sign-off', status: 'pending',
+        detail: `${needsYou.length} item(s) queued for your review (single sign-off at the end)`,
+    });
+    // Needs-you: human-judgment findings (the review-queue seed), with their anchors (titles) intact.
+    for (const f of (audit.findings || []))
+        if (isHumanFinding(f))
+            needsYou.push(f);
+    // Re-stamp the signoff detail now that needsYou is filled.
+    const signoff = obligations.find((o) => o.id === 'OB-signoff');
+    if (signoff)
+        signoff.detail = `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`;
+    // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
+    const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
+    let nextSuggested;
+    if (firstGap)
+        nextSuggested = `Repair "${firstGap.title}" (${firstGap.detail}).`;
+    else if (!ran('run'))
+        nextSuggested = `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
+    else
+        nextSuggested = `All obligations satisfied — review the ${needsYou.length} queued item(s), then sign off & deliver.`;
+    return {
+        unit, generatedFrom: from, youAreHere, phasesDone: phases,
+        gateStatus: audit.gateStatus ?? null, score: (audit.score && audit.score.overall) ?? null,
+        obligations, needsYou, nextSuggested,
+    };
+}
+function statePath(projectRoot, slug) {
+    return path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
+}
+/** Evidence cursor: the audit report's content hash. A waiver is invalidated when this changes. */
+function auditHashOf(projectRoot, slug) {
+    const p = path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`);
+    return fs.existsSync(p) ? crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex') : '';
+}
+function loadState(p) { return readJSON(p); }
+function saveState(p, s) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(s, null, 2), 'utf-8');
+}
+/** Recompute nextSuggested AFTER waivers are applied (a waived obligation is not a gap). */
+function computeNext(r, unit) {
+    const gap = r.obligations.find((o) => o.status !== 'satisfied' && o.status !== 'waived' && o.id !== 'OB-signoff');
+    if (gap)
+        return `Repair "${gap.title}" (${gap.detail}).`;
+    if (!r.phasesDone.some((s) => s === 'run' || s.startsWith('run')))
+        return `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
+    return `All obligations satisfied/waived — review the ${r.needsYou.length} queued item(s), then sign off & deliver.`;
+}
+/**
+ * The public entry: compute fresh, then RECONCILE with the persisted state —
+ *  - auto-close is automatic (fresh recompute reflects the current artifacts);
+ *  - an active waiver (evidence unchanged) sets status='waived' (carries the reason);
+ *  - a STALE waiver (audit changed since it was waived) is re-surfaced for re-decision (anti-amnesia).
+ * Then persist the current evidence cursor.
+ */
+function runJourney(projectRoot, unit) {
+    const slug = (0, unit_paths_1.reportSlug)(unit);
+    const report = computeFresh(projectRoot, unit);
+    const sp = statePath(projectRoot, slug);
+    const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+    const curHash = auditHashOf(projectRoot, slug);
+    for (const ob of report.obligations) {
+        const w = state.waivers[ob.id];
+        if (!w)
+            continue;
+        if (w.auditHashAtWaive === curHash) {
+            ob.status = 'waived';
+            ob.waivedReason = w.reason;
+            ob.detail = `waived — ${w.reason}`;
+        }
+        else {
+            report.needsYou.unshift(`⚠️ Waiver on "${ob.title}" is STALE (evidence changed since ${w.at}) — re-decide. Was: ${w.reason}`);
+        }
+    }
+    report.nextSuggested = computeNext(report, unit);
+    saveState(sp, { unit, auditHash: curHash, waivers: state.waivers });
+    return report;
+}
+/**
+ * Waive an obligation — REQUIRES a reason (anti-amnesia: a waiver leaves a recorded "why").
+ * Records the current evidence cursor so reconcile can invalidate it if the audit changes.
+ */
+function waive(projectRoot, unit, obId, reason) {
+    if (!reason || !reason.trim()) {
+        throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
+    }
+    const slug = (0, unit_paths_1.reportSlug)(unit);
+    const fresh = computeFresh(projectRoot, unit);
+    const valid = fresh.obligations.map((o) => o.id);
+    if (!valid.includes(obId)) {
+        throw new Error(`Unknown obligation "${obId}". Valid: ${valid.join(', ')}`);
+    }
+    const sp = statePath(projectRoot, slug);
+    const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+    state.waivers[obId] = { reason: reason.trim(), at: new Date().toISOString(), auditHashAtWaive: auditHashOf(projectRoot, slug) };
+    saveState(sp, state);
+    return runJourney(projectRoot, unit);
+}
+const ICON = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫' };
+function renderJourneyBoard(r) {
+    const L = [];
+    L.push(`# Journey — ${r.unit}`);
+    L.push('');
+    L.push(`📍 **You are here:** ${r.youAreHere}` + (r.phasesDone.length ? `  (phases: ${r.phasesDone.join(' → ')})` : ''));
+    if (r.gateStatus)
+        L.push(`   gate: **${r.gateStatus}** · score: ${r.score ?? '—'}/10`);
+    L.push('');
+    L.push('## What must still be true');
+    for (const o of r.obligations)
+        L.push(`- ${ICON[o.status]} **${o.title}** — ${o.detail}`);
+    L.push('');
+    L.push(`## 🔎 Needs your judgment (${r.needsYou.length})`);
+    if (r.needsYou.length)
+        for (const f of r.needsYou.slice(0, 20))
+            L.push(`- ${f}`);
+    else
+        L.push('- (nothing queued)');
+    L.push('');
+    L.push(`## → Next`);
+    L.push(`${r.nextSuggested}`);
+    L.push('');
+    return L.join('\n');
+}
+//# sourceMappingURL=journey.js.map

package/dist/harness/journey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey.js","sourceRoot":"","sources":["../../src/harness/journey.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.2-beta.5",
+  "version": "3.2.2-beta.7",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts && tsx tests/journey/run.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@sungen/driver-ui": "3.2.2-beta.5",
+    "@sungen/driver-ui": "3.2.2-beta.7",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",

package/src/cli/commands/journey.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runJourney, waive, renderJourneyBoard } from '../../harness/journey';
+import { reportSlug } from '../../harness/unit-paths';
+
+function findScreenDir(name: string): string | null {
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  return null;
+}
+
+export function registerJourneyCommand(program: Command): void {
+  program
+    .command('journey')
+    .description('Durable "you are here" board (#381): obligations + what-to-review + next, synthesised read-only from the audit report + ledger already on disk.')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--waive <obligation>', 'Waive an obligation (e.g. OB-coverage) — requires --reason')
+    .option('--reason <text>', 'The reason a waived obligation is acceptable (mandatory with --waive)')
+    .option('--json', 'Output the raw JSON report')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const report = options.waive
+          ? waive(process.cwd(), name, options.waive, options.reason || '')
+          : runJourney(process.cwd(), name);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'journey');
+        fs.mkdirSync(outDir, { recursive: true });
+        const slug = reportSlug(name);
+        fs.writeFileSync(path.join(outDir, `${slug}.json`), JSON.stringify(report, null, 2), 'utf-8');
+        const board = renderJourneyBoard(report);
+        fs.writeFileSync(path.join(outDir, `${slug}.board.md`), board, 'utf-8');
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          console.log('');
+          console.log(board);
+          console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, `${slug}.board.md`))}`);
+          console.log('');
+        }
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/index.ts

@@ -16,6 +16,7 @@ import { registerAddFlowCommand } from './commands/add-flow';
 import { registerDashboardCommand } from './commands/dashboard';
 import { registerAuditCommand } from './commands/audit';
 import { registerDepthLintCommand } from './commands/depth-lint';
+import { registerJourneyCommand } from './commands/journey';
 import { registerIngestCommand } from './commands/ingest';
 import { registerEvalCommand } from './commands/eval';
 import { registerManifestCommand } from './commands/manifest';
@@ -59,6 +60,7 @@ async function main() {
   registerDashboardCommand(program);
   registerAuditCommand(program);
   registerDepthLintCommand(program);
+  registerJourneyCommand(program);
   registerManifestCommand(program);
   registerLedgerCommand(program);
   registerFeedbackCommand(program);

package/src/harness/journey.ts

@@ -0,0 +1,233 @@
+/**
+ * Journey board (epic #381, story S1) — the durable, read-only "you are here" view.
+ *
+ * Reconstructs the QA's position from artifacts ALREADY on disk (no recomputation, no context
+ * needed): the audit report (`.sungen/reports/<slug>-audit.json`) supplies the obligation status
+ * via its calibration axes + gate + findings; the ledger (`.sungen/ledger/<slug>.jsonl`) supplies
+ * the phase history ("you are here"). The output answers the three QA questions — what's next /
+ * what to review / what's doubtful — and persists `.sungen/journey/<slug>.{json,board.md}`.
+ *
+ * S1 = the read-only synthesis. S2 (this file) adds the **writable lifecycle**: persisted
+ * waivers (reason-required, anti-amnesia), reconcile (auto-close satisfied; re-surface a waiver
+ * when its evidence changed), via `runJourney` + `waive`. Gate-bound predicates + inter-phase
+ * gates are S3. Pure-deterministic, no AI.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { reportSlug } from './unit-paths';
+
+export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived';
+
+export interface Obligation {
+  id: string;
+  title: string;
+  status: ObStatus;
+  detail: string;
+  waivedReason?: string;   // S2 — set when the QA explicitly waived this obligation
+}
+
+export interface JourneyReport {
+  unit: string;
+  generatedFrom: string[];          // which artifacts were available
+  youAreHere: string;               // last ledger phase, or 'not started'
+  phasesDone: string[];
+  gateStatus: string | null;
+  score: number | null;
+  obligations: Obligation[];
+  needsYou: string[];               // located findings / human-judgment items (the review queue seed)
+  nextSuggested: string;
+}
+
+function readJSON(p: string): any {
+  try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf-8')) : null; } catch { return null; }
+}
+
+function readLedgerPhases(p: string): string[] {
+  if (!fs.existsSync(p)) return [];
+  const out: string[] = [];
+  for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+    if (!line.trim()) continue;
+    try { const d = JSON.parse(line); if (d.step) out.push(String(d.step)); } catch { /* skip */ }
+  }
+  return out;
+}
+
+/** Findings that ask for HUMAN judgment (the review-queue seed), vs pure machine-repair targets. */
+function isHumanFinding(f: string): boolean {
+  return /@manual|MANUAL-|DEPTH-DEFERRED|UNSOURCEABLE|CAPABILITY-SUGGESTION|judgment|oracle|review/i.test(f);
+}
+
+const SAT = 0.8; // axis at/above this = satisfied (below = needs-work)
+
+function computeFresh(projectRoot: string, unit: string): JourneyReport {
+  const slug = reportSlug(unit);
+  const audit = readJSON(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+  const phases = readLedgerPhases(path.join(projectRoot, '.sungen', 'ledger', `${slug}.jsonl`));
+
+  const from: string[] = [];
+  if (audit) from.push('audit');
+  if (phases.length) from.push('ledger');
+
+  const youAreHere = phases.length ? phases[phases.length - 1] : 'not started';
+  const ran = (p: string) => phases.some((s) => s === p || s.startsWith(p));
+
+  const obligations: Obligation[] = [];
+  const needsYou: string[] = [];
+
+  if (!audit) {
+    // Nothing measured yet — the journey hasn't really begun.
+    obligations.push({ id: 'OB-create', title: 'Generate test cases', status: 'pending', detail: 'No audit report yet — run /sungen:create-test.' });
+    return {
+      unit, generatedFrom: from, youAreHere, phasesDone: phases, gateStatus: null, score: null,
+      obligations, needsYou, nextSuggested: 'Run `/sungen:create-test ' + unit + '` to begin.',
+    };
+  }
+
+  const ax = (audit.calibration && audit.calibration.axes) || {};
+  const depthThreshold = (audit.depth && audit.depth.threshold) || SAT;
+  const ob = (id: string, title: string, val: number | undefined, thr: number, detail: string): Obligation => ({
+    id, title,
+    status: val === undefined ? 'pending' : val >= thr ? 'satisfied' : 'needs-work',
+    detail: val === undefined ? detail : `${Math.round(val * 100)}% (need ${Math.round(thr * 100)}%) — ${detail}`,
+  });
+
+  obligations.push(ob('OB-spec', 'Spec readiness', ax.specFR, 1, 'FR/sections sufficient to design from'));
+  obligations.push(ob('OB-coverage', 'Viewpoint coverage', ax.coverage, SAT, 'critical themes covered'));
+  obligations.push(ob('OB-depth', 'Assertion depth', ax.businessDepth, depthThreshold, 'business-critical scenarios assert data'));
+  obligations.push(ob('OB-trace', 'Traceability', ax.taxonomy ?? ax.traceability, SAT, 'scenarios trace to viewpoints'));
+
+  // Automation obligation: automatable @manual still pending a driver = needs-work.
+  const autoPending = audit.automatableManual && audit.automatableManual.automatable > 0;
+  obligations.push({
+    id: 'OB-automation', title: 'Automation coverage',
+    status: autoPending ? 'needs-work' : 'satisfied',
+    detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
+  });
+
+  // Human sign-off: always pending until S5 explicit signoff; carries the review-queue count.
+  const manualCount = (audit.manualOracle && audit.manualOracle.total) || 0;
+  obligations.push({
+    id: 'OB-signoff', title: 'Human sign-off', status: 'pending',
+    detail: `${needsYou.length} item(s) queued for your review (single sign-off at the end)`,
+  });
+
+  // Needs-you: human-judgment findings (the review-queue seed), with their anchors (titles) intact.
+  for (const f of (audit.findings || [])) if (isHumanFinding(f)) needsYou.push(f);
+  // Re-stamp the signoff detail now that needsYou is filled.
+  const signoff = obligations.find((o) => o.id === 'OB-signoff');
+  if (signoff) signoff.detail = `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`;
+
+  // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
+  const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
+  let nextSuggested: string;
+  if (firstGap) nextSuggested = `Repair "${firstGap.title}" (${firstGap.detail}).`;
+  else if (!ran('run')) nextSuggested = `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
+  else nextSuggested = `All obligations satisfied — review the ${needsYou.length} queued item(s), then sign off & deliver.`;
+
+  return {
+    unit, generatedFrom: from, youAreHere, phasesDone: phases,
+    gateStatus: audit.gateStatus ?? null, score: (audit.score && audit.score.overall) ?? null,
+    obligations, needsYou, nextSuggested,
+  };
+}
+
+// ---------------- S2: writable lifecycle — persisted waivers + reconcile ----------------
+
+interface Waiver { reason: string; at: string; auditHashAtWaive: string; }
+interface JourneyState { unit: string; auditHash: string; waivers: Record<string, Waiver>; }
+
+function statePath(projectRoot: string, slug: string): string {
+  return path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
+}
+/** Evidence cursor: the audit report's content hash. A waiver is invalidated when this changes. */
+function auditHashOf(projectRoot: string, slug: string): string {
+  const p = path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`);
+  return fs.existsSync(p) ? crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex') : '';
+}
+function loadState(p: string): JourneyState | null { return readJSON(p); }
+function saveState(p: string, s: JourneyState): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(s, null, 2), 'utf-8');
+}
+
+/** Recompute nextSuggested AFTER waivers are applied (a waived obligation is not a gap). */
+function computeNext(r: JourneyReport, unit: string): string {
+  const gap = r.obligations.find((o) => o.status !== 'satisfied' && o.status !== 'waived' && o.id !== 'OB-signoff');
+  if (gap) return `Repair "${gap.title}" (${gap.detail}).`;
+  if (!r.phasesDone.some((s) => s === 'run' || s.startsWith('run'))) return `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
+  return `All obligations satisfied/waived — review the ${r.needsYou.length} queued item(s), then sign off & deliver.`;
+}
+
+/**
+ * The public entry: compute fresh, then RECONCILE with the persisted state —
+ *  - auto-close is automatic (fresh recompute reflects the current artifacts);
+ *  - an active waiver (evidence unchanged) sets status='waived' (carries the reason);
+ *  - a STALE waiver (audit changed since it was waived) is re-surfaced for re-decision (anti-amnesia).
+ * Then persist the current evidence cursor.
+ */
+export function runJourney(projectRoot: string, unit: string): JourneyReport {
+  const slug = reportSlug(unit);
+  const report = computeFresh(projectRoot, unit);
+  const sp = statePath(projectRoot, slug);
+  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+  const curHash = auditHashOf(projectRoot, slug);
+
+  for (const ob of report.obligations) {
+    const w = state.waivers[ob.id];
+    if (!w) continue;
+    if (w.auditHashAtWaive === curHash) {
+      ob.status = 'waived';
+      ob.waivedReason = w.reason;
+      ob.detail = `waived — ${w.reason}`;
+    } else {
+      report.needsYou.unshift(`⚠️ Waiver on "${ob.title}" is STALE (evidence changed since ${w.at}) — re-decide. Was: ${w.reason}`);
+    }
+  }
+  report.nextSuggested = computeNext(report, unit);
+  saveState(sp, { unit, auditHash: curHash, waivers: state.waivers });
+  return report;
+}
+
+/**
+ * Waive an obligation — REQUIRES a reason (anti-amnesia: a waiver leaves a recorded "why").
+ * Records the current evidence cursor so reconcile can invalidate it if the audit changes.
+ */
+export function waive(projectRoot: string, unit: string, obId: string, reason: string): JourneyReport {
+  if (!reason || !reason.trim()) {
+    throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
+  }
+  const slug = reportSlug(unit);
+  const fresh = computeFresh(projectRoot, unit);
+  const valid = fresh.obligations.map((o) => o.id);
+  if (!valid.includes(obId)) {
+    throw new Error(`Unknown obligation "${obId}". Valid: ${valid.join(', ')}`);
+  }
+  const sp = statePath(projectRoot, slug);
+  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+  state.waivers[obId] = { reason: reason.trim(), at: new Date().toISOString(), auditHashAtWaive: auditHashOf(projectRoot, slug) };
+  saveState(sp, state);
+  return runJourney(projectRoot, unit);
+}
+
+const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫' };
+
+export function renderJourneyBoard(r: JourneyReport): string {
+  const L: string[] = [];
+  L.push(`# Journey — ${r.unit}`);
+  L.push('');
+  L.push(`📍 **You are here:** ${r.youAreHere}` + (r.phasesDone.length ? `  (phases: ${r.phasesDone.join(' → ')})` : ''));
+  if (r.gateStatus) L.push(`   gate: **${r.gateStatus}** · score: ${r.score ?? '—'}/10`);
+  L.push('');
+  L.push('## What must still be true');
+  for (const o of r.obligations) L.push(`- ${ICON[o.status]} **${o.title}** — ${o.detail}`);
+  L.push('');
+  L.push(`## 🔎 Needs your judgment (${r.needsYou.length})`);
+  if (r.needsYou.length) for (const f of r.needsYou.slice(0, 20)) L.push(`- ${f}`);
+  else L.push('- (nothing queued)');
+  L.push('');
+  L.push(`## → Next`);
+  L.push(`${r.nextSuggested}`);
+  L.push('');
+  return L.join('\n');
+}