@pugi/cli 0.1.0-beta.28 → 0.1.0-beta.29

package/dist/core/artifact-chain/steps.js

@@ -0,0 +1,169 @@
+/**
+ * Artifact chain step definitions — Pugi α7 Wave 6 (2026-05-27).
+ *
+ * The chain encodes Pugi's moat: an operator drops one high-level intent
+ * (`pugi chain new "<intent>"`) and the CLI walks a deterministic 7-step
+ * pipeline that produces verifiable artifacts at each stage. Every step
+ * dispatches to a specialist persona via the existing `pugi delegate`
+ * surface so the same Tier 1 roster powers both ad-hoc dispatch and the
+ * artifact chain.
+ *
+ * The pipeline:
+ *
+ *   1. prd       — Olivia (PM):       structured PRD (goals / users /
+ *                                     acceptance criteria / scope)
+ *   2. adr       — Marcus (CTO):      architectural decision record
+ *                                     against the team ADR template
+ *   3. mindmap   — Marcus (CTO):      mermaid mindmap of the solution
+ *                                     surface (modules + boundaries)
+ *   4. er        — Hiroshi (Lead Dev):entity-relationship mermaid for
+ *                                     the data model the design implies
+ *   5. sequence  — Hiroshi (Lead Dev):mermaid sequence diagram covering
+ *                                     the critical happy + sad paths
+ *   6. tests     — Vera (QA):         spec scaffolding mapped from the
+ *                                     PRD acceptance criteria
+ *   7. code      — Hiroshi (Lead Dev):implementation diff against the
+ *                                     scaffolded specs
+ *
+ * Persona slugs are lowercase ASCII to satisfy the server-side delegate
+ * grammar (`^[a-z]+$`, mirrors `PUGI_DELEGATE_REGEX` in
+ * `apps/admin-api/src/pugi/sessions.controller.ts`). The chain never
+ * invents new personas — it only orchestrates the existing roster.
+ *
+ * Module contract:
+ *
+ *   - This file is PURE data. No fs, no network, no side effects.
+ *     Importing it from a hot path (REPL keystroke handler) is safe.
+ *   - The step ORDER is authoritative; downstream consumers MUST iterate
+ *     `CHAIN_STEPS` instead of hand-rolling their own arrays so future
+ *     re-ordering lands in exactly one place.
+ *   - Personas are looked up by slug at dispatch time so a roster change
+ *     does not silently break the chain — the dispatcher surfaces an
+ *     `unknown_persona` outcome the operator can see.
+ */
+/**
+ * Ordered, frozen table of the seven steps. The chain state machine
+ * advances through this array exactly once; re-ordering OR insertion
+ * is a breaking change for any chain currently on disk.
+ */
+export const CHAIN_STEPS = Object.freeze([
+    {
+        id: 'prd',
+        ordinal: 1,
+        persona: 'olivia',
+        personaLabel: 'Olivia (PM)',
+        artifactFilename: 'PRD.md',
+        briefTemplate: 'Produce a structured PRD for chain {{chainId}}. ' +
+            'Operator intent: "{{intent}}". ' +
+            'Cover: goals, target users, success metrics, ' +
+            'numbered acceptance criteria (## Acceptance Criteria), scope + non-scope, ' +
+            'risks. Output markdown ready for prd-check ingestion.',
+        gloss: 'Structured PRD — goals, users, acceptance criteria, scope',
+    },
+    {
+        id: 'adr',
+        ordinal: 2,
+        persona: 'marcus',
+        personaLabel: 'Marcus (CTO)',
+        artifactFilename: 'ADR.md',
+        briefTemplate: 'Produce an architectural decision record for chain {{chainId}}. ' +
+            'Read the PRD at .pugi/chains/{{chainId}}/PRD.md verbatim. ' +
+            'Follow the team ADR template: Status, Context, Decision, ' +
+            'Consequences, Alternatives Considered. ' +
+            'Be explicit about boundary changes the decision implies.',
+        gloss: 'Architectural decision record per team ADR template',
+    },
+    {
+        id: 'mindmap',
+        ordinal: 3,
+        persona: 'marcus',
+        personaLabel: 'Marcus (CTO)',
+        artifactFilename: 'MINDMAP.mmd',
+        briefTemplate: 'Produce a mermaid mindmap of the solution surface for chain {{chainId}}. ' +
+            'Read PRD + ADR at .pugi/chains/{{chainId}}/PRD.md and ADR.md. ' +
+            'Root node = the feature name; first-level branches = subsystems; ' +
+            'leaves = concrete modules / endpoints / tables. ' +
+            'Output ONE mermaid `mindmap` fenced block — no prose.',
+        gloss: 'Mermaid mindmap — solution surface (subsystems + modules)',
+    },
+    {
+        id: 'er',
+        ordinal: 4,
+        persona: 'hiroshi',
+        personaLabel: 'Hiroshi (Lead Dev)',
+        artifactFilename: 'ER.mmd',
+        briefTemplate: 'Produce a mermaid entity-relationship diagram for chain {{chainId}}. ' +
+            'Source: PRD + ADR + MINDMAP under .pugi/chains/{{chainId}}/. ' +
+            'Use `erDiagram` syntax. Cover every persisted entity the ' +
+            'design implies; mark PK / FK relationships explicitly.',
+        gloss: 'Mermaid ER diagram — persisted entities + relationships',
+    },
+    {
+        id: 'sequence',
+        ordinal: 5,
+        persona: 'hiroshi',
+        personaLabel: 'Hiroshi (Lead Dev)',
+        artifactFilename: 'SEQUENCE.mmd',
+        briefTemplate: 'Produce mermaid sequence diagrams for chain {{chainId}}. ' +
+            'Cover the critical happy path + at least one sad path. ' +
+            'Source: PRD acceptance criteria + ER diagram. ' +
+            'Use `sequenceDiagram` syntax; one diagram per fenced block.',
+        gloss: 'Mermaid sequence diagrams — happy + sad path flows',
+    },
+    {
+        id: 'tests',
+        ordinal: 6,
+        persona: 'vera',
+        personaLabel: 'Vera (QA)',
+        artifactFilename: 'TESTS.md',
+        briefTemplate: 'Produce spec scaffolding for chain {{chainId}}. ' +
+            'Map every numbered PRD acceptance criterion (under ## Acceptance Criteria) ' +
+            'to one or more concrete test descriptions using node:test + node:assert. ' +
+            'Format: criterion-id → test file path → `it(...)` blocks. ' +
+            'Output markdown only — no executable code.',
+        gloss: 'Spec scaffolding — PRD criteria mapped to test descriptions',
+    },
+    {
+        id: 'code',
+        ordinal: 7,
+        persona: 'hiroshi',
+        personaLabel: 'Hiroshi (Lead Dev)',
+        artifactFilename: 'CODE.md',
+        briefTemplate: 'Produce an implementation plan + diff references for chain {{chainId}}. ' +
+            'Read PRD, ADR, MINDMAP, ER, SEQUENCE, TESTS under .pugi/chains/{{chainId}}/. ' +
+            'Output: file-by-file changes (path, change kind, summary), ' +
+            'with each change tied back to a PRD criterion id. ' +
+            'NO inline patches — patches land via `pugi patch apply` after operator review.',
+        gloss: 'Implementation plan — file changes mapped to PRD criteria',
+    },
+]);
+/**
+ * Resolve a step descriptor by id. Returns `undefined` for unknown ids
+ * so callers can surface a structured error instead of panicking.
+ */
+export function findStep(id) {
+    return CHAIN_STEPS.find((step) => step.id === id);
+}
+/**
+ * Index of step ids in chain order. Exported so the state machine can
+ * answer "what is the next step after X?" without re-scanning the
+ * table on every transition.
+ */
+export const CHAIN_STEP_IDS = Object.freeze(CHAIN_STEPS.map((s) => s.id));
+/**
+ * Total number of steps in the chain. Hard-coded constant exported so
+ * downstream renderers can size their progress bars without iterating.
+ */
+export const CHAIN_STEP_COUNT = CHAIN_STEPS.length;
+/**
+ * Interpolate the brief template with chain context. The template
+ * grammar is intentionally minimal — only `{{chainId}}` and `{{intent}}`
+ * are honoured. Unknown placeholders are left verbatim so a template
+ * typo surfaces in the dispatched brief instead of silently dropping.
+ */
+export function renderBrief(template, ctx) {
+    return template
+        .replace(/\{\{chainId\}\}/g, ctx.chainId)
+        .replace(/\{\{intent\}\}/g, ctx.intent);
+}
+//# sourceMappingURL=steps.js.map

package/dist/core/repl/session.js

@@ -1023,6 +1023,38 @@ export class ReplSession {
                 }
                 return verdict;
             }
+            case 'chain': {
+                // Wave 6 (2026-05-27): forward to the shell-surface runner so
+                // the slash + top-level CLI share one parser + dispatcher.
+                // Dynamic import keeps the chain module out of the REPL hot
+                // path. The slash variant does NOT inject the live delegate
+                // wire-up — operators wanting full dispatch run `pugi chain
+                // next` from a fresh shell. The slash form is best-effort for
+                // status / show / list which are read-only.
+                try {
+                    const { runChainCommand } = await import('../../runtime/commands/chain.js');
+                    const lines = [];
+                    await runChainCommand(verdict.args, {
+                        cwd: process.cwd(),
+                        json: false,
+                        writeOutput: (_payload, text) => {
+                            const trimmed = text.replace(/\n+$/u, '');
+                            if (trimmed.length > 0)
+                                lines.push(trimmed);
+                        },
+                    });
+                    for (const line of lines)
+                        this.appendSystemLine(line);
+                    if (lines.length === 0) {
+                        this.appendSystemLine('/chain: no output.');
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/chain failed: ${message}`);
+                }
+                return verdict;
+            }
             case 'permissions': {
                 // Leak L6: handle the `/permissions [mode] [--persist]` flow.
                 // The session module forwards to the runtime helper so the

package/dist/core/repl/slash-commands.js

@@ -94,6 +94,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'version', args: '', gloss: 'Show CLI version', group: 'Meta' },
     { name: 'doctor', args: '', gloss: 'Environment health report (auth · API · Node · disk · MCP · …)', group: 'Meta' },
     { name: 'prd-check', args: '<prd-path | --all> [--json]', gloss: 'Verify PRD acceptance criteria against committed code/tests/docs (Wave 6)', group: 'Meta' },
+    { name: 'chain', args: '<new|status|next|show|export|list> [...args]', gloss: 'Artifact chain — PRD → ADR → mindmap → ER → sequence → tests → code (Wave 6)', group: 'Meta' },
     { name: 'stickers', args: '', gloss: 'show Pugi brand stickers (gimmick)', group: 'Meta' },
     { name: 'feedback', args: '', gloss: 'file a bug / feature / general comment without leaving the REPL', group: 'Meta' },
     { name: 'share', args: '[--gist|--pugi] [--redact] [--preview]', gloss: 'Export session transcript to gist / pugi.io (leak L20)', group: 'Meta' },
@@ -441,6 +442,15 @@ export function parseSlashCommand(input) {
             const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
             return { kind: 'prd-check', args: tokens };
         }
+        case 'chain': {
+            // Wave 6 (2026-05-27): forward the tokenized argv to
+            // `runChainCommand` via the session module. Subcommands are
+            // single tokens (new / status / next / show / export / list);
+            // the `new` subcommand accepts the intent as the joined tail so
+            // operators can write `/chain new add auth flow` без quoting.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'chain', args: tokens };
+        }
         case 'compact': {
             // Leak L8 (2026-05-27): graduated from stub. The session module
             // owns the summariser round-trip; tail args are ignored today

package/dist/runtime/cli.js

@@ -37,6 +37,7 @@ import { runPrivacyCommand } from './commands/privacy.js';
 import { runReport } from './commands/report.js';
 import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
 import { parsePrdCheckArgs, runPrdCheckCommand, } from './commands/prd-check.js';
+import { runChainCommand, } from './commands/chain.js';
 import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
 import { runStickersCommand } from './commands/stickers.js';
 import { runRepoMapCommand } from './commands/repo-map.js';
@@ -96,6 +97,11 @@ const handlers = {
     ask: dispatchAsk,
     build: runEngineTask('build_task'),
     budget: dispatchBudget,
+    // Wave 6 (2026-05-27): `pugi chain` walks the deterministic 7-step
+    // artifact pipeline (PRD → ADR → mindmap → ER → sequence → tests →
+    // code). Subcommands: new / status / next / show / export / list.
+    // Same handler powers the in-REPL `/chain` slash via session.ts.
+    chain: dispatchChain,
     code: runEngineTask('code'),
     config: dispatchConfig,
     cost: dispatchCost,
@@ -597,6 +603,32 @@ async function dispatchDelegate(args, flags, _session) {
         },
     });
 }
+/**
+ * `pugi chain` — Wave 6 artifact chain dispatcher (2026-05-27).
+ * Forwards to `runChainCommand` with the live credential + session
+ * opener wired so the dispatcher can hit Anvil. The slash counterpart
+ * `/chain` shares the same handler via session.ts so the surface
+ * stays single-sourced.
+ */
+async function dispatchChain(args, flags, _session) {
+    await runChainCommand(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        resolveConfig: () => {
+            const credential = resolveActiveCredential();
+            if (!credential)
+                return null;
+            return buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey });
+        },
+        openSession: async (config, workspaceCwd) => {
+            const result = await openPugiSession(config, { workspaceCwd });
+            if (result.status === 'ok')
+                return { sessionId: result.response.sessionId };
+            return { error: `${result.status}: ${result.message}` };
+        },
+    });
+}
 async function dispatchUndo(args, flags, session) {
     await runUndoCommand(args, {
         workspaceRoot: process.cwd(),
@@ -1626,6 +1658,16 @@ const COMMAND_HELP_BODIES = {
         'Slugs (Tier 1 alpha 7.5): dev qa pm devops researcher analyst designer',
         'frontend architect. `pugi roster` lists the live set.',
     ],
+    chain: [
+        'pugi chain — Wave 6 artifact chain (PRD → ADR → mindmap → ER → sequence → tests → code).',
+        '',
+        '  new "<intent>"           Start a new chain from a one-sentence intent.',
+        '  status [<chain-id>]      Show current cursor + per-step table.',
+        '  next [<chain-id>]        Approve the last step and dispatch the next.',
+        '  show <step> [<chain-id>] Render one artifact (prd/adr/mindmap/er/sequence/tests/code).',
+        '  export [<chain-id>] [--json]   Bundle every artifact as markdown / JSON.',
+        '  list                     Every chain in this workspace.',
+    ],
     dispatch: [
         'pugi dispatch <sub> — inspect + GC fork-subagent prompt-cache inherit refs.',
         '',