cool-workflow 0.1.78

package/docs/web-desktop-workbench.7.md

@@ -0,0 +1,215 @@
+# Web / Desktop Workbench
+
+CW v0.1.30 adds the Web / Desktop Workbench: a human-facing console that renders
+a run's five operator surfaces — run graph, blackboard, worker logs, candidate
+compare, and audit timeline — plus a cross-run entry point over the v0.1.28 Run
+Registry. It is a THIRD FRONT DOOR, not a new brain.
+
+Before v0.1.30 CW had no web/HTTP/UI surface at all: the CLI rendered for human
+speed and the MCP server (JSON-RPC over stdio) rendered for machine context. The
+Workbench adds human inspection at a glance — and adds NOTHING else. It computes,
+decides, and stores nothing the CLI/MCP cannot already produce.
+
+## The third front door (mechanism vs policy)
+
+The kernel and the durable `.cw/` state are the MECHANISM. The CLI, the MCP
+surface, and the Workbench are three renderings — three policies — over that one
+mechanism:
+
+- the per-run `.cw/runs/<id>/state.json` is the SINGLE source of truth
+- the v0.1.28 Run Registry is a DERIVED, rebuildable index over runs across repos
+- the Workbench is a STATELESS, READ-ONLY RENDERER over both
+
+Every Workbench panel embeds, VERBATIM, the canonical `--json` payload of ONE
+already-declared capability, assembled by calling the SAME capability core
+entries the CLI and MCP route through (the v0.1.27 parity contract, see
+[CLI ↔ MCP Parity](cli-mcp-parity.7.md)). The Workbench can show nothing the CLI
+or MCP cannot; a `workbench.view` panel is byte-for-byte equal to its underlying
+`cw <cmd> --json` payload, and that equality is parity-gated.
+
+## No hidden dashboard database
+
+CW's README promises there is "no hidden dashboard database." The Workbench
+upholds that promise by holding ZERO authoritative state:
+
+- it persists nothing — there is no Workbench store, cache, or schema
+- every response is re-derived on demand from disk; refresh re-reads `.cw/`
+- delete the host process and nothing is lost — the data IS the files
+- it forks no run/state schema; the view models in `src/types.ts`
+  (`WorkbenchRunView`, `WorkbenchPanel`, `WorkbenchServeDescriptor`) are DERIVED
+  projections that embed existing payloads, never copies of them
+
+The Workbench is OPTIONAL, like Bun is an optional execution backend: the
+committed `dist/` and a plain `node` runtime keep working with the Workbench (and
+its static UI assets under `ui/workbench/`) absent. The kernel imports the
+Workbench never; the Workbench imports the kernel.
+
+## The five panels
+
+Each panel renders existing operator vocabulary, with the same names and
+semantics as the CLI (least astonishment). For run `<id>`:
+
+1. RUN GRAPH — `cw graph <id> --json` (operator graph) plus
+   `cw multi-agent graph <id> [--view compact|critical-path] --json`. Backend
+   ids/attestations (v0.1.29) ride on the nodes; the critical path, failures,
+   missing evidence, and policy violations are never collapsed.
+2. BLACKBOARD — `cw coordinator summary <id>`, `cw blackboard summarize <id>
+   --json`, and `cw blackboard graph <id>`: topics, messages, contexts,
+   artifacts, snapshots, decisions, conflicts, and adopted/missing evidence.
+3. WORKER LOGS — `cw worker summary <id> --json`: manifests, outputs, scoped
+   results, failures, and the recorded execution backend + sandbox attestation.
+4. CANDIDATE COMPARE — `cw candidate summary <id> --json` plus
+   `cw multi-agent reasoning <id> --json`: scores, selection, rejection reasons,
+   and the v0.1.26 evidence-adoption reasoning chain (why adopted).
+5. AUDIT TIMELINE — `cw audit summary <id>`, `cw audit multi-agent <id> --json`,
+   `cw audit policy <id> --json`, and `cw audit judge <id> --json`: trust-audit
+   events, role policy decisions, provenance, judge/chair rationale, and policy
+   violations.
+
+Cross-run entry lists/searches runs via the Run Registry (`cw registry show
+--json` + `cw run list|search --json`); drilling into a run opens its five panels.
+
+## Explicit, inspectable, fail closed
+
+The Workbench surfaces freshness honestly. When a source capability is unreadable
+(a run with no blackboard yet, or unresolvable state), the panel is rendered
+`absent` with the honest error — exactly what the CLI would report — and the view
+is `resolved: false`. It never fabricates a view when source state is unreadable.
+The same `valid`/`stale`/`absent`/`missing` freshness the runtime already records
+(Run Registry, Evidence Adoption Reasoning Chain, state-explosion summaries) flows
+through verbatim.
+
+## Trust boundary
+
+The host is least-privilege and local by default:
+
+- it binds the loopback interface `127.0.0.1` ONLY — never a public address
+- it is READ-ONLY: every route is `GET`; any write verb is refused `405`
+- it rejects non-localhost `Host` headers (a DNS-rebinding defense) with `403`
+- it refuses path traversal out of `ui/workbench/` with `403`
+- it serves nothing beyond the current user's `.cw/` scope and the Run Registry's
+  registered repos
+- it fails closed on anything it cannot read
+
+The console is read-only. It offers no actions. If a future release adds an action
+(resume, rerun, dispatch), that action MUST route through an existing declared
+capability core entry — never a parallel code path — so it cannot drift from the
+CLI/MCP and is covered by the parity gate.
+
+## Surfaces
+
+```
+cw workbench view <run-id> [--json]         # five-panel WorkbenchRunView for one run
+cw workbench serve [--port N] [--scope repo|home] [--once|--json]
+```
+
+`cw workbench serve` with `--once`/`--json` prints the serve descriptor (bind
+host/port, scope, routes) and exits without starting a server; the default starts
+the localhost host (like `schedule daemon`). The MCP tools `cw_workbench_view` and
+`cw_workbench_serve` mirror these: `cw_workbench_view` returns the same view as the
+CLI `--json`, and `cw_workbench_serve` returns the descriptor only — an MCP stdio
+host cannot start a blocking server. That single side-effect difference is the
+declared, documented payload divergence recorded in `src/capability-registry.ts`;
+the descriptor payload itself is identical across surfaces.
+
+The read-only HTTP routes the host serves:
+
+```
+GET /                       # static UI shell (dependency-light; absent -> JSON-only fallback)
+GET /ui/*                   # static UI assets, read from disk
+GET /api/index              # registry show + run list/search (cross-run entry)
+GET /api/serve              # the serve descriptor
+GET /api/run/:runId         # the five-panel WorkbenchRunView
+```
+
+## Version
+
+This is CW v0.1.30. The Workbench changes no run-state schema and requires no
+migration: it is a pure read-only projection over existing durable state and
+existing capability payloads. Removing it leaves the framework fully functional.
+
+See also [Operator UX](operator-ux.7.md), [CLI ↔ MCP Parity](cli-mcp-parity.7.md),
+and [Run Registry / Control Plane](run-registry-control-plane.7.md).
+
+## Observability + Cost Accounting (v0.1.31)
+
+v0.1.31 adds Observability + Cost Accounting: `metrics show`/`metrics summary`
+derive durations, failure/verifier/acceptance rates (with sample counts and
+fail-closed `n/a`), and host-attested token/cost from existing durable run state
+— no metrics database, no collector daemon, no hidden counter. Usage is additive
+and optional (absent ⇒ `unreported`, never 0); cost is `attested` (attested usage
+× a recorded pricing policy) or clearly `estimated`, with pricing as policy. Both
+verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
+[observability-cost-accounting.7.md](observability-cost-accounting.7.md).
+
+
+## Team Collaboration (v0.1.32)
+
+v0.1.32 adds Team Collaboration: a host-attested actor and append-only
+approvals/rejections/comments/handoffs provenance-linked to a durable target,
+plus a review gate that STACKS ON the verifier gate — required approvals from
+authorized roles, enforced inside `resolveCommitGate` AFTER the verifier checks
+and never instead of them, failing closed on quorum/authority/self-approval and
+recording who approved the very artifact that shipped. Policy (required approvals,
+authorized roles, self-approval) is data, default off (pre-v0.1.32 behavior
+unchanged). The verbs are parity-gated and render read-only in the v0.1.30
+Workbench. See [Team Collaboration](team-collaboration.7.md).
+
+## Release Tooling (v0.1.33)
+
+the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(7).
+
+## Real Execution Backend Integrations (v0.1.34)
+
+container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is unavailable. See real-execution-backends(7).
+
+## Node Snapshot / Diff / Replay (v0.1.35)
+
+per-node snapshot, structural diff, and isolated deterministic replay over StateNode, reusing the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
+
+## Contract Migration Tooling (v0.1.36)
+
+first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
+
+## Control-Plane Scheduling (v0.1.37)
+
+priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
+
+## Agent Delegation Drive (v0.1.38)
+
+spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+
+## Run Retention & Provable Reclamation (v0.1.39)
+
+tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+
+## Durable State & Locking (v0.1.40)
+
+atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+
+## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
+
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+
+## Robust Result Ingest (v0.1.42)
+
+capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
+
+## No-False-Green Gate & Launch Prep (v0.1.43)
+
+Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+
+## Release-Gate Determinism & Agents Vendor (v0.1.44)
+
+Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+
+## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
+
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+0.1.51
+
+0.1.76
+
+0.1.77
+
+0.1.78

package/docs/worker-isolation.7.md

@@ -0,0 +1,167 @@
+# WORKER-ISOLATION(7)
+
+## NAME
+
+Worker Isolation - explicit path and contract boundary for dispatched CW workers
+
+## SYNOPSIS
+
+```ts
+import {
+  allocateWorkerScope,
+  recordWorkerOutput,
+  recordWorkerFailure
+} from "./worker-isolation";
+
+const scope = allocateWorkerScope(run, task, { dispatchId: task.dispatchId });
+recordWorkerOutput(run, scope.id, scope.resultPath);
+recordWorkerFailure(run, scope.id, "worker failed before producing output");
+```
+
+```text
+node dist/cli.js worker list <run-id>
+node dist/cli.js worker show <run-id> <worker-id>
+node dist/cli.js worker manifest <run-id> <worker-id>
+node dist/cli.js worker output <run-id> <worker-id> <result-file>
+node dist/cli.js dispatch <run-id> --sandbox readonly
+```
+
+## DESCRIPTION
+
+Worker Isolation is the small boundary layer between dispatch manifests, worker
+task prompts, worker-local files, result envelopes, StateNode records,
+PipelineRunner verifier gates, ErrorFeedback, and reports.
+
+It is not a process sandbox, container runtime, lease manager, or autonomous
+agent spawner. CW still writes task artifacts. Operators or the agent host run
+workers explicitly and return results through declared files.
+
+The kernel owns only:
+
+- worker scope allocation
+- stable worker manifests
+- worker-local path layout
+- sandbox profile selection and durable policy records
+- boundary validation
+- output collection
+- structured failure preservation
+
+## WORKER MODEL
+
+Dispatch moves runnable tasks to `running` and allocates one worker scope per
+dispatched task. Each worker receives a plain input file and a result path.
+
+The normal flow is:
+
+```text
+dispatch task -> worker scope -> worker.json + manifest.json/input.md -> result.md
+-> result node -> verifier node -> commit/report
+```
+
+Worker output does not mutate shared run state directly. CW records accepted
+output as result and verifier nodes after boundary checks pass.
+
+## ISOLATION BOUNDARIES
+
+Isolation is path and contract based.
+
+In CW v0.1.8, named Sandbox Profiles define the worker read paths, write paths,
+command policy, network policy, environment policy, worker output allowances,
+and host enforcement instructions. See `sandbox-profiles.7.md`.
+
+Accepted output paths must be inside the selected profile's resolved
+`writePaths`, the declared `result.md` when `workerOutput.result` is allowed,
+inside `artifacts/` when `workerOutput.artifacts` is allowed, inside `logs/`
+when `workerOutput.logs` is allowed, or inside an explicitly allowed path
+passed by the legacy runtime policy.
+
+Reads and writes are represented separately. CW validates accepted output writes
+it records. The agent host must enforce actual OS-level read/write restrictions
+while the worker is running.
+
+Out-of-scope output is rejected and preserved as:
+
+- a failed or rejected worker scope
+- an `error` StateNode
+- an ErrorFeedback record with worker and sandbox profile metadata
+
+## FILES
+
+```text
+.cw/runs/<run-id>/workers/index.json
+.cw/runs/<run-id>/workers/<worker-id>/worker.json
+.cw/runs/<run-id>/workers/<worker-id>/manifest.json
+.cw/runs/<run-id>/workers/<worker-id>/input.md
+.cw/runs/<run-id>/workers/<worker-id>/result.md
+.cw/runs/<run-id>/workers/<worker-id>/artifacts/
+.cw/runs/<run-id>/workers/<worker-id>/logs/
+.cw/runs/<run-id>/nodes/
+.cw/runs/<run-id>/feedback/
+.cw/runs/<run-id>/report.md
+```
+
+`worker.json` is the durable worker-scope state record. `manifest.json` is the
+worker-facing projection that hosts and agents read before writing `result.md`.
+Keeping them separate prevents a regenerated manifest from overwriting
+scope-only runtime state such as retry counters, lifecycle metadata, or future
+operator annotations. New v0.1.8 worker records include `sandboxProfileId`,
+`sandboxPolicy`, and a `sandbox` host contract with `enforcedByCW` and
+`hostRequired`.
+
+## FAILURE MODES
+
+Missing result files are retryable worker failures.
+
+Boundary violations are rejected worker outputs. They are not accepted into
+result state. Sandbox write denials use `sandbox-write-denied`; unknown and
+invalid profiles use `sandbox-profile-not-found` and `sandbox-profile-invalid`.
+
+Verifier failures remain verifier failures. Worker Isolation preserves the
+worker directory and records feedback so the operator can inspect or correct the
+result.
+
+Corrupt run state, unknown workers, and unknown tasks are hard errors because
+the runtime cannot proceed safely.
+
+## EXAMPLES
+
+List workers:
+
+```text
+node dist/cli.js worker list <run-id>
+```
+
+Show one worker:
+
+```text
+node dist/cli.js worker show <run-id> <worker-id>
+```
+
+Record worker output:
+
+```text
+node dist/cli.js worker output <run-id> <worker-id> .cw/runs/<run-id>/workers/<worker-id>/result.md
+```
+
+Record a failure:
+
+```text
+node dist/cli.js worker fail <run-id> <worker-id> --message "worker could not inspect assigned files"
+```
+
+## COMPATIBILITY
+
+Worker Isolation is introduced in CW v0.1.5. It adds optional worker fields to
+run paths, tasks, dispatch tasks, dispatch records, summaries, and run state.
+
+Sandbox Profiles are introduced in CW v0.1.8. The legacy `allowedPaths` field
+remains available and now mirrors effective write acceptance paths for older
+hosts. New hosts should prefer `sandboxPolicy.readPaths`,
+`sandboxPolicy.writePaths`, `sandboxPolicy.workerOutput`, and
+`sandbox.hostRequired`.
+
+Existing `plan`, `dispatch`, `result`, `node`, `contract`, and `feedback`
+commands remain compatible. The legacy `result` command still accepts a task id
+and result file. The stricter boundary-aware path is the `worker output`
+command.
+0.1.51

package/docs/workflow-app-framework.7.md

@@ -0,0 +1,274 @@
+# Workflow App framework
+
+Workflow App framework - stable userland contract for reusable CW workflow apps
+
+## Synopsis
+
+```js
+const {
+  defineWorkflowApp,
+  workflow,
+  phase,
+  agent,
+  artifact,
+  input
+} = require("../dist/workflow-app-framework");
+```
+
+```bash
+node scripts/cw.js app list
+node scripts/cw.js app show workflow-app-framework-demo
+node scripts/cw.js app validate apps/workflow-app-framework-demo/app.json
+node scripts/cw.js app show architecture-review
+npm run canonical-apps
+node scripts/cw.js app init my-app --title "My App"
+node scripts/cw.js plan my-app --question "What should happen?"
+```
+
+## Description
+
+CW treats the runner as the base system and workflow apps as userland. The
+runner owns state transitions, dispatch, result recording, verifier gates,
+commits, and reports. A workflow app owns domain-specific inputs, phases, task
+prompts, evidence requirements, and sandbox profile hints.
+
+The framework is intentionally small. The public app helpers are:
+
+- `defineWorkflowApp(definition)`
+- `workflow(definition)`
+- `phase(name, tasks, options)`
+- `agent(id, prompt, options)`
+- `artifact(id, prompt, options)`
+- `input(name, options)`
+
+Legacy workflow factories remain valid. If a canonical app owns the public id,
+the legacy wrapper should use an explicit compatibility id such as
+`legacy-research-synthesis` to avoid duplicate discovery:
+
+```js
+module.exports = ({ workflow, phase, agent, artifact }) =>
+  workflow({
+    id: "legacy-review",
+    title: "Legacy Review",
+    inputs: [{ name: "question", required: true }],
+    phases: [
+      phase("Map", [
+        agent("map:context", "Map {{question}}.")
+      ])
+    ]
+  });
+```
+
+## App Contract
+
+A first-class app contract is a plain object:
+
+```js
+module.exports = defineWorkflowApp({
+  schemaVersion: 1,
+  id: "example-review",
+  title: "Example Review",
+  summary: "Review a repository with evidence gates.",
+  version: "0.1.0",
+  author: "COOLWHITE LLC",
+  inputs: [
+    input("question", { type: "string", required: true })
+  ],
+  sandboxProfiles: ["readonly"],
+  compatibility: {
+    minVersion: "0.1.9"
+  },
+  workflow: workflow({
+    id: "example-review",
+    title: "Example Review",
+    inputs: [
+      input("question", { type: "string", required: true })
+    ],
+    limits: {
+      maxAgents: 4,
+      maxConcurrentAgents: 2
+    },
+    sandboxProfiles: ["readonly"],
+    phases: [
+      phase("Verify", [
+        artifact("verify:evidence", "Verify {{question}}.", {
+          requiresEvidence: true,
+          sandboxProfileId: "readonly"
+        })
+      ])
+    ]
+  })
+});
+```
+
+The durable fields are:
+
+- `schemaVersion`: currently `1`
+- `id`: stable app id, lowercase letters, digits, dots, and hyphens
+- `title`: human-readable name
+- `summary`: short description
+- `version`: semver app version
+- `author`: string or `{ name, url, email }`
+- `workflow`: workflow definition or manifest entrypoint
+- `inputs`: declared input definitions
+- `sandboxProfiles`: named bundled sandbox profiles used by the app
+- `compatibility`: optional CW version constraints
+- `metadata`: app-owned JSON metadata
+
+## App Directory
+
+CW also discovers app directories:
+
+```text
+apps/<app-id>/app.json
+apps/<app-id>/workflow.js
+```
+
+`app.json` stores the app metadata and points at a relative workflow entrypoint:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "example-review",
+  "title": "Example Review",
+  "version": "0.1.0",
+  "inputs": [{ "name": "question", "type": "string", "required": true }],
+  "sandboxProfiles": ["readonly"],
+  "compatibility": { "minVersion": "0.1.9" },
+  "workflow": { "entrypoint": "workflow.js" }
+}
+```
+
+The entrypoint may export a workflow object or a factory:
+
+```js
+module.exports = ({ workflow, phase, agent, input }) => {
+  const inputs = [input("question", { type: "string", required: true })];
+  return workflow({
+    id: "example-review",
+    title: "Example Review",
+    inputs,
+    phases: [
+      phase("Map", [
+        agent("map:context", "Map {{question}}.")
+      ])
+    ]
+  });
+};
+```
+
+## Validation
+
+App loading fails closed. CW validates:
+
+- app `schemaVersion`, `id`, `title`, and semver `version`
+- input names, types, duplicate inputs, and boolean flags
+- workflow id/title matching the app id/title
+- positive limits and `maxConcurrentAgents <= maxAgents`
+- phase ids and duplicate phase ids
+- task ids, duplicate task ids, task kind, prompt, and evidence flags
+- sandbox profile references on the app, workflow, and tasks
+- compatibility constraints against the current CW runtime
+
+`cw.js app validate` prints a structured result. Invalid apps return nonzero:
+
+```json
+{
+  "valid": false,
+  "issues": [
+    {
+      "code": "workflow-task-duplicate",
+      "message": "Duplicate workflow task id: map:context",
+      "path": "/path/app.json.workflow.phases.0.tasks.1.id"
+    }
+  ]
+}
+```
+
+CW does not silently rewrite malformed apps into runnable workflows.
+
+## CLI
+
+```bash
+node scripts/cw.js app list
+node scripts/cw.js app show <app-id>
+node scripts/cw.js app validate <path-or-app-id>
+node scripts/cw.js app init <app-id> --title "Title"
+node scripts/cw.js app package <app-id> --output app.cwapp.json
+```
+
+`cw.js list`, `cw.js init`, and `cw.js plan` remain compatible. `list` includes
+legacy workflow files and first-class app directories. `plan` accepts either
+kind by id.
+
+## Canonical Apps
+
+CW v0.1.13 includes four maintained canonical app directories:
+
+- `architecture-review`
+- `pr-review-fix-ci`
+- `release-cut`
+- `research-synthesis`
+
+These apps are official userland pressure tests for the framework. They use declared
+inputs, compatibility metadata, sandbox profile hints, and evidence-required
+verification or synthesis/verdict tasks. Validate and plan the full matrix with:
+
+```bash
+npm run canonical-apps
+```
+
+See [canonical-workflow-apps.7.md](canonical-workflow-apps.7.md).
+
+## MCP
+
+The MCP bridge exposes matching tools:
+
+- `cw_app_list`
+- `cw_app_show`
+- `cw_app_validate`
+- `cw_app_init`
+- `cw_app_package`
+- `cw_app_run`
+
+Tool results are JSON and use the same app summaries and validation issue
+records as the CLI. `cw_app_run` creates a run from an app id and structured
+`inputs`, then returns the run id, app id/version, state/report paths, pending
+task count, compact operator status, and next actions.
+
+The full agent-host runtime surface is documented in
+[mcp-app-surface.7.md](mcp-app-surface.7.md).
+
+## State And Reports
+
+Run state records compact app metadata at:
+
+```text
+state.json.workflow.app
+```
+
+Reports include:
+
+```text
+Workflow App: <id>@<version>
+Workflow App Source: <manifest-or-entrypoint-path>
+```
+
+CW stores app identity, version, compatibility, source path, sandbox profile
+references, and metadata. It does not copy workflow source into run state.
+
+## Files
+
+```text
+src/workflow-app-framework.ts
+dist/workflow-app-framework.js
+apps/workflow-app-framework-demo/app.json
+apps/workflow-app-framework-demo/workflow.js
+apps/architecture-review/app.json
+apps/pr-review-fix-ci/app.json
+apps/release-cut/app.json
+apps/research-synthesis/app.json
+test/workflow-app-framework-smoke.js
+test/canonical-workflow-apps-smoke.js
+```
+0.1.51

package/manifest/README.md

@@ -0,0 +1,43 @@
+# Vendor Manifest Source of Truth
+
+Every agent host scans a different, hard-coded manifest directory
+(`.claude-plugin/`, `.codex-plugin/`, `.agents/`) with a different JSON shape.
+You cannot unify the directory or the schema — so we do not try. Instead, all
+vendor manifests are **generated** from one neutral source and point at the same
+shared runtime (`skills/`, `dist/`, `apps/`, the MCP server). No vendor forks the
+logic; each manifest is a thin adapter.
+
+This is the mechanism/policy split: shared assets are mechanism, per-vendor
+manifests are policy.
+
+## Edit here, generate the rest
+
+- **Source of truth:** `plugin.manifest.json` (this directory). Edit only this.
+- **Generator:** `../scripts/gen-manifests.js`.
+
+```bash
+npm run gen:manifests          # regenerate every vendor manifest
+npm run gen:manifests -- --check   # fail (exit 1) if any generated file drifted
+```
+
+`--check` runs inside `npm run release:check`, so drift is release-blocking.
+`npm run version:sync` verifies the source version matches every surface.
+
+## Generated outputs (do NOT hand-edit)
+
+| Vendor | Marketplace | Plugin manifest | MCP config | MCP path var |
+| --- | --- | --- | --- | --- |
+| Claude Code | `../../../.claude-plugin/marketplace.json` | `../.claude-plugin/plugin.json` | `../.mcp.json` (auto-discovered) | `${CLAUDE_PLUGIN_ROOT}/` |
+| Codex / `.agents` | `../../../.agents/plugins/marketplace.json` | `../.codex-plugin/plugin.json` | `../.codex-plugin/mcp.json` | `./` |
+
+The two vendors read **different** MCP files, so the plugin-root path variable
+never collides.
+
+## Adding a new vendor (Cursor, Windsurf, …)
+
+1. Add a `targets.<vendor>` entry in `plugin.manifest.json` (its manifest path,
+   mcp path, and `pluginRootVar`).
+2. Add a matching `vendors.<vendor>.outputs` template in
+   `plugin.manifest.json`.
+3. Run `npm run gen:manifests`. Shared assets stay untouched, and the generator
+   needs no code change for a template-only vendor.