@caiqueoak/flow 0.6.0 → 0.8.0

package/README.md

@@ -1,75 +1,97 @@
 # Flow
 
-Repository-resumable software delivery with deterministic workflow checks and explicit human approval.
+## Canonical work-items
 
-## Install and use
+Each `_flow/work-items/W###-*/` directory is the sole source of truth. Creating a work-item writes versionable shells for `spec.md`, `tasks.yaml`, `implementation-plan.md`, and `review.yaml`. A spec may remain `outlined`; tasks require a `ready` spec and implementation requires an approved plan.
+
+Run `flow sync` to materialize `_flow/generated/backlog.yaml` and `_flow/generated/graph.md`. Sync only reads canonical work-items and only writes `_flow/generated/`; it never alters a canonical source. Generated files are disposable and ignored by Git.
+
+Complete a task with one commit whose exact subject is `type(domain): description [W###-T###]` and whose body contains matching `Flow-Work-Item` and `Flow-Task` trailers. Complete review with `flow work-item review-complete W### --domain domain`, which creates `chore(domain): complete review [W###]`. The review commit may contain only that item's `spec.md` and `review.yaml`; a deliberate review-time `spec.md` amendment belongs in the same commit.
+
+CLI-first, repository-resumable delivery for coding agents. Flow keeps deterministic state, IDs, dependency routing, approvals, Git evidence, gates and migrations in the CLI while the agent owns product and engineering judgment.
+
+## Install
 
 ```bash
 npm install --save-dev @caiqueoak/flow
 npx --no-install flow init --runtime codex
+npx --no-install flow doctor --quick --json
 ```
 
-Invoke `/flow` to start or continue. The agent routes from repository state, reads the returned instruction/context, executes one step, persists artifacts, validates and routes again. Consequential decisions require explicit human input; status updates alone are not terminal stops.
+The project records the Flow package version that initialized or explicitly updated its artifacts. Flow never checks npm or upgrades a project automatically.
 
-## Engineering preferences
+## Workflow
 
-The single built-in template is **Readability First**, ID `flow/readability-first@1`. It covers Clean Code, SOLID, mandatory SRP, semantic naming, low coupling, high cohesion, vertical slices, modular ownership, locality and complexity justified by demonstrable value.
+`doctor quick → discovery → PRD → engineering → outlined backlog → selected eligible item → ready spec → tasks and plan → approval → implementation → gates → implementation commit → evidence persistence → review`
 
-The agent-readable template ships with the npm package and is installed with the runtime skill. It is loaded when generating or explicitly revising engineering, not on every task. The approved `.flow/docs/engineering.md` is the project engineering source of truth and must be read in full before planning, implementation and review. Package/profile updates never silently change that contract.
+The backlog contains every known work-item and its DAG, but deep specs are created on demand. `spec_maturity: outlined|ready` is independent of `state: pending|in_progress|completed`. Eligibility is derived from completed dependencies plus resolved external/decision blockers; then routing uses lower priority number and lower numeric ID.
 
-For existing code, `--existing-code improve` (**Improve existing structure**) treats current style as evidence, not authority; `preserve` (**Keep existing structure**) gives consistent conventions stronger weight. Both preserve behavior and external contracts; neither authorizes automatic refactoring. New projects use `not_applicable` when no meaningful code exists.
+Generated `backlog.yaml` and `graph.md` are disposable projections under `_flow/generated/`. Product truth lives in `docs/prd.md`, technical truth in `docs/engineering.md`, and work-item maturity/DAG in canonical work-item specs.
 
-## Lifecycle and approval
+## CLI
 
-Discovery → PRD approval → engineering approval → complete backlog planning → implementation-plan approval → serial implementation → review.
+Run `flow --help` or `flow <command> --help`. Help and parsing share one declarative command registry, so unknown flags and invalid combinations are rejected before writes.
 
-After product and engineering are approved, create every known work item's directory, `spec.md` and `tasks.yaml` before implementation. Then draft a concrete `implementation-plan.md` per selected work item and request human validation. It identifies exact paths, symbols/contracts, ordered changes, task mapping, engineering compliance, tests, risks, rollback and exclusions. Approval is tied to SHA256 revisions of the exact engineering and spec documents; stale plans return to drafting.
+Core read operations:
 
-PRD, engineering and plans use YAML frontmatter with `schema_version: 1`, `status: draft|approved`, and `approved_at` when approved. Engineering records baseline profile and existing-code policy. Plans record work_item, engineering_revision and spec_revision. Completed work retains its historical approval; later outcome records or engineering changes do not retroactively invalidate completed delivery.
+```bash
+flow doctor --quick --json
+flow status
+flow route --json
+flow validate [--work-item W015] [--gates]
+flow trace W015-T003
+flow gates list|run [--id ID|--task W015-T003|--work-item W015|--stage task|work-item-review|full|--all]
+```
 
-## Canonical artifacts
+Structured writes:
 
-- `config.yaml`: runtime/bootstrap preferences; installed package metadata owns version.
-- `docs/prd.md`: product truth; `docs/engineering.md`: approved engineering truth.
-- `backlog.yaml`: schema 2, W### IDs, W###-kebab-case folders, kinds, priority, dependency DAG and lifecycle.
-- `work-items/W###-slug/spec.md`: bounded scope and decisions; `tasks.yaml`: schema 1, work_item, local T### task DAG.
-- `implementation-plan.md`: human-approved implementation approach.
-- `state.yaml`: resume cursor and migration reconciliation status.
-- `gates.yaml`: schema 1, command/builtin checks only; qualitative judgment remains review instructions.
-- `docs/graph.md`: deterministic derived projection; regenerate rather than hand-edit.
+```bash
+flow work-item create --title "Customer search" --priority 2
+flow work-item dependencies W015 --depends-on W003,W009
+flow work-item blocker-add W015 --id vendor-approval --type external_action --description "Vendor approval"
+flow work-item blocker-resolve W015 --id vendor-approval
+flow work-item promote W015
+flow task create W015 --title "Add query contract"
+flow task start W015-T001
+flow scope validate W015-T001 --files src/query.js,test/query.test.js
+flow task commit W015-T001 --message "feat(search): add customer query [W015-T001]" --files src/query.js,test/query.test.js
+flow approval record _flow/work-items/W015-customer-search/implementation-plan.md
+```
 
-Persist only pending, in_progress and completed. Ready/Blocked are derived exclusively from work-item dependency edges. Blockers use `{id, type: external_action|consequential_decision, description, status: unresolved|resolved}` as context for the agent to address within the work item; they do not change execution status. Only one mutating work item/task may be active across the project. Read-only analysis may be parallel; automatic concurrent worktrees are out of scope.
+## Git traceability
 
-## CLI
+`W###-T###` is permanent task identity. A repository-mutating task creates exactly one coherent implementation commit. Its objective message contains the task ID for human visibility and its body contains the canonical machine evidence:
 
-All commands use the local installation:
+```text
+Flow-Work-Item: W015
+Flow-Task: W015-T003
+```
 
-| Command                                  | Purpose                                                                     |
-| ---------------------------------------- | --------------------------------------------------------------------------- |
-| `npx --no-install flow init`             | Configure or add/refresh runtime integrations.                              |
-| `npx --no-install flow migrate`          | Atomic structural migration, followed by semantic reconciliation via /flow. |
-| `npx --no-install flow status`           | Progress and dependency/external blockers.                                  |
-| `npx --no-install flow validate`         | Fast artifact integrity, approvals, DAGs and traceability checks.           |
-| `npx --no-install flow validate --gates` | Full validation, including configured deterministic project gates.          |
-| `npx --no-install flow route --json`     | Next legal step and required context.                                       |
-| `npx --no-install flow graph`            | Regenerate dependency graph.                                                |
-| `npx --no-install flow trace W015-T003`  | Resolve a task's implementation commit.                                     |
+`flow trace W015-T003` resolves a unique reachable commit only when its subject and both trailers agree. SHA evidence is never stored in tasks.yaml. `flow trace W015` aggregates reachable implementation commits by `Flow-Work-Item`, including task, SHA, title and changed files.
 
-Use `--help` for options; `--path` selects a project. Existing managed projects cannot change engineering through init; use /flow and approval. Older config is refused without mutation and must be migrated first. Update with your package manager, then rerun init to refresh integrations; there is no separate update/config/gates workflow command.
+## Gates and performance
 
-## Git and migration
+`flow validate` performs cheap structural checks and does not run the project test suite. `--gates` is explicit. Gates declare stage (`task`, `work-item-review`, `full`), expected cost and optional task/work-item scope. JSON output includes duration, process and Git-read metrics. Engineering maps changed paths/contracts to the smallest safe test scope and falls back to broader checks when impact is unknown.
 
-New completed code tasks have exactly one HEAD-reachable implementation commit with both trailers:
+## Migration
 
-```text
-Flow-Work-Item: W015
-Flow-Task: W015-T003
+```bash
+flow doctor
+flow migrate --plan --json
+flow migrate --apply
 ```
 
-Non-code tasks use implementation: none. SHA is derived, not canonical task identity. Pre-commit verification uses `validate --pre-commit W015-T003`; normal validation checks the integrated commit. Avoid squashing task commits when preserving task traceability.
+Planning is read-only. Apply rechecks preconditions, transforms a staging copy, validates it, swaps only on success and preserves the prior `_flow` under `_flow-backups`. Structural migration never invents semantic decisions; ambiguous legacy truths route to assisted reconcile.
 
-Migration stages transformations before swapping artifacts, rejects collisions/invalid DAGs before mutation, preserves legacy documents and commit evidence, normalizes qualified task IDs/dependencies, and routes first to semantic reconciliation. Completed migrated tasks use implementation: legacy and optional legacy_commit; they do not require invented Git trailers or rewritten historical spec headings. Pending legacy folders may be absent during reconciliation, but complete backlog planning must materialize them before native implementation. Private project artifacts are not committed as fixtures.
+## Development
 
-## Releases
+```bash
+npm run typecheck
+npm run lint
+npm run format:check
+npm test
+npm run test:package
+npm run pack:check
+```
 
-Merges to main are released automatically after the test matrix passes. Conventional Commit PR titles drive semantic-release. Installed package metadata is the Flow version source of truth; project config does not duplicate it.
+The npm binary points at ESM build output. Runtime sources remain JavaScript in this staged packaging migration and are not strict TypeScript-checked; a full source conversion is intentionally separate. The published package contains compiled source, skills and generated JSON Schemas.

package/dist/artifacts/backlog.d.mts

@@ -0,0 +1,16 @@
+export declare class ArtifactValidationError extends Error {
+    constructor(message: any);
+}
+export declare function parseBacklog(text: any, { source }?: {
+    source?: string | undefined;
+}): {
+    schema_version: number;
+    work_items: any;
+};
+export declare function validateAcyclic(items: any): void;
+export declare function deriveExecutionStatus(item: any, byId: any): {
+    status: string;
+    reasons: any[];
+};
+export declare function topologicalOrder(items: any): any[];
+//# sourceMappingURL=backlog.d.mts.map

package/dist/artifacts/backlog.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlog.d.mts","sourceRoot":"","sources":["../../src/artifacts/backlog.mjs"],"names":[],"mappings":"AAQA,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAO,KAAA,EAGlB;CACF;AAsBD,wBAAgB,YAAY,CAAC,IAAI,KAAA,EAAE,EAAE,MAAuB,EAAE;;CAAK;;;EAwFlE;AAED,wBAAgB,eAAe,CAAC,KAAK,KAAA,QAgBpC;AAED,wBAAgB,qBAAqB,CAAC,IAAI,KAAA,EAAE,IAAI,KAAA;;;EAU/C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,KAAA,SA6BrC"}

package/dist/artifacts/backlog.mjs

@@ -0,0 +1,193 @@
+import { parseDocument } from 'yaml';
+import { BACKLOG_SCHEMA_VERSION, LIFECYCLE_STATES, SPEC_MATURITIES, WORK_ITEM_ID as WORK_ITEM_ID_PATTERN } from '../domain/contracts.mjs';
+export class ArtifactValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArtifactValidationError';
+    }
+}
+const KINDS = new Set(['feature', 'technical', 'maintenance']);
+const STATES = new Set(LIFECYCLE_STATES);
+const SPEC_MATURITY = new Set(SPEC_MATURITIES);
+const WORK_ITEM_ID = WORK_ITEM_ID_PATTERN;
+const WORK_ITEM_FOLDER = /^W\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function fail(message) {
+    throw new ArtifactValidationError(message);
+}
+function requireObject(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(`${label} must be a mapping.`);
+    return value;
+}
+function requireString(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        fail(`${label} must be a non-empty string.`);
+    return value.trim();
+}
+export function parseBacklog(text, { source = 'backlog.yaml' } = {}) {
+    const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
+    if (document.errors.length)
+        fail(`${source} is invalid: ${document.errors[0].message}`);
+    const backlog = requireObject(document.toJS(), source);
+    if (backlog.schema_version !== BACKLOG_SCHEMA_VERSION)
+        fail(`${source} schema_version must be ${BACKLOG_SCHEMA_VERSION}.`);
+    if (!Array.isArray(backlog.work_items))
+        fail(`${source} work_items must be a list.`);
+    const ids = new Set();
+    const items = backlog.work_items.map((raw, index) => {
+        const label = `work_items[${index}]`;
+        const item = requireObject(raw, label);
+        const id = requireString(item.id, `${label}.id`);
+        if (!WORK_ITEM_ID.test(id))
+            fail(`${label}.id must use W followed by a zero-padded numeric sequence, e.g. W015.`);
+        if (ids.has(id))
+            fail(`${source} contains duplicate work-item ID '${id}'.`);
+        ids.add(id);
+        const folder = requireString(item.folder ?? item.path, `${label}.folder`);
+        if (!WORK_ITEM_FOLDER.test(folder))
+            fail(`${label}.folder must use W###-kebab-case, e.g. W015-learner-web-application.`);
+        const numericId = id.slice(1);
+        if (!folder.startsWith(`W${numericId}-`))
+            fail(`${label}.folder must preserve the numeric sequence from ${id}.`);
+        if (!KINDS.has(item.kind))
+            fail(`${label}.kind must be feature, technical, or maintenance.`);
+        const title = requireString(item.title, `${label}.title`);
+        const state = item.state ?? item.status;
+        if (!STATES.has(state))
+            fail(`${label}.state must be pending, in_progress, or completed.`);
+        if (!Number.isInteger(item.priority) || item.priority < 1)
+            fail(`${label}.priority must be a positive integer.`);
+        const specMaturity = item.spec_maturity ?? (item.state === 'pending' ? 'outlined' : 'ready');
+        if (!SPEC_MATURITY.has(specMaturity))
+            fail(`${label}.spec_maturity must be outlined or ready.`);
+        if (state !== 'pending' && specMaturity !== 'ready')
+            fail(`${id}: in_progress or completed work must have spec_maturity ready.`);
+        if (!Array.isArray(item.depends_on ?? []))
+            fail(`${label}.depends_on must be a list.`);
+        if (!Array.isArray(item.blockers ?? []))
+            fail(`${label}.blockers must be a list when present.`);
+        const dependencies = [];
+        const seenDependencies = new Set();
+        for (const rawDependency of item.depends_on ?? []) {
+            const dependency = requireString(rawDependency, `${label}.depends_on entry`);
+            if (!WORK_ITEM_ID.test(dependency))
+                fail(`${label}.depends_on contains invalid work-item ID '${dependency}'.`);
+            if (dependency === id)
+                fail(`Work item '${id}' cannot depend on itself.`);
+            if (seenDependencies.has(dependency))
+                fail(`Work item '${id}' lists dependency '${dependency}' more than once.`);
+            seenDependencies.add(dependency);
+            dependencies.push(dependency);
+        }
+        return {
+            id,
+            folder,
+            kind: item.kind,
+            title,
+            state,
+            priority: item.priority,
+            spec_maturity: specMaturity,
+            depends_on: dependencies,
+            blockers: (item.blockers ?? []).map((blocker) => {
+                requireObject(blocker, `${id} blocker`);
+                if (!/^[a-z][a-z0-9-]*$/.test(blocker.id ?? ''))
+                    fail(`${id} blocker.id must be stable kebab-case.`);
+                if (!['external_action', 'consequential_decision'].includes(blocker.type))
+                    fail(`${id} blocker.type is invalid.`);
+                requireString(blocker.description, `${id} blocker.description`);
+                if (!['unresolved', 'resolved'].includes(blocker.status))
+                    fail(`${id} blocker.status is invalid.`);
+                return blocker;
+            }),
+            ...(item.objective ? { objective: requireString(item.objective, `${label}.objective`) } : {}),
+            boundaries: Array.isArray(item.boundaries) ? item.boundaries : [],
+            requirements: Array.isArray(item.requirements) ? item.requirements : [],
+            provides: Array.isArray(item.provides) ? item.provides : [],
+            consumes: Array.isArray(item.consumes) ? item.consumes : [],
+            dependency_rationale: item.dependency_rationale &&
+                typeof item.dependency_rationale === 'object' &&
+                !Array.isArray(item.dependency_rationale)
+                ? item.dependency_rationale
+                : {}
+        };
+    });
+    const byId = new Map(items.map((item) => [item.id, item]));
+    for (const item of items) {
+        for (const dependency of item.depends_on) {
+            if (!byId.has(dependency))
+                fail(`Work item '${item.id}' depends on unknown work item '${dependency}'.`);
+        }
+    }
+    validateAcyclic(items);
+    if (items.filter((item) => item.state === 'in_progress').length > 1)
+        fail('Only one mutating work item may be in_progress.');
+    return { schema_version: BACKLOG_SCHEMA_VERSION, work_items: items };
+}
+export function validateAcyclic(items) {
+    const indegree = new Map(items.map((item) => [item.id, item.depends_on.length]));
+    const dependents = new Map(items.map((item) => [item.id, []]));
+    for (const item of items)
+        for (const dependency of item.depends_on)
+            dependents.get(dependency).push(item.id);
+    const queue = items.filter((item) => indegree.get(item.id) === 0).map((item) => item.id);
+    let visited = 0;
+    while (queue.length) {
+        const id = queue.shift();
+        visited += 1;
+        for (const dependent of dependents.get(id)) {
+            const next = indegree.get(dependent) - 1;
+            indegree.set(dependent, next);
+            if (next === 0)
+                queue.push(dependent);
+        }
+    }
+    if (visited !== items.length)
+        fail('backlog.yaml work-item dependencies contain a cycle.');
+}
+export function deriveExecutionStatus(item, byId) {
+    if (item.state === 'completed')
+        return { status: 'completed', reasons: [] };
+    const incompleteDependencies = item.depends_on.filter((id) => byId.get(id)?.state !== 'completed');
+    const unresolvedBlockers = item.blockers.filter((blocker) => blocker.status === 'unresolved');
+    const reasons = [
+        ...incompleteDependencies.map((id) => ({ type: 'dependency', ref: id })),
+        ...unresolvedBlockers.map((blocker) => ({ type: 'blocker', ref: blocker.id, blocker_type: blocker.type }))
+    ];
+    if (reasons.length)
+        return { status: 'blocked', reasons };
+    return { status: item.state === 'in_progress' ? 'in_progress' : 'eligible', reasons: [] };
+}
+export function topologicalOrder(items) {
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const remaining = new Map(items.map((item) => [item.id, item.depends_on.length]));
+    const dependents = new Map(items.map((item) => [item.id, []]));
+    for (const item of items)
+        for (const dependency of item.depends_on)
+            dependents.get(dependency).push(item.id);
+    const compare = (a, b) => a.localeCompare(b);
+    for (const ids of dependents.values())
+        ids.sort(compare);
+    const ready = items
+        .filter((item) => item.depends_on.length === 0)
+        .map((item) => item.id)
+        .sort(compare);
+    const levels = new Map(ready.map((id) => [id, 0]));
+    const orderedIds = [];
+    while (ready.length) {
+        const id = ready.shift();
+        orderedIds.push(id);
+        for (const dependent of dependents.get(id)) {
+            levels.set(dependent, Math.max(levels.get(dependent) ?? 0, (levels.get(id) ?? 0) + 1));
+            const count = remaining.get(dependent) - 1;
+            remaining.set(dependent, count);
+            if (count === 0) {
+                ready.push(dependent);
+                ready.sort(compare);
+            }
+        }
+    }
+    return orderedIds
+        .map((id) => byId.get(id))
+        .sort((a, b) => levels.get(a.id) - levels.get(b.id) || compare(a.id, b.id));
+}
+//# sourceMappingURL=backlog.mjs.map

package/dist/artifacts/backlog.mjs.map

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

package/dist/artifacts/document.d.mts

@@ -0,0 +1,6 @@
+export declare function documentRevision(text: any): any;
+export declare function documentMetadata(text: any): any;
+export declare function validateDocument(text: any, headings: any): {
+    errors: any[];
+};
+//# sourceMappingURL=document.d.mts.map

package/dist/artifacts/document.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.mts","sourceRoot":"","sources":["../../src/artifacts/document.mjs"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAAC,IAAI,KAAA,OAEpC;AACD,wBAAgB,gBAAgB,CAAC,IAAI,KAAA,OAQpC;AACD,wBAAgB,gBAAgB,CAAC,IAAI,KAAA,EAAE,QAAQ,KAAA;;EAe9C"}

package/dist/artifacts/document.mjs

@@ -0,0 +1,39 @@
+import { parseDocument } from 'yaml';
+import { createHash } from 'node:crypto';
+export function documentRevision(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+export function documentMetadata(text) {
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!match)
+        throw new Error('Missing YAML frontmatter.');
+    const doc = parseDocument(match[1], { uniqueKeys: true });
+    if (doc.errors.length)
+        throw new Error(doc.errors[0].message);
+    const value = doc.toJS();
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Frontmatter must be a mapping.');
+    return value;
+}
+export function validateDocument(text, headings) {
+    let metadata = {};
+    const errors = [];
+    try {
+        metadata = documentMetadata(text);
+    }
+    catch (error) {
+        errors.push(error.message);
+    }
+    if (metadata.schema_version !== 1)
+        errors.push('schema_version must be 1.');
+    if (!['draft', 'approved'].includes(metadata.status))
+        errors.push('status must be draft or approved.');
+    if (metadata.status === 'approved' && (!metadata.approved_at || Number.isNaN(Date.parse(metadata.approved_at))))
+        errors.push('approved_at must record the human approval timestamp.');
+    const actual = new Set(text.split(/\r?\n/).filter((line) => /^#{1,2} /.test(line)));
+    for (const heading of headings)
+        if (!actual.has(heading))
+            errors.push(`Missing ${heading}.`);
+    return { ...metadata, errors };
+}
+//# sourceMappingURL=document.mjs.map

package/dist/artifacts/document.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.mjs","sourceRoot":"","sources":["../../src/artifacts/document.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,MAAM,UAAU,gBAAgB,CAAC,IAAI;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AACD,MAAM,UAAU,gBAAgB,CAAC,IAAI;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;IACnE,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACzD,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACnH,OAAO,KAAK,CAAC;AACf,CAAC;AACD,MAAM,UAAU,gBAAgB,CAAC,IAAI,EAAE,QAAQ;IAC7C,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,MAAM,MAAM,GAAG,EAAE,CAAC;IAClB,IAAI,CAAC;QACH,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,QAAQ,CAAC,cAAc,KAAK,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAC5E,IAAI,CAAC,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IACvG,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,QAAQ,CAAC,WAAW,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;QAC7G,MAAM,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpF,KAAK,MAAM,OAAO,IAAI,QAAQ;QAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,GAAG,CAAC,CAAC;IAC7F,OAAO,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC"}

package/dist/artifacts/engineering.d.mts

@@ -0,0 +1,5 @@
+export declare const ENGINEERING_HEADINGS: string[];
+export declare function validateEngineeringDocument(text: any): {
+    errors: any[];
+};
+//# sourceMappingURL=engineering.d.mts.map

package/dist/artifacts/engineering.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineering.d.mts","sourceRoot":"","sources":["../../src/artifacts/engineering.mjs"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,UAehC,CAAC;AACF,wBAAgB,2BAA2B,CAAC,IAAI,KAAA;;EAO/C"}

package/dist/artifacts/engineering.mjs

@@ -0,0 +1,27 @@
+import { validateDocument } from './document.mjs';
+import { READABILITY_FIRST_PROFILE } from '../shared/profiles.mjs';
+export const ENGINEERING_HEADINGS = [
+    '# Engineering',
+    '## System shape',
+    '## Modules and ownership',
+    '## Dependency direction and boundaries',
+    '## Vertical slices and code organization',
+    '## Naming and readability conventions',
+    '## Data ownership and persistence',
+    '## Error handling',
+    '## Testing and verification',
+    '## Dependencies and external services',
+    '## Security and operations',
+    '## Deterministic gates',
+    '## Deferred complexity',
+    '## Exceptions'
+];
+export function validateEngineeringDocument(text) {
+    const result = validateDocument(text, ENGINEERING_HEADINGS);
+    if (result.baseline?.profile !== READABILITY_FIRST_PROFILE.id)
+        result.errors.push('baseline.profile must be flow/readability-first@1.');
+    if (!['improve', 'preserve', 'not_applicable'].includes(result.baseline?.existing_code_policy))
+        result.errors.push('baseline.existing_code_policy is invalid.');
+    return result;
+}
+//# sourceMappingURL=engineering.mjs.map

package/dist/artifacts/engineering.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineering.mjs","sourceRoot":"","sources":["../../src/artifacts/engineering.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACnE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,eAAe;IACf,iBAAiB;IACjB,0BAA0B;IAC1B,wCAAwC;IACxC,0CAA0C;IAC1C,uCAAuC;IACvC,mCAAmC;IACnC,mBAAmB;IACnB,6BAA6B;IAC7B,uCAAuC;IACvC,4BAA4B;IAC5B,wBAAwB;IACxB,wBAAwB;IACxB,eAAe;CAChB,CAAC;AACF,MAAM,UAAU,2BAA2B,CAAC,IAAI;IAC9C,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,QAAQ,EAAE,OAAO,KAAK,yBAAyB,CAAC,EAAE;QAC3D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;IAC3E,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,oBAAoB,CAAC;QAC5F,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IAClE,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/artifacts/gates.d.mts

@@ -0,0 +1,7 @@
+export declare function parseGates(text: any, { source }?: {
+    source?: string | undefined;
+}): {
+    schema_version: number;
+    gates: any;
+};
+//# sourceMappingURL=gates.d.mts.map

package/dist/artifacts/gates.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.mts","sourceRoot":"","sources":["../../src/artifacts/gates.mjs"],"names":[],"mappings":"AAMA,wBAAgB,UAAU,CAAC,IAAI,KAAA,EAAE,EAAE,MAAqB,EAAE;;CAAK;;;EAgC9D"}

package/dist/artifacts/gates.mjs

@@ -0,0 +1,42 @@
+import { parseDocument } from 'yaml';
+import { ArtifactValidationError } from './backlog.mjs';
+import { GATES_SCHEMA_VERSION } from '../domain/contracts.mjs';
+const KINDS = new Set(['command', 'builtin']);
+export function parseGates(text, { source = 'gates.yaml' } = {}) {
+    const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
+    if (document.errors.length)
+        throw new ArtifactValidationError(`${source} is invalid: ${document.errors[0].message}`);
+    const value = document.toJS();
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ArtifactValidationError(`${source} must be a mapping.`);
+    if (value.schema_version !== GATES_SCHEMA_VERSION)
+        throw new ArtifactValidationError(`${source} schema_version must be ${GATES_SCHEMA_VERSION}.`);
+    if (!Array.isArray(value.gates))
+        throw new ArtifactValidationError(`${source} gates must be a list.`);
+    const ids = new Set();
+    const gates = value.gates.map((gate, index) => {
+        if (!gate || typeof gate !== 'object' || Array.isArray(gate))
+            throw new ArtifactValidationError(`gates[${index}] must be a mapping.`);
+        if (typeof gate.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(gate.id))
+            throw new ArtifactValidationError(`gates[${index}].id must be lower kebab-case.`);
+        if (ids.has(gate.id))
+            throw new ArtifactValidationError(`duplicate gate '${gate.id}'.`);
+        ids.add(gate.id);
+        if (!KINDS.has(gate.kind))
+            throw new ArtifactValidationError(`${gate.id}.kind must be command or builtin.`);
+        if (gate.kind === 'command' && (!gate.command || typeof gate.command !== 'string'))
+            throw new ArtifactValidationError(`${gate.id} command gate requires command.`);
+        const stage = gate.stage ?? 'full';
+        if (!['task', 'work-item-review', 'full'].includes(stage))
+            throw new ArtifactValidationError(`${gate.id}.stage must be task, work-item-review or full.`);
+        const cost = gate.cost ?? 'medium';
+        if (!['low', 'medium', 'high'].includes(cost))
+            throw new ArtifactValidationError(`${gate.id}.cost must be low, medium or high.`);
+        const scope = gate.scope ?? {};
+        if (!scope || typeof scope !== 'object' || Array.isArray(scope))
+            throw new ArtifactValidationError(`${gate.id}.scope must be a mapping.`);
+        return { ...gate, stage, cost, scope, blocking: gate.blocking !== false };
+    });
+    return { schema_version: GATES_SCHEMA_VERSION, gates };
+}
+//# sourceMappingURL=gates.mjs.map

package/dist/artifacts/gates.mjs.map

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

package/dist/artifacts/implementation-plan.d.mts

@@ -0,0 +1,11 @@
+export { documentRevision } from './document.mjs';
+export declare const PLAN_HEADINGS: string[];
+export declare function validateImplementationPlan(text: any, { workItem, engineeringText, specText, checkRevisions }: {
+    checkRevisions?: boolean | undefined;
+    engineeringText: any;
+    specText: any;
+    workItem: any;
+}): {
+    errors: any[];
+};
+//# sourceMappingURL=implementation-plan.d.mts.map

package/dist/artifacts/implementation-plan.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implementation-plan.d.mts","sourceRoot":"","sources":["../../src/artifacts/implementation-plan.mjs"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,eAAO,MAAM,aAAa,UAazB,CAAC;AACF,wBAAgB,0BAA0B,CAAC,IAAI,KAAA,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAqB,EAAE;;;;;CAAA;;EAU9G"}

package/dist/artifacts/implementation-plan.mjs

@@ -0,0 +1,30 @@
+import { documentRevision, validateDocument } from './document.mjs';
+export { documentRevision } from './document.mjs';
+export const PLAN_HEADINGS = [
+    '# Implementation Plan',
+    '## Outcome',
+    '## Current state',
+    '## Proposed changes',
+    '## Execution sequence',
+    '## Task mapping',
+    '## Data and control flow',
+    '## Engineering compliance',
+    '## Tests and validation',
+    '## Risks and rollback',
+    '## Deliberately excluded',
+    '## Human decisions required'
+];
+export function validateImplementationPlan(text, { workItem, engineeringText, specText, checkRevisions = true }) {
+    const result = validateDocument(text, PLAN_HEADINGS);
+    if (result.work_item !== workItem)
+        result.errors.push('Plan belongs to a different work item.');
+    for (const key of ['engineering_revision', 'spec_revision'])
+        if (!/^[a-f0-9]{64}$/.test(result[key] ?? ''))
+            result.errors.push(`${key} must be SHA256.`);
+    if (checkRevisions && result.engineering_revision !== documentRevision(engineeringText))
+        result.errors.push('Engineering revision is stale.');
+    if (checkRevisions && result.spec_revision !== documentRevision(specText))
+        result.errors.push('Spec revision is stale.');
+    return result;
+}
+//# sourceMappingURL=implementation-plan.mjs.map

package/dist/artifacts/implementation-plan.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"implementation-plan.mjs","sourceRoot":"","sources":["../../src/artifacts/implementation-plan.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,uBAAuB;IACvB,YAAY;IACZ,kBAAkB;IAClB,qBAAqB;IACrB,uBAAuB;IACvB,iBAAiB;IACjB,0BAA0B;IAC1B,2BAA2B;IAC3B,yBAAyB;IACzB,uBAAuB;IACvB,0BAA0B;IAC1B,6BAA6B;CAC9B,CAAC;AACF,MAAM,UAAU,0BAA0B,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,EAAE;IAC7G,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ;QAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IAChG,KAAK,MAAM,GAAG,IAAI,CAAC,sBAAsB,EAAE,eAAe,CAAC;QACzD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,kBAAkB,CAAC,CAAC;IAC9F,IAAI,cAAc,IAAI,MAAM,CAAC,oBAAoB,KAAK,gBAAgB,CAAC,eAAe,CAAC;QACrF,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IACvD,IAAI,cAAc,IAAI,MAAM,CAAC,aAAa,KAAK,gBAAgB,CAAC,QAAQ,CAAC;QACvE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/artifacts/prd.d.mts

@@ -0,0 +1,4 @@
+export declare function validatePrdDocument(text: any): {
+    errors: any[];
+};
+//# sourceMappingURL=prd.d.mts.map

package/dist/artifacts/prd.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prd.d.mts","sourceRoot":"","sources":["../../src/artifacts/prd.mjs"],"names":[],"mappings":"AACA,wBAAgB,mBAAmB,CAAC,IAAI,KAAA;;EAUvC"}