@caiqueoak/flow 0.6.0 → 0.8.0

package/skills/flow/SKILL.md

@@ -1,21 +1,20 @@
 ---
 name: flow
-description: Repository-resumable software delivery through discovery, approved engineering, complete backlog planning, human-approved implementation plans, serial implementation and review. Use /flow to start or continue this workflow.
+description: CLI-first repository-resumable delivery through deep discovery, approved product/engineering contracts, progressive specs, atomic task commits and review. Use /flow to start or continue.
 ---
 
 # Flow
 
-/flow is the only public agent workflow. Incorporate current developer intent before routing; repository routing does not authorize ignoring new requests.
+Read `invariants.md` once per invocation. Use only the project-local CLI (`npx --no-install flow`); never fetch or substitute another Flow version automatically.
 
-Read invariants.md once per invocation. All Flow CLI commands MUST use the project-local installation: `npx --no-install flow`. If unavailable, stop and ask for local installation; never use a global executable or fetch a different package automatically.
+1. Run `npx --no-install flow doctor --quick --json`. A version difference requires an explicit user decision and, when needed, `flow migrate --plan` before `--apply`.
+2. Run `npx --no-install flow sync`, then `npx --no-install flow validate --json`, then `npx --no-install flow route --json`.
+3. Read the returned instruction and every `required_context` file. Planning, implementation and review require the full approved `engineering.md` immediately before the step.
+4. Execute only that step. Use CLI commands for IDs, dependencies, blockers, approvals, task evidence and every other deterministic mutation. The agent owns qualitative product, architecture, spec, decomposition and trade-off reasoning.
+5. Run the indicated minimum validation, persist through the CLI, then route again until a real human decision, external action, unrecoverable blocker or completion.
 
-1. Run `npx --no-install flow route --json`.
-2. Read the returned instruction from this installed skill and every returned required_context file. Planning, implementation and review require rereading the FULL .flow/docs/engineering.md immediately before that step, including after resumption.
-3. Execute only the routed step, persist canonical artifacts and run its required checks.
-4. Route again. Continue until an actual human decision, external action, unrecoverable blocker or completion.
+Never approve your own proposal or infer consent. Approval records the exact document revision and ISO timestamp. A revision requires new approval.
 
-If stopped for approval, present the exact proposal and ask explicitly. Never approve your own work or treat silence as consent. Human approval must be persisted with status: approved and approved_at: ISO timestamp in the approved document. Clear state.stop_reason only when the current message resolves its decision. Revisions require a new approval, not copying an old approved_at.
+Artifact ownership: every `_flow/work-items/W###-*/` directory is canonical and always contains `spec.md`, `tasks.yaml`, `implementation-plan.md`, and `review.yaml`. Spec frontmatter owns work-item metadata and `maturity`; lifecycle is derived from it, tasks, dependencies, blockers and review. `gates.yaml` contains executable checks. `backlog.yaml` and `graph.md` under `_flow/generated/` are disposable projections: `sync` only reads canonical work-items and only writes that directory. Never commit generated projections. A task is completed by one canonical subject `type(domain): description [W###-T###]`; review completion uses `chore(domain): complete review [W###]`. A deliberate review-time spec edit belongs in that review commit, and nothing outside its work-item folder may enter it. Preserve completed history. Later corrections become a new task or maintenance work-item.
 
-Artifact owners: docs/prd.md product; docs/engineering.md engineering; backlog.yaml work-item DAG; work-items/W###-slug/spec.md scope; tasks.yaml task DAG; implementation-plan.md approved approach; state.yaml cursor; gates.yaml mechanical checks; docs/graph.md derived. Preserve completed history; changed completed scope becomes new maintenance work.
-
-Engineering changes go through reconcile/step-01-reconcile.md: propose the change, obtain approval and invalidate affected plans. A profile is bootstrap input, never a second policy engine competing with approved engineering.
+Engineering changes go through reconcile. A profile is bootstrap input, never a competing policy engine. Product-impacting technical decisions explicitly update the affected product contract.

package/skills/flow/build/step-01-execute-task.md

@@ -1,9 +1,9 @@
 # Build — execute one approved task
 
-Read the FULL engineering.md, spec, tasks and approved current implementation plan. Verify current route and approval hashes before application edits. Persist both selected work item and task in_progress; no other mutating task may be active.
+Read the applicable global PRD rules, the FULL engineering.md, spec, tasks and approved current implementation plan. Verify current route and approval hashes before application edits. Persist both selected work item and task in_progress; no other mutating task may be active.
 
 Implement the bounded approved change for readability: semantic naming, mandatory SRP, low coupling, high cohesion, locality and justified complexity. If the approach must change materially, revise the plan and ask approval before continuing.
 
-Run targeted tests and npx --no-install flow validate --pre-commit W###-T###. Mark completed only after checks pass. Code tasks get exactly one primary implementation commit with separate trailers Flow-Work-Item: W### and Flow-Task: W###-T###. Non-code tasks use none. Do not assign legacy to new work.
+Inspect the worktree, stage only this task's bounded implementation, focused tests, necessary contracts/migrations and required documentation, then compare the staged diff with the approved spec and plan. Reject unrelated changes. Run the smallest safe tests and `npx --no-install flow validate --pre-commit W###-T###`.
 
-Synchronize metadata and graph, validate traceability with npx --no-install flow trace W###-T###, validate again and route to the next task/review. Do not yield merely for status.
+Commit and complete the task atomically through `npx --no-install flow task commit W###-T### --message "type(domain): description [W###-T###]" --files path/to/file,...`. The command requires the declared files to match the staged set exactly, creates the one canonical implementation commit with matching `Flow-Work-Item` and `Flow-Task` trailers, and persists task completion in that commit. Never create the implementation commit manually and never edit task completion metadata directly. On failure, recover with `flow trace`/`flow doctor` rather than recreating implementation. Validate traceability, validate again and route onward.

package/skills/flow/discovery/bmad-comparison.md

@@ -0,0 +1,5 @@
+# BMAD comparison record
+
+Adopted: conversational elicitation proportional to ambiguity, contextual investigation, explicit gap analysis, persistent decisions/assumptions/questions, alternatives before convergence, and a product brief before detailed requirements.
+
+Rejected: BMAD's role topology, ceremony count, architecture workflow and large document templates. They add orchestration/context cost without improving Flow's contracts. Flow retains one resumable workflow, product-first discovery and separate engineering ownership.

package/skills/flow/discovery/step-01-project.md

@@ -1,5 +1,10 @@
-# Discovery — define product
+# Discovery — resolve product ambiguity
 
-Read current intent and existing product evidence. Create .flow/docs/prd.md as a coherent proposal, not architecture. Frontmatter: schema_version: 1, status: draft. Headings: # Product Requirements; ## Purpose; ## Users; ## Scope; ## Requirements; ## Constraints; ## Non-goals.
+Scale depth to ambiguity, not document length. Persist decisions, discarded alternatives, assumptions, evidence and open questions after each pass so discovery resumes without repetition.
 
-Create state.yaml with schema_version: 1, execution.phase: discovery, active.work_item/task: null, stop_reason: null, migration.status: not_required. Do not create incomplete work-item folders or implement code. Present scope and ask PRD approval through the next routed step.
+1. Problem: users, context, evidence, motivation and desired outcomes.
+2. Product: journeys, relevant personas, business rules, primary cases, exceptions, risks, metrics, alternatives and non-goals.
+3. Viability: investigate only technical questions capable of changing product, cost, schedule, risk or feasibility.
+4. Consolidation: close gaps that prevent a PRD, engineering analysis or backlog decomposition.
+
+Do not define the full architecture here. If viability changes product, record the product decision explicitly. Read `bmad-comparison.md` for the adopted/rejected prompt-design rationale.

package/skills/flow/engineering/profiles/readability-first.md

@@ -16,5 +16,6 @@ Load this reusable preference template only when synthesizing or explicitly revi
 - Modularize at meaningful boundaries. Do not introduce interfaces, factories, wrappers, layers or infrastructure without demonstrable value exceeding their complexity and maintenance cost.
 - State the concrete return on complexity before adding it. Defer speculative abstractions; optimize for reading and changing code.
 - Verify behavior, domain logic and external boundaries. Use ecosystem tooling for deterministic checks; qualitative review is not a control-plane fact.
+- Organize tests by module, domain, bounded context or feature when the stack supports it. Engineering must map changed paths/contracts to the smallest safe test commands. Escalate to the broad suite for cross-cutting/shared infrastructure, broad contracts, releases, unknown impact or when no trustworthy mapping exists; never invent a narrow command.
 
 These preferences are not a fixed architecture. Reconcile them with PRD constraints, public contracts, security, stack conventions and explicit exceptions before seeking approval.

package/skills/flow/engineering/step-02-synthesize.md

@@ -2,7 +2,7 @@
 
 Read the approved PRD, config, full existing engineering evidence, repository tooling/contracts, profiles/readability-first.md and technology-defaults.md. Use existing_code_policy improve to critique accidental structure while preserving behavior; preserve gives consistent patterns stronger weight. Neither authorizes refactoring.
 
-Recommend a complete but proportional contract. Frontmatter: schema_version: 1, status: draft, baseline.profile: flow/readability-first@1, baseline.existing_code_policy: improve|preserve|not_applicable. Include exact headings:
+Recommend a complete but proportional technical contract. Keep global product behavior in the PRD and bounded delivery behavior in work-item specs; engineering records only the technical/code/infra constraints that realize them. Frontmatter: schema_version: 1, status: draft, baseline.profile: flow/readability-first@1, baseline.existing_code_policy: improve|preserve|not_applicable. Include exact headings:
 
 # Engineering
 
@@ -34,4 +34,4 @@ Recommend a complete but proportional contract. Frontmatter: schema_version: 1,
 
 Materialize concrete paths, responsibilities, dependency direction, naming examples, stack conventions, tests and justified exceptions. Explicitly state not applicable/deferred areas and why. Review SRP, low coupling/high cohesion, colocated vertical slices, readability and complexity ROI. Do not mandate ceremony or speculative abstraction.
 
-Draft gates.yaml schema_version: 1 with only command/builtin gates using real project tooling. Qualitative review stays instructions, not agentic gates or regex coverage. Do not install tooling or change application code before approval. Route to approval.
+Draft gates.yaml schema_version: 2 with only command/builtin gates using real project tooling. Qualitative review stays instructions, not agentic gates or regex coverage. Do not install tooling or change application code before approval. Route to approval.

package/skills/flow/invariants.md

@@ -1,16 +1,16 @@
 # Flow invariants
 
-1. Persist lifecycle states only pending, in_progress and completed. Ready/Blocked are derived.
+1. Persist lifecycle states only pending, in_progress and completed. Eligible/Blocked are derived.
 2. One mutating work item and task at a time across the project. Read-only research/review may be parallel; Flow does not orchestrate concurrent mutating worktrees.
 3. PRD approval precedes engineering approval; both precede complete backlog creation.
-4. Create every known work-item folder, spec.md and tasks.yaml before any implementation. No just-in-time missing work-item artifacts in native projects.
-5. Every work item needs a human-approved implementation-plan.md before application code changes.
+4. Keep the full outlined backlog, but create a work-item spec on demand; create tasks.yaml and implementation-plan.md only once its spec is ready.
+5. Every ready work item needs a human-approved implementation-plan.md before application code changes.
 6. Plans bind to exact SHA256 engineering and spec text; stale approval cannot authorize implementation.
 7. Read the full engineering.md before planning, implementation and review. Missing/unapproved engineering blocks code.
 8. SRP, semantic naming, cohesion, low coupling, locality and justified complexity guide qualitative review; do not fake mechanical proof with Markdown regex.
 9. Dependencies belong in depends_on. External approvals belong in structured unresolved blockers.
 10. Regenerate graph through npx --no-install flow graph; never hand-edit derived output.
-11. New code tasks use implementation: commit and both Flow trailers. Non-code tasks use none. legacy is reserved for completed migrated tasks, never new work.
+11. Each mutating task is completed by `flow task commit`, which creates exactly one implementation commit with the permanent ID in the subject and both Flow trailers. Native tasks never persist traceability fields; `provenance: legacy_migration` is reserved for completed migrated tasks.
 12. Completion requires acceptance, verification, review and traceability. Completed changes become fix tasks or maintenance work.
 13. Pending migration reconciliation blocks all normal planning/build until legacy constraints reach canonical owners.
 14. Invoke only local npx --no-install flow commands. Progress alone is not a terminal stop.

package/skills/flow/planning/step-01-create-tasks.md

@@ -0,0 +1,3 @@
+# Planning — create tasks after spec readiness
+
+Read the complete ready spec and engineering contract. Decompose repository changes into independently coherent tasks with explicit dependencies. Use `flow task create`; task identity and lifecycle belong to the CLI, while Git evidence is derived from the canonical task commit. Record non-repository work in the plan instead of inventing task fields that are not part of `tasks.yaml`. Then prepare the implementation plan and obtain explicit approval before starting a task.

package/skills/flow/planning/step-01-plan-work-item.md

@@ -1,8 +1,8 @@
 # Planning — materialize the complete backlog
 
-Reread the FULL approved engineering.md and PRD. Decompose all known approved scope into bounded work items and dependencies; do not invent future scope. Create backlog.yaml schema_version: 2, work_items with id W###, folder W###-kebab-case, kind feature|technical|maintenance, title, state pending, priority positive integer, depends_on and blockers.
+Reread the FULL approved engineering.md and PRD. Decompose all known approved scope into bounded work items and dependencies; do not invent future scope. Create backlog.yaml schema_version: 3 with outlined work items using id W###, folder W###-kebab-case, kind feature|technical|maintenance, title, state pending, priority positive integer, spec_maturity, depends_on and blockers.
 
-Create EVERY known work-item folder with spec.md and tasks.yaml before implementation. Existing completed artifacts stay intact. Specs include ## Status, ## Goal, ## Scope, ## Non-goals, ## Requirements, ## Acceptance criteria, ## Decisions, ## Implementation, ## Final outcome, ## Validation and ## Follow-up. Tasks: schema_version: 1, work_item: W###, tasks with local T### IDs, title, state pending, depends_on, implementation commit|none. Preserve already completed task history.
+Do not eagerly create folders, specs, tasks or plans for outlined work. When a selected item is ready, create its spec, then tasks.yaml schema_version: 2 with local T### IDs, title, state pending, depends_on and traceability commit|none. Preserve completed history and legacy_commit provenance; never use the retired implementation task field.
 
 Structured blockers: id stable-kebab-case, type external_action|consequential_decision, description, status unresolved|resolved. Do not encode dependencies as external blockers.
 

package/skills/flow/planning/step-02-prepare-plan.md

@@ -1,6 +1,6 @@
 # Planning — draft an implementation plan
 
-Reread the FULL approved engineering.md, selected spec/tasks, affected code and tests. Write implementation-plan.md BEFORE application edits. Frontmatter: schema_version: 1, work_item: W###, status: draft, engineering_revision and spec_revision SHA256 of the exact UTF-8 files. Calculate with Node crypto; never guess.
+Reread the applicable global PRD rules, the FULL approved engineering.md, selected spec/tasks, affected code and tests. The PRD supplies product constraints; the spec supplies only this work item's bounded delivery scope. Write implementation-plan.md BEFORE application edits. Frontmatter: schema_version: 1, work_item: W###, status: draft, engineering_revision and spec_revision SHA256 of the exact UTF-8 files. Calculate with Node crypto; never guess.
 
 Use exact headings:
 

package/skills/flow/review/step-01-review-work-item.md

@@ -1,5 +1,5 @@
 # Review — verify delivery
 
-Reread FULL engineering.md, frozen scope, tasks and approved plan. Review acceptance, regressions, SRP, semantic naming, low coupling/high cohesion, vertical-slice locality and complexity ROI. Explain concrete defects, not stylistic alternatives. Run actual tests and npx --no-install flow validate; never write fake gate evidence.
+Reread applicable global PRD rules, FULL engineering.md, frozen scope, tasks and approved plan. Review acceptance, regressions, SRP, semantic naming, low coupling/high cohesion, vertical-slice locality and complexity ROI. Explain concrete defects, not stylistic alternatives. Run actual tests and npx --no-install flow validate; never write fake gate evidence.
 
-Defects become new fix tasks. Material approach changes require revised plan approval; never rewrite completed task history. Complete only after all tasks, acceptance, gates, qualitative review and traceability pass. Populate spec outcome/implementation/validation; synchronize backlog/state/graph, validate and route again.
+Defects become new fix tasks. Material approach changes require revised plan approval; never rewrite completed task history. After all tasks, acceptance, gates, qualitative review and traceability pass, run `npx --no-install flow work-item review-complete W### --domain domain`, replacing `domain` with the repository's conventional commit scope. It only finalizes this item; then run `flow route`, which alone selects the next item or finishes the project. Populate spec outcome/implementation/validation and validate again.

package/skills/flow/specification/step-01-deepen-spec.md

@@ -0,0 +1,7 @@
+# Specification — deepen one eligible work-item
+
+Read the PRD, full engineering contract and selected backlog outline. Do not deepen other work-items.
+
+Create `spec.md` with `# Work Item Specification` and sections Problem, Scope, Non-goals, Requirements, observable Acceptance criteria, Contracts, Data and APIs, Edge cases, Risks, Decisions, and Gates. Resolve ambiguity that would make planning unsafe. Keep `spec_maturity` exclusively in backlog.
+
+Validate, then run `flow work-item promote W###`. Only then create tasks and a plan. Contract, dependency or spec changes invalidate unexecuted plans; never rewrite completed history.

package/src/artifacts/backlog.mjs

@@ -1,157 +0,0 @@
-import { parseDocument } from 'yaml';
-
-export class ArtifactValidationError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'ArtifactValidationError';
-  }
-}
-
-const KINDS = new Set(['feature', 'technical', 'maintenance']);
-const STATES = new Set(['pending', 'in_progress', 'completed']);
-const WORK_ITEM_ID = /^W\d{3,}$/;
-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 !== 2) fail(`${source} schema_version must be 2.`);
-  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.`);
-    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,
-      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;
-      })
-    };
-  });
-
-  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: 2, 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');
-  if (incompleteDependencies.length)
-    return { status: 'blocked', reasons: incompleteDependencies.map((id) => ({ type: 'dependency', ref: id })) };
-  return { status: item.state === 'in_progress' ? 'in_progress' : 'ready', 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));
-}

package/src/artifacts/document.mjs

@@ -1,30 +0,0 @@
-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 };
-}

package/src/artifacts/engineering.mjs

@@ -1,26 +0,0 @@
-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;
-}

package/src/artifacts/gates.mjs

@@ -1,28 +0,0 @@
-import { parseDocument } from 'yaml';
-import { ArtifactValidationError } from './backlog.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 !== 1) throw new ArtifactValidationError(`${source} schema_version must be 1.`);
-  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.`);
-    return { ...gate, blocking: gate.blocking !== false };
-  });
-  return { schema_version: 1, gates };
-}

package/src/artifacts/implementation-plan.mjs

@@ -1,27 +0,0 @@
-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;
-}

package/src/artifacts/prd.mjs

@@ -1,12 +0,0 @@
-import { validateDocument } from './document.mjs';
-export function validatePrdDocument(text) {
-  return validateDocument(text, [
-    '# Product Requirements',
-    '## Purpose',
-    '## Users',
-    '## Scope',
-    '## Requirements',
-    '## Constraints',
-    '## Non-goals'
-  ]);
-}

package/src/artifacts/state.mjs

@@ -1,63 +0,0 @@
-import { parseDocument, stringify } from 'yaml';
-import { ArtifactValidationError } from './backlog.mjs';
-
-const PHASES = new Set([
-  'engineering_bootstrap',
-  'discovery',
-  'engineering',
-  'planning',
-  'backlog_planning',
-  'work_item_plan_approval',
-  'build',
-  'implementation',
-  'review',
-  'work_item_review',
-  'reconcile',
-  'migration_reconciliation',
-  'complete'
-]);
-const STOP_REASONS = new Set([null, 'consequential_decision', 'external_action', 'unrecoverable_blocker', 'finished']);
-
-export function emptyState() {
-  return {
-    schema_version: 1,
-    execution: { id: null, phase: 'discovery', step: 'define_project', workflow_hash: null },
-    active: { work_item: null, task: null },
-    stop_reason: null,
-    migration: { status: 'not_required' }
-  };
-}
-
-export function parseState(text, { source = 'state.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 !== 1) throw new ArtifactValidationError(`${source} schema_version must be 1.`);
-  const phase = value.execution?.phase;
-  if (!PHASES.has(phase)) throw new ArtifactValidationError(`${source} execution.phase is invalid.`);
-  if (!STOP_REASONS.has(value.stop_reason ?? null))
-    throw new ArtifactValidationError(`${source} stop_reason is invalid.`);
-  if (!['not_required', 'pending_reconciliation', 'completed'].includes(value.migration?.status ?? 'not_required'))
-    throw new ArtifactValidationError(`${source} migration.status is invalid.`);
-  return {
-    schema_version: 1,
-    execution: {
-      id: value.execution?.id ?? null,
-      phase,
-      step: value.execution?.step ?? null,
-      workflow_hash: value.execution?.workflow_hash ?? null
-    },
-    active: {
-      work_item: value.active?.work_item ?? null,
-      task: value.active?.task ?? null
-    },
-    stop_reason: value.stop_reason ?? null,
-    migration: value.migration ?? { status: 'not_required' }
-  };
-}
-
-export function stringifyState(state) {
-  return stringify(state, { lineWidth: 0 });
-}

package/src/artifacts/tasks.mjs

@@ -1,90 +0,0 @@
-import { parseDocument } from 'yaml';
-import { ArtifactValidationError } from './backlog.mjs';
-
-const STATES = new Set(['pending', 'in_progress', 'completed']);
-const TASK_ID = /^T\d{3,}$/;
-
-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 parseTasks(text, { source = 'tasks.yaml', expectedWorkItem = null } = {}) {
-  const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
-  if (document.errors.length) fail(`${source} is invalid: ${document.errors[0].message}`);
-  const value = requireObject(document.toJS(), source);
-  if (value.schema_version !== 1) fail(`${source} schema_version must be 1.`);
-  const workItem = requireString(value.work_item, `${source} work_item`);
-  if (expectedWorkItem && workItem !== expectedWorkItem)
-    fail(`${source} belongs to ${workItem}, expected ${expectedWorkItem}.`);
-  if (!Array.isArray(value.tasks)) fail(`${source} tasks must be a list.`);
-  const ids = new Set();
-  const tasks = value.tasks.map((raw, index) => {
-    const label = `tasks[${index}]`;
-    const task = requireObject(raw, label);
-    const id = requireString(task.id, `${label}.id`);
-    if (!TASK_ID.test(id)) fail(`${label}.id must use T followed by a zero-padded numeric sequence, e.g. T003.`);
-    if (ids.has(id)) fail(`${source} contains duplicate task ID '${id}'.`);
-    ids.add(id);
-    const title = requireString(task.title, `${label}.title`);
-    const state = task.state ?? task.status;
-    if (!STATES.has(state)) fail(`${label}.state must be pending, in_progress, or completed.`);
-    if (!Array.isArray(task.depends_on ?? [])) fail(`${label}.depends_on must be a list.`);
-    const dependencies = [...new Set(task.depends_on ?? [])];
-    if (dependencies.length !== (task.depends_on ?? []).length) fail(`${id} contains duplicate task dependencies.`);
-    for (const dependency of dependencies) {
-      if (!TASK_ID.test(dependency)) fail(`${id} depends on invalid task ID '${dependency}'.`);
-      if (dependency === id) fail(`${id} cannot depend on itself.`);
-    }
-    const implementation = task.implementation ?? 'commit';
-    if (!['commit', 'none', 'legacy'].includes(implementation))
-      fail(`${id}.implementation must be commit, none or legacy.`);
-    if (implementation === 'legacy' && state !== 'completed')
-      fail(`${id}: legacy is reserved for completed migrated tasks.`);
-    return {
-      id,
-      title,
-      state,
-      depends_on: dependencies,
-      implementation,
-      ...(task.legacy_commit ? { legacy_commit: task.legacy_commit } : {})
-    };
-  });
-  const byId = new Map(tasks.map((task) => [task.id, task]));
-  for (const task of tasks)
-    for (const dependency of task.depends_on)
-      if (!byId.has(dependency)) fail(`${task.id} depends on unknown task '${dependency}'.`);
-  validateTaskDag(tasks);
-  if (tasks.filter((task) => task.state === 'in_progress').length > 1)
-    fail('Only one mutating task may be in_progress.');
-  return { schema_version: 1, work_item: workItem, tasks };
-}
-
-function validateTaskDag(tasks) {
-  const indegree = new Map(tasks.map((task) => [task.id, task.depends_on.length]));
-  const dependents = new Map(tasks.map((task) => [task.id, []]));
-  for (const task of tasks) for (const dependency of task.depends_on) dependents.get(dependency).push(task.id);
-  const queue = tasks.filter((task) => task.depends_on.length === 0).map((task) => task.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 !== tasks.length) fail('tasks.yaml task dependencies contain a cycle.');
-}
-
-export function qualifiedTaskId(workItem, task) {
-  return `${workItem}-${task}`;
-}