@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/workflow/phase_inference.d.ts

@@ -0,0 +1,56 @@
+/**
+ * phase_inference.ts -- derives the active workflow phase from
+ * a WorkflowState (alpha.57).
+ *
+ * The 18-step methodology groups into 6 phases:
+ *
+ *   Phase I    -- steps 1-3.5  (intent / tier / legacy_audit)
+ *   Phase II   -- steps 4-9    (clarification rounds + blocks plan)
+ *   Phase III  -- steps 10-12  (RFP + Arch + Design specs)
+ *                step 13       (approvals)            ** still phase III **
+ *   Phase IV   -- step 14      (bootstrap)
+ *   Phase V    -- step 15      (block implementation: code + tests)
+ *   Phase VI   -- steps 16-18  (deploy + postlaunch + iterations)
+ *
+ * The "active phase" is the first phase whose closure milestone
+ * is NOT yet recorded. Closure milestones (per state.ts):
+ *
+ *   Phase I    closed by:  workflow.tier present + intent.decided_at
+ *                          + legacy_audit.ran_at + vault_inventory.ran_at
+ *   Phase II   closed by:  clarification.* rounds all done_at +
+ *                          clarification.blocks.done_at
+ *   Phase III  closed by:  specs.rfp + specs.arch + specs.design
+ *                          all done_at + approvals.* all approved_at
+ *   Phase IV   closed by:  bootstrap.done_at
+ *   Phase V    closed by:  every blocks_progress[].status === 'green'
+ *   Phase VI   closed by:  deploy.done_at + postlaunch.manual_at
+ *
+ * If WorkflowState is empty or undefined we return 'phase_i'.
+ * If everything is done we return 'phase_vi' (the last active
+ * phase -- iterations live there).
+ *
+ * The router uses the result to pick frontier vs eco:
+ *   FRONTIER_WORKFLOW_PHASES = ['phase_iii', 'phase_v']
+ *
+ * ASCII-only.
+ */
+import type { WorkflowState } from './state.js';
+export type WorkflowPhase = 'phase_i' | 'phase_ii' | 'phase_iii' | 'phase_iv' | 'phase_v' | 'phase_vi';
+/**
+ * Returns the active workflow phase for routing decisions.
+ *
+ * Algorithm: walk phase I -> phase VI in order, return the first
+ * phase whose closure milestones are not all present.
+ */
+export declare function inferActivePhase(wf: WorkflowState | undefined | null): WorkflowPhase;
+/**
+ * Tells the router whether the phase strongly suggests frontier.
+ * Mirrors FRONTIER_WORKFLOW_PHASES in cost_router; exposed here
+ * for callers that want to query without importing the router.
+ */
+export declare function phaseRequiresFrontier(phase: WorkflowPhase): boolean;
+/**
+ * Human-readable label for logs + debug.
+ */
+export declare function phaseLabel(phase: WorkflowPhase): string;
+//# sourceMappingURL=phase_inference.d.ts.map

package/dist/workflow/phase_inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase_inference.d.ts","sourceRoot":"","sources":["../../src/workflow/phase_inference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,UAAU,GACV,WAAW,GACX,UAAU,GACV,SAAS,GACT,UAAU,CAAC;AAEf;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,GAAG,aAAa,CA0CpF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAEnE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CASvD"}

package/dist/workflow/phase_inference.js

@@ -0,0 +1,107 @@
+/**
+ * phase_inference.ts -- derives the active workflow phase from
+ * a WorkflowState (alpha.57).
+ *
+ * The 18-step methodology groups into 6 phases:
+ *
+ *   Phase I    -- steps 1-3.5  (intent / tier / legacy_audit)
+ *   Phase II   -- steps 4-9    (clarification rounds + blocks plan)
+ *   Phase III  -- steps 10-12  (RFP + Arch + Design specs)
+ *                step 13       (approvals)            ** still phase III **
+ *   Phase IV   -- step 14      (bootstrap)
+ *   Phase V    -- step 15      (block implementation: code + tests)
+ *   Phase VI   -- steps 16-18  (deploy + postlaunch + iterations)
+ *
+ * The "active phase" is the first phase whose closure milestone
+ * is NOT yet recorded. Closure milestones (per state.ts):
+ *
+ *   Phase I    closed by:  workflow.tier present + intent.decided_at
+ *                          + legacy_audit.ran_at + vault_inventory.ran_at
+ *   Phase II   closed by:  clarification.* rounds all done_at +
+ *                          clarification.blocks.done_at
+ *   Phase III  closed by:  specs.rfp + specs.arch + specs.design
+ *                          all done_at + approvals.* all approved_at
+ *   Phase IV   closed by:  bootstrap.done_at
+ *   Phase V    closed by:  every blocks_progress[].status === 'green'
+ *   Phase VI   closed by:  deploy.done_at + postlaunch.manual_at
+ *
+ * If WorkflowState is empty or undefined we return 'phase_i'.
+ * If everything is done we return 'phase_vi' (the last active
+ * phase -- iterations live there).
+ *
+ * The router uses the result to pick frontier vs eco:
+ *   FRONTIER_WORKFLOW_PHASES = ['phase_iii', 'phase_v']
+ *
+ * ASCII-only.
+ */
+/**
+ * Returns the active workflow phase for routing decisions.
+ *
+ * Algorithm: walk phase I -> phase VI in order, return the first
+ * phase whose closure milestones are not all present.
+ */
+export function inferActivePhase(wf) {
+    if (!wf)
+        return 'phase_i';
+    /* Phase I: tier + intent decided + audits run */
+    const tierDecided = !!wf.tier && !!wf.tier_decided_at;
+    const intentDecided = !!wf.intent && !!wf.intent.decided_at;
+    /* legacy_audit + vault_inventory are bonus, not blockers --
+     *  some flows (greenfield) skip legacy_audit. We require only
+     *  tier + intent for phase I closure. */
+    if (!tierDecided || !intentDecided)
+        return 'phase_i';
+    /* Phase II: all clarification rounds + blocks plan */
+    const c = wf.clarification || {};
+    const clarificationRounds = [
+        c.functional,
+        c.nfr_quantitative,
+        c.nfr_structural,
+        c.nfr_governance,
+        c.nfr_operational,
+    ];
+    const allClarificationsDone = clarificationRounds.every((r) => !!r && !!r.done_at);
+    const blocksPlanned = !!c.blocks && !!c.blocks.done_at;
+    if (!allClarificationsDone || !blocksPlanned)
+        return 'phase_ii';
+    /* Phase III: 3 specs drafted + 3 approvals granted */
+    const specs = wf.specs || {};
+    const approvals = wf.approvals || {};
+    const rfpDone = !!specs.rfp?.done_at && !!approvals.rfp?.approved_at;
+    const archDone = !!specs.arch?.done_at && !!approvals.arch?.approved_at;
+    const designDone = !!specs.design?.done_at && !!approvals.design?.approved_at;
+    if (!rfpDone || !archDone || !designDone)
+        return 'phase_iii';
+    /* Phase IV: bootstrap done */
+    if (!wf.bootstrap?.done_at)
+        return 'phase_iv';
+    /* Phase V: every block green */
+    const blocks = wf.blocks_progress || [];
+    const allBlocksGreen = blocks.length > 0 && blocks.every((b) => b.status === 'green');
+    if (!allBlocksGreen)
+        return 'phase_v';
+    /* Phase VI: deploy + postlaunch (iterations continue indefinitely) */
+    return 'phase_vi';
+}
+/**
+ * Tells the router whether the phase strongly suggests frontier.
+ * Mirrors FRONTIER_WORKFLOW_PHASES in cost_router; exposed here
+ * for callers that want to query without importing the router.
+ */
+export function phaseRequiresFrontier(phase) {
+    return phase === 'phase_iii' || phase === 'phase_v';
+}
+/**
+ * Human-readable label for logs + debug.
+ */
+export function phaseLabel(phase) {
+    switch (phase) {
+        case 'phase_i': return 'I - intent / tier / audits';
+        case 'phase_ii': return 'II - clarification + blocks plan';
+        case 'phase_iii': return 'III - specs (RFP / Arch / Design)';
+        case 'phase_iv': return 'IV - bootstrap';
+        case 'phase_v': return 'V - block implementation';
+        case 'phase_vi': return 'VI - deploy + postlaunch';
+    }
+}
+//# sourceMappingURL=phase_inference.js.map

package/dist/workflow/phase_inference.js.map

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

package/dist/workflow/select.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Workflow selection (PND-094).
+ *
+ * Forge must decide which of the three workflows a request follows
+ * and ASK the user to confirm. This module is the pure heuristic
+ * behind that decision -- the doctrine tells the brain to surface
+ * the suggestion + confirm before committing to a workflow.
+ *
+ * ASCII-only.
+ */
+import type { WorkflowKind } from './definitions.js';
+export interface WorkflowClassifyInput {
+    /** The user's request text. */
+    text: string;
+    /** Whether the project already has an implementation. When false,
+     *  greenfield is the strong default regardless of wording. */
+    hasExistingCode: boolean;
+}
+export interface WorkflowClassifyResult {
+    kind: WorkflowKind;
+    /** 0..1 -- below ~0.6 the brain should ASK rather than assume. */
+    confidence: number;
+    rationale: string;
+}
+/** Suggest a workflow kind from the request + project state. The
+ *  brain confirms with the user before locking it in. */
+export declare function classifyWorkflowKind(input: WorkflowClassifyInput): WorkflowClassifyResult;
+//# sourceMappingURL=select.d.ts.map

package/dist/workflow/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/workflow/select.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb;kEAC8D;IAC9D,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAOD;yDACyD;AACzD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CAiCzF"}

package/dist/workflow/select.js

@@ -0,0 +1,38 @@
+/* Spanish + English signal words. */
+const CORRECTIVE_RE = /\b(bug|arregl|fix|roto|rota|no\s+funciona|falla|fallo|error|crash|defecto|broken|regres)/i;
+const EVOLUTIVE_RE = /\b(agreg|sum[aá]|nueva\s+func|nuevo\s+feature|feature|mejor|extend|ampli|implement|soport[ae]|add\b|enhance)/i;
+const GREENFIELD_RE = /\b(desde\s+cero|app\s+nueva|proyecto\s+nuevo|crear\s+(una|un)\s+(app|aplicaci|proyecto)|greenfield|from\s+scratch|scaffold)/i;
+/** Suggest a workflow kind from the request + project state. The
+ *  brain confirms with the user before locking it in. */
+export function classifyWorkflowKind(input) {
+    const text = input.text || '';
+    /* No code yet -> greenfield is the strong default. An explicit
+     * greenfield phrase only reinforces it. */
+    if (!input.hasExistingCode) {
+        return {
+            kind: 'greenfield',
+            confidence: GREENFIELD_RE.test(text) ? 0.95 : 0.8,
+            rationale: 'El proyecto no tiene implementacion previa.',
+        };
+    }
+    /* Live project: greenfield phrasing is unusual but possible (a
+     * rewrite). Otherwise weigh corrective vs evolutive signals. */
+    if (GREENFIELD_RE.test(text)) {
+        return { kind: 'greenfield', confidence: 0.55, rationale: 'El pedido habla de empezar de cero pese a haber codigo; confirmar si es un rewrite.' };
+    }
+    const corrective = CORRECTIVE_RE.test(text);
+    const evolutive = EVOLUTIVE_RE.test(text);
+    if (corrective && !evolutive) {
+        return { kind: 'corrective', confidence: 0.85, rationale: 'El pedido apunta a arreglar algo roto en un proyecto vivo.' };
+    }
+    if (evolutive && !corrective) {
+        return { kind: 'evolutive', confidence: 0.85, rationale: 'El pedido apunta a agregar/mejorar funcionalidad en un proyecto vivo.' };
+    }
+    if (corrective && evolutive) {
+        /* Both signals: lean corrective (a fix usually gates the rest). */
+        return { kind: 'corrective', confidence: 0.5, rationale: 'Hay senales de arreglo Y de mejora; confirmar con el usuario cual es primero.' };
+    }
+    /* Live project, no clear signal -> default evolutive, low confidence. */
+    return { kind: 'evolutive', confidence: 0.45, rationale: 'Proyecto vivo sin senal clara; asumo evolutivo pero conviene confirmar.' };
+}
+//# sourceMappingURL=select.js.map

package/dist/workflow/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../src/workflow/select.ts"],"names":[],"mappings":"AA2BA,qCAAqC;AACrC,MAAM,aAAa,GAAG,2FAA2F,CAAC;AAClH,MAAM,YAAY,GAAG,+GAA+G,CAAC;AACrI,MAAM,aAAa,GAAG,8HAA8H,CAAC;AAErJ;yDACyD;AACzD,MAAM,UAAU,oBAAoB,CAAC,KAA4B;IAC/D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;IAE9B;+CAC2C;IAC3C,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG;YACjD,SAAS,EAAE,6CAA6C;SACzD,CAAC;IACJ,CAAC;IAED;oEACgE;IAChE,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,qFAAqF,EAAE,CAAC;IACpJ,CAAC;IACD,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE1C,IAAI,UAAU,IAAI,CAAC,SAAS,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,4DAA4D,EAAE,CAAC;IAC3H,CAAC;IACD,IAAI,SAAS,IAAI,CAAC,UAAU,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,uEAAuE,EAAE,CAAC;IACrI,CAAC;IACD,IAAI,UAAU,IAAI,SAAS,EAAE,CAAC;QAC5B,mEAAmE;QACnE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,+EAA+E,EAAE,CAAC;IAC7I,CAAC;IACD,yEAAyE;IACzE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,yEAAyE,EAAE,CAAC;AACvI,CAAC"}

package/dist/workflow/state.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Yujin Forge -- Product Workflow state.
+ *
+ * Shared persistence layer for the 18-step methodology defined
+ * in docs/PRODUCT_WORKFLOW.md. State lives in the project's
+ * yujin.forge.json under `workflow.*` so it survives across
+ * sessions + can be inspected + shared via the git repo.
+ *
+ * Every command in the workflow (yf triage, yf discover, yf
+ * clarify, yf spec, yf approve, yf bootstrap, yf block dev, yf
+ * deploy, yf manual, yf metrics, yf iterate) reads + writes
+ * through this module. The chat tool surface (forge_triage,
+ * forge_discover, etc) does the same -- the underlying state
+ * is identical regardless of entry point.
+ *
+ * Schema:
+ *
+ *   workflow: {
+ *     tier: 'simple' | 'medium' | 'full' | null,
+ *     tier_reason: string,
+ *     tier_decided_at: ISO,
+ *
+ *     intent: { ... }                       // Phase I step 3
+ *     legacy_audit: { ... }                 // Phase I step 3.5
+ *     vault_inventory: { ... }              // Phase I step 2 audit
+ *
+ *     clarification: {
+ *       functional:        { done_at, summary, doc_path },   // step 4
+ *       nfr_quantitative:  { done_at, summary, doc_path },   // step 5
+ *       nfr_structural:    { done_at, summary, doc_path },   // step 6
+ *       nfr_governance:    { done_at, summary, doc_path },   // step 7
+ *       nfr_operational:   { done_at, summary, doc_path },   // step 8
+ *       blocks:            { done_at, blocks: [...] },       // step 9
+ *     },
+ *
+ *     specs: {
+ *       rfp:    { done_at, version, doc_path, sha256 },      // step 10
+ *       arch:   { done_at, version, doc_path, sha256 },      // step 11
+ *       design: { done_at, version, doc_path, sha256 },      // step 12
+ *     },
+ *
+ *     approvals: {
+ *       rfp:    { approved_at, version_sha256 },             // step 13
+ *       arch:   { approved_at, version_sha256 },             // step 13
+ *       design: { approved_at, version_sha256 },             // step 13
+ *     },
+ *
+ *     bootstrap: { done_at, stack, ci_set },                 // step 14
+ *
+ *     blocks_progress: [                                     // step 15
+ *       { block_id, status, tests_green_at, deployed_at }
+ *     ],
+ *
+ *     deploy:    { ... }                                     // step 16
+ *     postlaunch:{ ... }                                     // step 17
+ *     iterations:[{ at, type, summary }]                     // step 18
+ *   }
+ *
+ * ASCII-only.
+ */
+export type WorkflowTier = 'simple' | 'medium' | 'full';
+/** Director sprint slice 14 -- language sovereignty.
+ *  Captures the language chosen per component slot. Slots are
+ *  open-ended so a project can add (e.g.) "edge-worker" without
+ *  a schema change. */
+export interface LanguageChoice {
+    /** Lowercase token. Examples: "ts", "go", "python", "rust",
+     *  "swift", "kotlin", "dart", "java", "c#", "php", "ruby",
+     *  "elixir", "sql", "hcl", "wasm". */
+    lang: string;
+    decided_at: string;
+    /** Who made this decision. "user" = explicit choice by the
+     *  user. "director_suggested" = default the Director
+     *  proposed + the user did not override. */
+    decided_by: 'user' | 'director_suggested';
+    /** Optional free-text rationale (preserved for audit). */
+    reason?: string;
+}
+export interface LanguageChoicesState {
+    frontend?: LanguageChoice;
+    mobile?: LanguageChoice;
+    backend?: LanguageChoice;
+    data_pipeline?: LanguageChoice;
+    infra?: LanguageChoice;
+    db?: LanguageChoice;
+    ml?: LanguageChoice;
+    /** Forward-compat catch-all for adopter-specific slots. */
+    [other: string]: LanguageChoice | undefined;
+}
+export interface IntentState {
+    operation: 'migrate' | 'new' | 'modify' | null;
+    target: 'desktop' | 'mobile' | 'responsive' | 'web-and-mobile' | null;
+    input_channel: 'chat-text' | 'voice' | 'document-paste' | null;
+    project_state: 'no-code' | 'local-repo' | 'remote-repo' | 'deployed' | null;
+    legacy_framework: string | null;
+    preferred_stack: string | null;
+    use_case: 'hobby' | 'poc' | 'internal' | 'commercial' | null;
+    decided_at: string;
+}
+export interface LegacyAuditState {
+    ran_at: string;
+    framework: string;
+    framework_version: string;
+    total_files: number;
+    tsx_files: number;
+    has_tests: boolean;
+    nac3_readiness: number;
+    tech_debt_signals: string[];
+    deprecated_deps: string[];
+}
+export interface VaultInventoryState {
+    ran_at: string;
+    /** Per family: configured | skipped | unknown.
+     *  Skipped families are flagged as debt for step 16 (deploy). */
+    families: Record<string, 'configured' | 'skipped' | 'unknown'>;
+}
+export interface ClarificationRoundState {
+    done_at: string;
+    summary: string;
+    doc_path?: string;
+}
+export interface BlockPlanItem {
+    id: string;
+    name: string;
+    effort: 'S' | 'M' | 'L' | 'XL';
+    dependencies: string[];
+    mvp: boolean;
+}
+export interface ClarificationState {
+    functional?: ClarificationRoundState;
+    nfr_quantitative?: ClarificationRoundState;
+    nfr_structural?: ClarificationRoundState;
+    nfr_governance?: ClarificationRoundState;
+    nfr_operational?: ClarificationRoundState;
+    blocks?: {
+        done_at: string;
+        blocks: BlockPlanItem[];
+        mvp_path: string[];
+    };
+}
+export interface SpecDocState {
+    done_at: string;
+    version: number;
+    doc_path: string;
+    sha256: string;
+}
+export interface ApprovalState {
+    approved_at: string;
+    version_sha256: string;
+}
+export interface BootstrapState {
+    done_at: string;
+    stack: string;
+    ci_set: boolean;
+}
+export interface BlockProgressState {
+    block_id: string;
+    status: 'pending' | 'in_progress' | 'green' | 'failed';
+    tests_green_at?: string;
+    deployed_at?: string;
+}
+export interface DeployState {
+    done_at: string;
+    pipeline: string;
+    url: string;
+    smoke_at: string;
+}
+export interface PostLaunchState {
+    manual_at: string;
+    dashboards_at: string;
+    feedback_channel: string;
+}
+/** alpha.59y.4 -- document bump record carried inside an
+ *  iteration. When a user-driven change contradicts an approved
+ *  doc (RFP / Arch / Design), the LLM proposes an adenda + this
+ *  record materialises which doc gets bumped, from which version
+ *  to which, and what the adenda summarised. Cascade entries
+ *  (e.g. arch bumped because rfp changed) have status
+ *  'pending_review'; the originating doc has 'approved'. */
+export interface DocBump {
+    doc: 'rfp' | 'arch' | 'design';
+    from_version: number | null;
+    to_version: number;
+    adenda_summary: string;
+    status: 'approved' | 'pending_review' | 'rejected';
+    blocking?: boolean;
+    approved_at?: string;
+}
+export interface IterationEntry {
+    at: string;
+    type: 'bug' | 'feature_small' | 'feature_large' | 'nfr_change' | 'pivot' | 'adenda_radius';
+    summary: string;
+    /** alpha.59y.4 -- when this iteration emerges from an adenda
+     *  flow, list the docs affected + the bump records. */
+    originating_doc?: 'rfp' | 'arch' | 'design';
+    affects_docs?: Array<'rfp' | 'arch' | 'design'>;
+    doc_bumps?: DocBump[];
+    re_approval_needed?: string[];
+    completed_at?: string;
+    triggered_by?: string;
+}
+/** PND-094 -- one logged transition in the workflow evolution. */
+export interface WorkflowEvolutionEntry {
+    at: string;
+    kind: 'greenfield' | 'corrective' | 'evolutive';
+    stage_id: string;
+    stage_title: string;
+    step_id?: string;
+    step_title?: string;
+    event: 'stage_start' | 'stage_end' | 'step_start' | 'step_end';
+    content?: string;
+}
+export interface WorkflowState {
+    /** PND-094 -- which workflow this project follows. Decided up
+     *  front (greenfield for new apps; corrective/evolutive for live
+     *  projects) and confirmed by the owner. */
+    kind?: 'greenfield' | 'corrective' | 'evolutive';
+    /** PND-094 -- machine-readable mirror of the per-project workflow
+     *  evolution doc (docs/WORKFLOW_LOG.md). Append-only. */
+    evolution?: WorkflowEvolutionEntry[];
+    tier?: WorkflowTier;
+    tier_reason?: string;
+    tier_decided_at?: string;
+    intent?: IntentState;
+    legacy_audit?: LegacyAuditState;
+    vault_inventory?: VaultInventoryState;
+    /** Director sprint phase II slice 14 -- language sovereignty.
+     *  The user picks the language per slot; the Director suggests
+     *  + persists choices here. Read/written via yujin.workflow.set
+     *  /state. See docs/doctrine/language-sovereignty.md for the
+     *  algorithm + suitability table. */
+    language_choices?: LanguageChoicesState;
+    clarification?: ClarificationState;
+    specs?: {
+        rfp?: SpecDocState;
+        arch?: SpecDocState;
+        design?: SpecDocState;
+    };
+    approvals?: {
+        rfp?: ApprovalState;
+        arch?: ApprovalState;
+        design?: ApprovalState;
+    };
+    bootstrap?: BootstrapState;
+    blocks_progress?: BlockProgressState[];
+    deploy?: DeployState;
+    postlaunch?: PostLaunchState;
+    iterations?: IterationEntry[];
+}
+interface ProjectConfig {
+    workflow?: WorkflowState;
+    [key: string]: unknown;
+}
+export declare function loadConfig(projectRoot: string): Promise<ProjectConfig>;
+export declare function saveConfig(projectRoot: string, cfg: ProjectConfig): Promise<void>;
+export declare function readWorkflow(projectRoot: string): Promise<WorkflowState>;
+export declare function writeWorkflow(projectRoot: string, patch: Partial<WorkflowState>): Promise<WorkflowState>;
+/** Update a NESTED key under workflow.<group> (clarification,
+ *  specs, approvals, blocks_progress) without overwriting sibling
+ *  keys at the same level. */
+export declare function patchWorkflowGroup<K extends keyof WorkflowState>(projectRoot: string, group: K, patch: Partial<NonNullable<WorkflowState[K]>>): Promise<WorkflowState>;
+/** Append to workflow.iterations[]. Idempotent: callers should
+ *  generate a unique-ish `at` per call so duplicates do not stack. */
+export declare function appendIteration(projectRoot: string, entry: IterationEntry): Promise<WorkflowState>;
+/** alpha.59y.4 -- material change to an approved doc.
+ *
+ * Flow: user pushes a request that contradicts an approved spec
+ * (RFP / Arch / Design). The LLM:
+ *   1. Detects contradiction.
+ *   2. Calls this helper with the originating doc, the adenda
+ *      summary, and the list of downstream docs the change
+ *      cascades to.
+ *
+ * The helper:
+ *   - Bumps the originating doc's `specs[doc].version`.
+ *   - Marks the originating doc's approval as stale (so step 13
+ *     re-runs for that doc).
+ *   - Marks downstream docs as pending_review (cascade) -- the
+ *     LLM is expected to draft the delta + the user approves.
+ *   - Persists the full audit record in workflow.iterations[].
+ *
+ * Returns the updated WorkflowState. */
+export declare function advanceViaIteration(projectRoot: string, input: {
+    originating_doc: 'rfp' | 'arch' | 'design';
+    adenda_summary: string;
+    cascade_to?: Array<'rfp' | 'arch' | 'design'>;
+    triggered_by?: string;
+}): Promise<WorkflowState>;
+export {};
+//# sourceMappingURL=state.d.ts.map

package/dist/workflow/state.d.ts.map

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