@tiic-tech/openworkflow 0.1.1 → 0.1.2

package/references/validation-trust-domains.md

@@ -0,0 +1,286 @@
+# Validation Trust Domains
+
+OpenWorkflow exposes several green or red signals to Agents. Those signals must
+not imply the same scope unless they actually validate the same domain.
+
+This reference defines the initial trust-domain taxonomy for engineering
+quality governance. It is taxonomy only: it does not change CLI JSON shape,
+validator pass or fail behavior, generated surfaces, or historical artifacts.
+
+## Core Rule
+
+A command may be green for its domain while a broader domain is red. When that
+happens, the command should be interpreted as scoped trust, not global
+repository readiness.
+
+The product failure to avoid is false readiness: a fresh Agent sees a green
+entry command and assumes release-grade validation is clean.
+
+## Domains
+
+### Entry Trust
+
+Purpose: decide whether a fresh Agent can safely enter the repository and load
+bounded context.
+
+Primary commands:
+
+- `handoff --json`
+- `inspect --strict --json`
+- `context --handoff --json`
+
+Proves:
+
+- managed workflow surfaces are present and current enough for entry
+- generated adapter surfaces are present and current enough for entry
+- summary freshness and strict quality are acceptable for instantiated workflow
+  artifacts
+- current next command readiness can be checked
+- read order and blockers are available
+
+Does not prove:
+
+- broad repository validation is clean
+- historical planning artifacts are contract-current
+- all fixtures are release-ready
+- release packaging is ready
+- all quality-debt baselines are resolved
+
+### Summary Health
+
+Purpose: decide whether instantiated workflow artifacts have trusted summaries
+or current slices before raw evidence is loaded.
+
+Primary commands:
+
+- `summaries --json`
+- `summaries --strict --json`
+
+Proves:
+
+- summary or current-slice presence for instantiated artifact contracts
+- freshness status
+- strict source quality when `--strict` is enabled
+
+Does not prove:
+
+- candidate queues outside registered workflow artifacts are globally clean
+- historical archives have modern selected-change evidence
+- example fixtures match the current release gate
+
+### Managed Surface Health
+
+Purpose: decide whether OpenWorkflow-owned files and generated adapters are
+missing, stale, or repairable through source-driven sync.
+
+Primary commands:
+
+- `doctor --json`
+- `sync --root . --tools codex --json` as a preview or mutation command
+
+Proves:
+
+- managed files and adapters match the current generators
+- `AGENTS.md` managed block is current when present
+- repair guidance is available for generated-surface drift
+
+Does not prove:
+
+- artifact handoff quality
+- repository contract validation
+- release readiness
+
+### Source Contract Validation
+
+Purpose: validate source-of-truth artifacts, schemas, and repository contracts.
+
+Primary commands:
+
+- `validate --root . --json`
+- `npm run validate`
+
+Proves:
+
+- repository contract files and source artifacts meet the current validation
+  rules for the validator's release-oriented scope
+- malformed YAML, missing contract keys, missing evidence fields, high-risk
+  report section drift, and fixture shape problems are visible
+
+Does not prove:
+
+- generated adapter parity unless that validator explicitly includes it
+- runtime workflow behavior
+- Agent entry trust when failures are known historical or release-domain debt
+
+### Active Queue Health
+
+Purpose: decide whether the current queue or selected change can safely
+continue.
+
+Primary commands and surfaces:
+
+- `resume --json`
+- `changes/<plan_id>/SUMMARY.yaml`
+- `changes/<plan_id>/CANDIDATE_CHANGES.yaml`
+- selected-change artifacts
+- `git-automation commit` evidence
+
+Proves:
+
+- active queue boundary, selected candidate, next candidate, owned paths,
+  forbidden paths, validation expectations, and commit-evidence expectations
+  when the evidence is present
+
+Does not prove:
+
+- unrelated historical queues are clean
+- release readiness
+- all future candidate dependencies are satisfied
+
+### Historical Archive Health
+
+Purpose: classify older planning and evidence artifacts that may predate the
+current contract.
+
+Primary consumers:
+
+- broad repository validation
+- release readiness checks
+- migration tools
+
+Proves:
+
+- archive compatibility with current validation rules when it passes
+
+Does not prove:
+
+- active continuation blockers by itself
+
+Interpretation rule:
+
+Historical archive failures must remain visible, but entry commands should not
+silently collapse them into the same category as active selected-change
+blockers. They should be reported as archive or release-readiness debt until a
+specific migration candidate owns them.
+
+### Fixture Corpus Health
+
+Purpose: ensure examples, stress fixtures, and dev fixtures match the current
+runtime and validator contracts.
+
+Primary commands:
+
+- `npm run verify:runtime-surface`
+- targeted dev verifiers
+- broad `npm run validate` when examples are part of repository validation
+
+Proves:
+
+- selected fixtures still exercise current behavior
+- known negative and positive cases remain meaningful
+
+Does not prove:
+
+- every production path is covered
+- historical artifacts are migrated
+
+### Release Readiness
+
+Purpose: decide whether the repository is clean enough to package, publish, or
+promote as a coherent tool release.
+
+Primary commands:
+
+- `npm run validate`
+- `npm run verify:runtime-surface`
+- `npm run verify:e2e-workflow`
+- `npm run verify:agent-e2e`
+- `npm run verify:clean`
+- `npm pack` or publish gates when applicable
+
+Proves:
+
+- the broadest available local release gate is clean for the configured checks
+
+Does not prove:
+
+- that no deferred product feature remains
+- that external providers or remote integrations are healthy unless those gates
+  explicitly run them
+
+## Current Baseline Red Domains
+
+As of 2026-05-23, `handoff --json`, `inspect --strict --json`, and
+`summaries --strict --json` can pass while `npm run validate` fails.
+
+Current `npm run validate` failure classes:
+
+- selected-change atom task shape drift in historical planning folders
+- malformed YAML in a planning queue
+- missing completion evidence in older done candidates
+- missing or incomplete local commit evidence fields
+- high-risk decision report section drift
+- stale example prompt-pack shape
+
+These are baseline quality debt. They are not acceptable release health, but
+they also should not be confused with the active entry-trust domain unless a
+current queue or selected change depends on them.
+
+## Report Categories
+
+Future trust reports should classify findings into these categories when the
+domain distinction matters:
+
+- `blocking_active`: blocks the current selected change, current command, or
+  entry trust.
+- `blocking_release`: blocks release readiness but not necessarily local Agent
+  continuation.
+- `historical_debt`: older artifact or archive incompatibility that must remain
+  visible but needs a migration owner.
+- `fixture_debt`: example or stress fixture mismatch.
+- `generated_surface_drift`: managed or generated surface mismatch repairable
+  through source-driven sync or generator changes.
+- `new_regression`: failure introduced by the current candidate or dirty paths.
+- `advisory`: non-blocking guidance with a concrete follow-up.
+
+## Command Mapping
+
+| Command | Intended domain | Important non-domain |
+| --- | --- | --- |
+| `handoff --json` | Entry trust | Release readiness |
+| `inspect --strict --json` | Entry trust and strict summary quality | Historical archive migration |
+| `context --handoff --json` | Command-specific startup packet plus entry trust | Broad repository validation |
+| `summaries --strict --json` | Summary health | Queue archive health |
+| `doctor --json` | Managed surface health | Artifact handoff quality |
+| `validate --root . --json` | Source contract validation | Agent entry trust by itself |
+| `npm run validate` | Build plus broad source contract validation | Runtime E2E behavior |
+| `verify:runtime-surface` | Runtime and generated-surface regression coverage | Release readiness by itself |
+| `resume --json` | Active queue and recovery packet | Mutation authorization |
+
+## Agent Interpretation Rules
+
+1. If entry trust is red, stop before implementation.
+2. If entry trust is green and broad validation is red, continue only inside
+   the active queue or selected-change boundary and record the red broad domain
+   as residual debt.
+3. If broad validation red classes touch the files or artifact family being
+   edited, treat them as in-scope until proven historical.
+4. If a command is green for a narrow domain, do not report global readiness.
+5. If a candidate changes validation behavior, it must state which domain's
+   pass/fail semantics changed and how Agents should interpret the result.
+6. Historical debt must not be hidden to make a quality gate look healthy.
+
+## Migration Direction
+
+The next implementation candidates should move from this taxonomy toward
+structured output:
+
+- domain-classified validation sections
+- shared path safety helpers
+- extracted validator modules by domain
+- structural verifier assertions
+- typed protocol source models
+- scan-budget reporting for entry commands
+
+Each step should preserve the distinction between scoped Agent trust and broad
+release readiness.

package/references/workflow-blueprint-runtime-alignment.md

@@ -0,0 +1,287 @@
+# Workflow Blueprint Runtime Alignment
+
+This reference aligns OpenWorkflow's command vocabulary with the intended
+product-to-implementation workflow. It is a design reference, not runtime
+registration. Adding a command to this document does not expose a CLI command,
+generate adapter files, or authorize implementation.
+
+## Scope
+
+M73 owns the taxonomy and stage-graph alignment layer. It does not own detailed
+runtime contracts for `proto2html`, `html2spec`, `build`, `change`, `review`,
+`archive`, `build-agent`, or `build-skill`. Those surfaces remain deferred
+features that require later DTC queues and, where marked high risk, explicit
+approval before implementation.
+
+## Command Families
+
+OpenWorkflow commands fall into four families. The family controls how an Agent
+should reason about the command before implementation details exist.
+
+### Primary Workflow Commands
+
+Primary workflow commands represent user-visible stages in the product-to-
+implementation path. They move the project from intent to validated direction,
+prototype evidence, implementation planning, execution, and closure.
+
+Current or intended primary workflow commands:
+
+- `/ow:vision`: establish or revise the product vision and durable intent.
+- `/ow:validation`: identify the core assumption or feature that must be proven
+  before deeper design or build work.
+- `/ow:proto`: create image-first prototype evidence for product direction.
+- `/ow:tune`: refine accepted prototype evidence without changing the product
+  thesis unexpectedly.
+- `/ow:proto2html`: convert the accepted benchmark prototype image into a
+  high-fidelity HTML prototype.
+- `/ow:html2spec`: extract implementation-ready specs from locked HTML
+  prototype evidence.
+- `/ow:build`: create project-specific agent team, skill, milestone, and
+  workstream planning from approved specs.
+- `/ow:change`: execute implementation through selected, bounded changes.
+- `/ow:archive`: verify, close, and archive completed implementation work.
+
+Only commands that own a stage transition belong in this family. Planning
+helpers, analysis commands, and async checks should not be promoted into primary
+workflow stages simply because they are important.
+
+### Internal Planning And Decision Commands
+
+Internal planning and decision commands produce decision intelligence for a
+primary workflow stage. They may be invoked directly during dogfood development,
+but their architectural role is subordinate to the stage they support.
+
+Current planning intelligence commands:
+
+- `/ow:decompose-to-changes`: create or maintain one bounded candidate-change
+  queue for a feature, command surface, artifact family, module, or workflow
+  slice.
+- `/ow:analyze-changes`: recommend the next candidate from one or more queues
+  without selecting or implementing it.
+- `/ow:select-change`: select one implementable candidate and create
+  implementation-ready planning artifacts.
+
+These three commands are DTC, AC, and SC. They are the planning intelligence
+inside `/ow:change`; they are not a replacement for the full OpenWorkflow
+workflow and should not be treated as primary stages.
+
+Decision behavior also belongs in this family. `/ow:decision` records review
+outcomes and handoff decisions, but it should remain internal unless a later
+queue proves that user-facing decision control is needed.
+
+### Advanced Creation Commands
+
+Advanced creation commands create reusable execution capability for a project.
+They affect future implementation quality and therefore require stronger
+boundaries than ordinary planning notes.
+
+Intended advanced creation commands:
+
+- `/ow:build-agent`: create a bounded repo-local agent role that can participate
+  in `/ow:build`, `/ow:change`, or later workflow loops.
+- `/ow:build-skill`: create a reusable procedural capability that can be
+  registered for project-specific workflow use.
+
+These commands are not primary workflow stages. They are capability factories
+that should be governed by registry semantics, generated-surface ownership, and
+high-risk approval when they affect adapter delivery or execution behavior.
+
+### Asynchronous Support Commands
+
+Asynchronous support commands monitor, review, or enrich workflow execution
+without replacing the main stage sequence.
+
+Intended asynchronous support command:
+
+- `/ow:review`: monitor implementation output, check consistency against specs
+  and accepted artifacts, and emit findings that inform the next planning loop.
+
+`/ow:review` findings should become input evidence for `/ow:analyze-changes`
+or `/ow:select-change`. They are not a parallel implementation plan and do not
+authorize repairs without a selected change.
+
+## Boundary Rules
+
+- A command family is a design classification, not runtime exposure.
+- Primary workflow commands own stage transitions.
+- Internal planning commands advise or prepare a primary stage.
+- Advanced creation commands create reusable agents or skills and need registry
+  boundaries before runtime exposure.
+- Async support commands produce evidence for later planning; they do not
+  silently mutate implementation.
+- DTC, AC, and SC must remain inside the `/ow:change` planning loop unless a
+  later approved change deliberately revises the taxonomy.
+
+## Stage Graph
+
+The intended primary workflow chain is:
+
+```text
+/ow:vision
+  -> /ow:validation
+  -> /ow:proto
+  -> /ow:tune          # optional, repeatable
+  -> /ow:proto2html
+  -> /ow:html2spec
+  -> /ow:build
+  -> /ow:change
+  -> /ow:archive
+```
+
+The graph is a blueprint for stage responsibility. It does not mean every
+listed command is already implemented, registered, or safe to expose at runtime.
+
+### Stage Responsibilities
+
+- `/ow:vision` creates or revises durable product intent.
+- `/ow:validation` chooses the core assumption or feature that must be proven.
+- `/ow:proto` explores the accepted direction through image-first prototype
+  evidence.
+- `/ow:tune` refines accepted prototype evidence. It is optional and repeatable;
+  it should improve fidelity without silently changing the product thesis.
+- `/ow:proto2html` reconstructs the accepted benchmark prototype image as a
+  high-fidelity HTML prototype.
+- `/ow:html2spec` turns locked HTML prototype evidence into implementation-ready
+  specification artifacts.
+- `/ow:build` turns approved specs into project-specific team, skill, milestone,
+  and workstream planning.
+- `/ow:change` executes selected, bounded implementation changes through the
+  planning intelligence loop and implementation work.
+- `/ow:archive` verifies and closes completed implementation work.
+
+### Loop And Support Attachments
+
+`/ow:tune` is the only loop inside the discovery/prototype segment. It can run
+multiple times while the accepted prototype still needs refinement. Once the
+benchmark prototype is accepted for reconstruction, downstream work should
+avoid reopening product direction unless new validation evidence requires it.
+
+`/ow:review` attaches to `/ow:change` as asynchronous support. It should produce
+findings that influence the next analysis or selection pass, not bypass the
+selected-change boundary.
+
+`/ow:build-agent` and `/ow:build-skill` attach to `/ow:build` and later
+workflow loops as advanced creation commands. They create capability that may be
+used by implementation work, but they are not normal stage transitions.
+
+### Deferred Stage Surfaces
+
+The stage graph intentionally names future surfaces before they are implemented.
+Detailed contracts for `proto2html`, `html2spec`, `build`, `change`, `review`,
+`archive`, `build-agent`, and `build-skill` require separate DTC queues. The
+next deferred queue after M73 should reassess `/ow:vision`, `/ow:validation`,
+`/ow:proto`, and `/ow:tune` quality before `proto2html` proceeds.
+
+## /ow:change Planning Intelligence Boundary
+
+`/ow:change` is the implementation orchestration stage. It owns the loop that
+turns approved build or milestone context into bounded implementation work,
+evidence, review input, and completion handoff.
+
+DTC, AC, and SC sit inside that loop as planning intelligence:
+
+- DTC, `/ow:decompose-to-changes`, creates or maintains one bounded
+  `CANDIDATE_CHANGES.yaml` queue for the current feature boundary.
+- AC, `/ow:analyze-changes`, performs cross-queue priority analysis when more
+  than one active queue competes for the next change.
+- SC, `/ow:select-change`, ranks candidates inside one owning queue, selects one
+  implementable candidate, and creates implementation-ready planning artifacts.
+
+Single-queue work should normally go directly from DTC to SC. AC is not a
+mandatory pre-step when there is only one active queue; using it for every
+selection adds cost and weakens SC into a marker instead of a decision command.
+
+### Planning Loop Inputs
+
+At the boundary level, `/ow:change` can consume:
+
+- approved specs or milestone plans from `/ow:build`
+- an existing candidate queue from DTC
+- review findings from `/ow:review`
+- high-risk decision reports
+- branch, dirty-tree, validation, and commit evidence
+- user sequencing or approval constraints
+
+### Planning Loop Outputs
+
+The planning intelligence loop can produce:
+
+- a bounded `CANDIDATE_CHANGES.yaml` queue
+- optional cross-queue `CHANGE_ANALYSIS.yaml` when more than one queue competes
+- `SELECTED_CHANGE.yaml`
+- `ATOM_TASKS.yaml`
+- `IMPLEMENTATION_BRIEF.md`
+- high-risk stop packets when approval is required
+
+These outputs prepare implementation. They do not by themselves implement the
+selected change, update runtime registries, push to remote services, or approve
+high-risk work.
+
+### High-Risk Stops
+
+A high-risk report is a stop packet. It names risks, options, guardrails, go
+criteria, and stop criteria, but it is not approval. Selection or
+implementation of high-risk work requires explicit user approval of a concrete
+option from the report.
+
+### Deferred /ow:change Runtime
+
+This reference defines the planning-intelligence boundary only. Full
+`/ow:change` orchestration, including how implementation agents run, how review
+is triggered, and how archive completion is enforced, remains a deferred
+feature and needs its own DTC queue.
+
+## Future DTC Handoff Map
+
+M73 intentionally stops at taxonomy and stage-graph alignment. The following
+items are future feature boundaries, not active M73 candidates. Each item needs
+a later DTC pass before selection or implementation.
+
+Each command deserves its own candidate-change boundary. When a future queue
+reviews multiple existing commands together, such as the front-chain quality
+review, each command should still become its own candidate change inside that
+queue. Do not merge multiple command quality efforts into one broad candidate.
+
+For existing commands, the work is repair and enhancement. The queue should
+define strict acceptance criteria and stress tests before implementation starts:
+
+- behavioral acceptance for normal command use
+- malformed or missing artifact inputs
+- stale, thin, or conflicting summary/current-state inputs
+- dirty-tree and branch-boundary friction where relevant
+- JSON report quality and `ok:false` error clarity
+- generated adapter and source-of-truth drift where relevant
+- regression coverage that proves the command remains usable by a low-context
+  Agent
+
+| Order | Suggested Queue | Boundary | Risk Note |
+|---|---|---|---|
+| 1 | `M74-front-chain-command-quality-review` | Reassess `/ow:vision`, `/ow:validation`, `/ow:proto`, and `/ow:tune` under the expanded workflow. | Medium; quality of these commands affects every downstream artifact. |
+| 2 | `M75-proto2html-runtime-contract` | Define benchmark-image to high-fidelity HTML reconstruction. | High if runtime exposure or generated surfaces are changed. |
+| 3 | `M76-html2spec-artifact-contract` | Define locked HTML to implementation-ready SPEC artifacts. | Medium; must avoid inventing requirements not grounded in locked HTML. |
+| 4 | `M77-build-command-contract` | Define `/ow:build` team, skill, milestone, and workstream planning. | High if it creates executable agents or adapter-visible commands. |
+| 5 | `M78-change-planning-loop` | Define full `/ow:change` orchestration around DTC, AC, SC, implementation, and evidence. | Medium to high depending on runtime scope. |
+| 6 | `M79-review-async-pipeline` | Define `/ow:review` findings, monitoring triggers, and feedback into planning. | High if background automation or monitoring runtime is introduced. |
+| 7 | `M80-archive-completion-transaction` | Define verified completion and archive semantics for implemented changes. | High if it mutates state, git, or workflow pointers automatically. |
+| 8 | `M81-build-agent-skill-registry` | Define `/ow:build-agent` and `/ow:build-skill` registry semantics. | High if generated adapter surfaces or execution capabilities are materialized. |
+| 9 | `M82-workflow-lifecycle-transactions` | Define explicit dry-run/write transactions for workflow state movement. | Medium to high depending on mutation authority. |
+| 10 | `M83-expanded-workflow-read-model` | Extend summary-first read models across the expanded workflow. | Medium; protects low-context Agent consumption. |
+
+### Handoff Rules
+
+- Future queues must cite this M73 reference and the relevant source plan.
+- Future queues must run DTC scope control and avoid bundling multiple feature
+  boundaries into one `CANDIDATE_CHANGES.yaml`.
+- Future command-review queues should split one candidate per command, with
+  explicit repair/enhancement scope, acceptance criteria, and stress tests.
+- High-risk queues require a `HIGH_RISK_DECISION_REPORT.md` and explicit user
+  approval before selection or implementation of the high-risk option.
+- Front-chain command quality review must happen before proto2html work. Even
+  though `/ow:vision`, `/ow:validation`, `/ow:proto`, and `/ow:tune` already
+  exist, their output quality determines downstream reconstruction, spec, build,
+  and implementation quality.
+
+## Deferred Work
+
+M73 closes after C014. The next queue should be
+`M74-front-chain-command-quality-review`.

package/schemas/atom-tasks.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openworkflow.local/schemas/atom-tasks.schema.json",
+  "title": "OpenWorkflow Atom Tasks",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "contract_id",
+    "contract_type",
+    "planning_artifact_type",
+    "selected_change_id",
+    "title",
+    "status",
+    "tasks"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string"
+    },
+    "contract_id": {
+      "type": "string"
+    },
+    "contract_type": {
+      "const": "planning"
+    },
+    "planning_artifact_type": {
+      "const": "atom_tasks"
+    },
+    "selected_change_id": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "active",
+        "completed",
+        "blocked",
+        "archived"
+      ]
+    },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "task_id",
+          "title",
+          "status",
+          "type",
+          "owned_paths",
+          "done_when"
+        ],
+        "properties": {
+          "task_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "planned",
+              "in_progress",
+              "completed",
+              "blocked",
+              "deferred"
+            ]
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "read",
+              "edit",
+              "verify",
+              "document"
+            ]
+          },
+          "owned_paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "done_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}