workflow-supervisor 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+This changelog was reconstructed from npm publish metadata and git history after the first four package versions were published without GitHub releases or tags.
+
+## 0.1.4 - 2026-06-19
+
+Prepared for npm publication.
+
+### Added
+
+- Added profile-based supervisor execution with `lean_work_unit_runner`, `strict_full_workflow`, and `planning_only`.
+- Added compact lean-runner ledger guidance for large bounded backlogs that need lower memory and less ceremony.
+- Added native worker resource lifecycle rules for thread and subagent transports.
+
+### Changed
+
+- Changed strict worker lifecycle from logical closeout only to `planned -> handed_off -> acknowledged -> reported -> verified -> resource_closed -> closed`.
+- Required native worker transports to record resource ids, close actions, and close results before final workflow outcome.
+- Made one-shot portable delegation the preferred worker path when it satisfies the work, because it avoids resident native workers.
+
+### Fixed
+
+- Prevented completed Codex subagents from remaining open after workflow-supervisor runs by requiring `close_agent` for every recorded native `agent_id`.
+- Blocked final PASS when any native worker has no recorded close result.
+- Reduced large-backlog memory pressure by defaulting lean execution to same-session phased work unless workers are explicitly authorized or risk escalation requires them.
+
+### Verified
+
+- Expanded lifecycle tests to cover profile selection, lean ledgers, native worker resource ids, `close_agent`, and close-result gates.
+
+## 0.1.3 - 2026-06-17
+
+Published to npm: 2026-06-17 22:09:08 UTC
+
+Commit: `154bbd7`
+
+### Added
+
+- Added resumable SPEC gate behavior so broad source-controlled workflows can pause for human review before final work units, dossiers, and implementation.
+- Added resume guidance for autonomous workflows that block on a human decision, including updates to workflow state, goal state, and decision artifacts.
+- Expanded troubleshooting guidance for broad roadmap scope, residual risks that hide required work, and SPEC review before work units.
+
+### Changed
+
+- Hardened workflow-supervisor scope coverage so material source requirements, roadmap phases, exit criteria, named systems, and numeric targets must be mapped to work units, explicitly deferred, blocked, or marked non-material.
+- Updated acceptance, loop-policy, work-unit, and workflow-docs instructions to preserve source requirement strength and avoid quiet downgrades.
+
+### Verified
+
+- Expanded workflow-supervisor lifecycle tests for source coverage, SPEC review, and resume behavior.
+
+## 0.1.2 - 2026-06-17
+
+Published to npm: 2026-06-17 16:00:10 UTC
+
+Commit: `b449656`
+
+### Changed
+
+- Reworked the workflow-supervisor skill around a stricter worker-agent supervisor architecture.
+- Made explicit supervisor invocation require full intake, work units, dossiers, worker-agent contracts, scoped handoffs, report schema, and verification even for small tasks.
+- Clarified that implementation, verification, repair-authoring, and documentation are separate worker-agent responsibilities when an automated worker path is available.
+- Rewrote the README around the strict worker supervisor model and the current package workflow.
+
+### Verified
+
+- Added lifecycle coverage for strict supervisor invocation behavior.
+
+## 0.1.1 - 2026-06-15
+
+Published to npm: 2026-06-15 10:59:19 UTC
+
+Commit: `ee4c02b`
+
+### Added
+
+- Added portable worker delegation for Codex and Claude Code through `workflow-supervisor delegate`.
+- Added `WorkerReportV1` and `DossierV1` schema artifacts plus dossier validation before delegation.
+- Added `delegate-doctor` for adapter inspection and optional probe runs.
+- Added project-scope `.workflow/` ignore handling for local workflow state.
+- Added portable delegation documentation and tests for install, delegation, and lifecycle behavior.
+
+### Changed
+
+- Renamed the primary package executable path around `workflow-supervisor` while keeping `workflow-skills` as an executable alias.
+- Narrowed certified install/delegation targets to Codex, Claude Code, and generic Markdown contexts.
+- Strengthened validation to include adapter metadata and schema artifacts.
+
+### Verified
+
+- Added Node test coverage for delegate CLI behavior, installation behavior, portable delegation, and supervisor lifecycle handling.
+
+## 0.1.0 - 2026-06-14
+
+Published to npm: 2026-06-14 23:35:57 UTC
+
+Source: npm tarball contents. The GitHub release tag for this version is a reconstructed source snapshot from the npm tarball because no exact matching commit exists in the branch history for this first publish.
+
+### Added
+
+- Initial npm package for the workflow-supervisor skill pack.
+- Added the bundled skills: `workflow-supervisor`, `worker-roles`, `acceptance-matrix`, `dossier-builder`, `source-corpus`, `loop-policy`, `work-unit`, and `workflow-docs`.
+- Added the `workflow-supervisor` and `workflow-skills` executables for listing, validating, installing, uninstalling, and emitting portable context.
+- Added Codex, Claude Code, OpenCode, HermesAgent, and generic adapter metadata, plus package documentation, troubleshooting notes, compatibility notes, and a README overview.
+- Added packaging metadata, test coverage, and prepublish validation through `npm run validate`.
+
+### Verified
+
+- Initial package validation covered skill folder structure, `SKILL.md` metadata, and publishable package layout.

package/README.md

@@ -1,8 +1,8 @@
 # Workflow Supervisor
 
-Workflow Supervisor is a strict supervision skill pack for agent work that needs to stay organized, resumable, and evidence-backed.
+Workflow Supervisor is a profile-based supervision skill pack for agent work that needs to stay organized, resumable, evidence-backed, and proportional to the work.
 
-It is for moments when you do not want an agent to jump straight into implementation, lose the thread halfway through, verify its own work, or quietly skip important handoffs. You ask for the supervisor, the supervisor asks the right setup questions, turns the work into small units, creates worker dossiers, delegates scoped work to real worker agents when possible, verifies the results, and leaves a clear outcome trail.
+It is for moments when you do not want an agent to lose the thread halfway through, quietly skip scope, or turn a large backlog into an unreviewable blur. You ask for the supervisor, the supervisor selects the right execution profile, keeps the work units explicit, verifies results with evidence, and leaves a clear outcome trail. Heavy multi-agent ceremony is available when risk justifies it; large pure backlogs can use a lean runner that keeps the agent focused on delivery.
 
 Example prompt:
 
@@ -19,8 +19,12 @@ The correct first response is not code. The correct first response is an intake
 Workflow Supervisor gives you a repeatable workflow for serious agent tasks:
 
 - a complete intake before work starts
+- a profile choice between `lean_work_unit_runner`, `strict_full_workflow`, and `planning_only`
 - a source map, even when the only source is the user prompt
+- a source-requirement coverage ledger so roadmap items and exit criteria cannot disappear
+- a `SPEC.md` review gate where humans can ask questions, request revisions, block, defer, or approve before work units are finalized
 - bounded work units, including `WU-001` for tiny tasks
+- a compact ledger for high-throughput work-unit execution
 - dossiers that tell each worker exactly what to do and what not to touch
 - separate implementer, verifier, repair, and documenter responsibilities
 - structured worker reports instead of loose prose
@@ -29,7 +33,7 @@ Workflow Supervisor gives you a repeatable workflow for serious agent tasks:
 - durable `.workflow/` state when the work needs to survive context loss
 - a final report with checks, risks, workers, and next actions
 
-The main design choice is simple: the supervisor coordinates, workers do scoped work, and the CLI stays small.
+The main design choice is simple: supervision is mandatory when requested, but overhead is profile-dependent. Work units preserve clarity. Workers, dossiers, and independent verifier loops are tools for strict or escalated work, not a default tax on every unit.
 
 ## The Mental Model
 
@@ -86,43 +90,75 @@ flowchart TB
 
 ## What Happens When You Invoke It
 
-When you explicitly invoke `workflow-supervisor`, `$workflow-supervisor`, or say to use the skill, the workflow enters `strict_full_workflow`.
+When you explicitly invoke `workflow-supervisor`, `$workflow-supervisor`, or say to use the skill, the first decision is the execution profile:
 
-Strict mode means task size does not matter. Even if the request is "make a function that adds two numbers", explicit supervisor invocation still means the full workflow:
+- `lean_work_unit_runner`: for large, already-bounded work-unit backlogs where throughput and low memory matter.
+- `strict_full_workflow`: for ambiguous, high-risk, delegated, security-sensitive, source-of-truth, publication, or cross-system work.
+- `planning_only`: for intake, sequencing, risk review, and recommendations without implementation.
+
+Lean mode keeps work units but removes per-unit ceremony. It uses one upfront scope contract, one compact ledger, targeted checks, and strict escalation gates:
+
+```text
+select next ready unit
+-> inspect only needed sources
+-> patch or update the allowed surface
+-> run the targeted check
+-> update one ledger row
+-> continue until batch checkpoint, blocker, or final disposition
+```
+
+A lean unit is not ready unless it has:
+
+```yaml
+id:
+source_ref:
+scope:
+done:
+check:
+status:
+```
+
+Strict mode is still available when risk justifies it. In strict mode, task size does not matter. The full workflow is:
 
 1. Ask the complete intake packet.
 2. Build or record the source corpus.
-3. Create at least one work unit.
-4. Create acceptance rows.
-5. Create dossiers for the planned workers.
-6. Create a worker-agent plan.
-7. Ask for approval when the selected path is human-in-loop.
-8. Delegate scoped work to real workers when the environment supports it.
-9. Verify with evidence.
-10. Route repair work if verification fails.
-11. Refresh docs or outcome state.
-12. Report final status and next action.
-
-This rule exists to prevent the agent from deciding that a task is "too simple" and quietly skipping the supervisor.
+3. Create a source-requirement coverage ledger.
+4. Create a `SPEC.md` review packet or file.
+5. Pause for human Q&A, revisions, block, defer, or approval when the path is human-in-loop.
+6. Create at least one work unit.
+7. Create acceptance rows that preserve source-scope fidelity.
+8. Create dossiers for the planned workers.
+9. Create a worker-agent plan.
+10. Ask for approval when the selected path is human-in-loop.
+11. Delegate scoped work to real workers when the environment supports it.
+12. Verify with evidence.
+13. Route repair work if verification fails.
+14. Refresh docs or outcome state.
+15. Report final status and next action.
+
+Profile selection exists to prevent both failure modes: skipping supervision when work is risky, and drowning simple or already-bounded work in process.
 
 ## Intake
 
-The supervisor must get explicit answers to these seven items before planning deeply, creating a goal, delegating workers, implementing, publishing, or taking irreversible action:
+The supervisor must get explicit answers to these eight items before planning deeply, creating a goal, delegating workers, implementing, publishing, or taking irreversible action:
 
 ```text
 1. Objective and source: what artifact, spec, repo path, document, ticket, or source set controls the work?
-2. Execution path: autonomous_goal or human_in_loop?
-3. Mode: sequential, parallel where safe, or staged parallel?
-4. Delegation: automated worker delegation, native threads/subagents if available, or same-session phased?
-5. Final disposition: keep local, open PR, push main, deploy/publish, or ask at the end?
-6. Boundaries: may I install dependencies, call external services, use credentials, or only edit local files?
-7. State artifacts: create .workflow docs, use another artifact directory, or keep state inline?
+2. Profile: lean_work_unit_runner, strict_full_workflow, or planning_only?
+3. Execution path: autonomous_goal or human_in_loop?
+4. Mode: sequential, parallel where safe, or staged parallel?
+5. Delegation: same-session phased, automated worker delegation, or native threads/subagents if available?
+6. Final disposition: keep local, open PR, push main, deploy/publish, or ask at the end?
+7. Boundaries: may I install dependencies, call external services, use credentials, or only edit local files?
+8. State artifacts: compact ledger, .workflow docs, another artifact directory, or inline state?
 ```
 
 If any answer is missing or vague, the supervisor asks only for the missing pieces and stops. Phrases like "work autonomously", "just do it", or "use your judgment" do not fill in the missing intake fields.
 
 Expected human pauses are normal. A workflow can move from `WAITING_FOR_HUMAN` back to `ACTIVE` after the user approves a plan or answers a blocker question.
 
+In `autonomous_goal`, a human clarification pause is not automatically a terminal failed goal. The supervisor records the blocker, asks the smallest needed question, updates SPEC/Q&A/coverage state when the answer arrives, refreshes only affected downstream artifacts, and resumes from the recorded next action. If an old Codex goal was already terminal-blocked, the resumed workflow references it as history and continues from workflow state or a newly authorized goal binding.
+
 ## The Workflow
 
 The full loop looks like this:
@@ -130,6 +166,8 @@ The full loop looks like this:
 ```text
 complete intake
 -> source corpus
+-> source-requirement coverage ledger
+-> SPEC review and Q&A gate
 -> work units
 -> loop policy
 -> acceptance matrix
@@ -147,10 +185,16 @@ complete intake
 The worker lifecycle is tracked separately:
 
 ```text
-planned -> handed_off -> acknowledged -> reported -> verified -> closed
+planned -> handed_off -> acknowledged -> reported -> verified -> resource_closed -> closed
 ```
 
-This makes it possible to see where the workflow is, which worker owns which piece, what evidence exists, and what should happen next.
+This makes it possible to see where the workflow is, which worker owns which piece, what evidence exists, what native resource was opened, and whether that resource was closed. A native worker is not closed just because it returned a report.
+
+For source-of-truth builds, the coverage ledger is the guardrail against "green but incomplete" outcomes. Every material source requirement must be mapped to a work unit and acceptance row, explicitly deferred by the user, blocked as a scope decision, or marked non-material with a reason. Residual risks and future-work notes cannot contain unimplemented material source requirements in a PASS workflow.
+
+`SPEC.md` is the human review contract before final work units. In human-in-loop mode, the supervisor stops at the draft SPEC so the human can ask questions, request revisions, mark items deferred, block the workflow, or approve. The workflow continues only after explicit approval.
+
+When a workflow pauses for a human decision, the decision is recorded as state rather than treated as a restart. The next supervisor pass updates the affected coverage rows, SPEC fields, work units, acceptance rows, dossiers, or verification results, invalidates stale artifacts, and continues from the saved `Next Action`.
 
 ## Skills In The Pack
 
@@ -181,16 +225,17 @@ Common workflow files:
 |---|---|---|
 | `.workflow/WORKFLOW.md` | `workflow-supervisor`, `loop-policy`, `workflow-docs` | Main state, objective, execution path, policy, stop gates, next action. |
 | `.workflow/SOURCE-CORPUS.md` | `source-corpus`, `workflow-docs` | Source ranking, missing sources, contradictions, assumptions. |
+| `.workflow/SPEC.md` | `workflow-supervisor`, `source-corpus`, `workflow-docs` | Human-reviewable interpretation, requirement coverage, Q&A, and approval decision before work units. |
 | `.workflow/WORK-UNITS.md` | `work-unit`, `workflow-docs` | Unit list, dependencies, sequencing, blocked units. |
 | `.workflow/DOSSIER.md` or `.workflow/dossiers/*.yaml` | `dossier-builder`, `workflow-docs` | Worker contracts for implementation, verification, repair, or documentation. |
-| `.workflow/WORKER-MAP.md` | `workflow-supervisor`, `worker-roles`, `workflow-docs` | Worker names, roles, transports, lifecycle, reports, blockers. |
+| `.workflow/WORKER-MAP.md` | `workflow-supervisor`, `worker-roles`, `workflow-docs` | Worker names, roles, transports, native resource ids, lifecycle, reports, close results, blockers. |
 | `.workflow/ACCEPTANCE-MATRIX.md` | `acceptance-matrix`, `workflow-docs` | Evidence rows and material PASS, FAIL, BLOCKED states. |
 | `.workflow/VERIFICATION-REPORT.md` | verifier worker, `acceptance-matrix`, `workflow-docs` | Verification evidence, findings, skipped checks, residual risks. |
 | `.workflow/REPAIR-TICKETS.md` | repair worker, `workflow-docs` | Repair tasks tied to failed rows or verifier findings. |
 | `.workflow/DECISIONS.md` | supervisor, `workflow-docs` | User decisions, assumptions, reversals, unresolved questions. |
 | `.workflow/HANDOFF.md` | supervisor, `workflow-docs` | Resume pack for another agent or later session. |
 | `.workflow/OUTCOME.md` | supervisor, documenter worker, `workflow-docs` | Final status, checks, risks, disposition, next action. |
-| `.workflow/GOAL-STATE.md` | supervisor, `workflow-docs` | Codex goal mirror when goal state needs durable backup. |
+| `.workflow/GOAL-STATE.md` | supervisor, `workflow-docs` | Codex goal mirror, blocked-goal history, human-decision resume checkpoint, and durable backup. |
 
 For documentation-heavy workflows, `workflow-docs` can also create:
 
@@ -297,9 +342,11 @@ Every delegated worker returns this machine-shaped report:
 
 The supervisor trusts the report shape, not loose prose. A PASS without evidence is invalid. A verifier that edits implementation is invalid. A worker that asks the human directly is converted into a blocker for the supervisor to route.
 
+For native threads or subagents, the report is only the work result. The supervisor must also close the native resource. For Codex subagents, record the returned `agent_id` and call `close_agent` after the report, timeout, failure, blocker, cancellation, or invalid-output result is captured. Final outcome is blocked while any native worker lacks a close result.
+
 ## How The Supervisor Talks To Workers
 
-The portable worker path is one CLI command:
+The portable worker path is one CLI command and is preferred when it satisfies the work because it is one-shot:
 
 ```bash
 workflow-supervisor delegate \
@@ -335,9 +382,11 @@ workflow-supervisor delegate-doctor --agent all --probe --require-pass
 
 If a worker adapter is missing, unauthenticated, times out, returns invalid output, edits forbidden surfaces, or returns PASS without evidence, the delegate command returns a structured `BLOCKED` report.
 
+Native thread or subagent transports may be used only when the environment exposes the full lifecycle: create, wait or receive a terminal report, and close. If a native transport can start workers but cannot close them, the supervisor records `worker_resource_close_unavailable` and uses portable delegation or same-session phased work only when intake allows it.
+
 ## No Silent Fallbacks
 
-If the environment can create, message, or delegate to worker agents, the supervisor must use real workers for implementation, verification, repair, and documentation responsibilities.
+In `strict_full_workflow` with worker delegation selected, if the environment can create, message, or delegate to worker agents, the supervisor must use real workers for implementation, verification, repair, and documentation responsibilities.
 
 If it cannot, it must record:
 
@@ -347,7 +396,7 @@ worker_agent_unavailable
 
 Then it must stop for a human decision unless complete intake explicitly selected `same_session_phased`.
 
-Same-session phased work is allowed only when selected. Verification in that mode is a `self-check`, not an `independent-verifier`.
+In `lean_work_unit_runner`, same-session phased execution is the default unless the user explicitly authorizes workers for a batch or escalation. Verification in same-session mode is a `focused-check` or `self-check`, not an `independent-verifier`.
 
 ## Install
 
@@ -410,10 +459,12 @@ You should expect:
 1. The supervisor asks the complete intake packet.
 2. You answer every intake item.
 3. If the path is `human_in_loop`, the supervisor gives you an approval packet before implementation.
-4. The supervisor creates work units, acceptance rows, and dossiers.
-5. The supervisor delegates scoped work to workers when supported.
-6. Workers return structured reports.
-7. The supervisor verifies, routes repairs if needed, and gives you the final result.
+4. The supervisor creates the source-requirement coverage ledger and `SPEC.md`.
+5. You ask questions, request revisions, block, defer, or approve the SPEC.
+6. After approval, the supervisor creates work units, acceptance rows, and dossiers.
+7. The supervisor delegates scoped work to workers when supported.
+8. Workers return structured reports.
+9. The supervisor verifies, routes repairs if needed, and gives you the final result.
 
 If you only want a normal quick edit, do not invoke `$workflow-supervisor`.
 
@@ -520,11 +571,11 @@ If you are an agent using this package:
 
 1. Do not start work before complete intake.
 2. Do not infer missing permissions from words like "autonomous", "generate", or "work until done".
-3. If `$workflow-supervisor` is explicit, always create at least one work unit.
-4. Do not delegate without a valid `DossierV1`.
-5. Use separate worker agents when supported by the environment.
-6. Do not silently collapse worker agents into same-session roleplay.
-7. Treat same-session verification as `self-check`, not `independent-verifier`.
+3. If `$workflow-supervisor` is explicit, select `lean_work_unit_runner`, `strict_full_workflow`, or `planning_only` before heavy planning.
+4. Always keep work units explicit; lean mode uses a compact ledger instead of full per-unit ceremony.
+5. Do not delegate without a valid `DossierV1`.
+6. Use separate worker agents in strict or explicitly delegated work, not by default for lean execution.
+7. Treat same-session verification as `focused-check` or `self-check`, not `independent-verifier`.
 8. Trust only structured `WorkerReportV1` results from delegated workers.
 9. Treat verifier edits as invalid.
 10. Keep `.workflow/` ignored and local unless the user explicitly asks to publish it.

package/bin/workflow-skills.mjs

@@ -8,8 +8,9 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
-const PACKAGE_NAME = "workflow-supervisor";
-const PACKAGE_VERSION = "0.1.1";
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+const PACKAGE_NAME = packageJson.name || "workflow-supervisor";
+const PACKAGE_VERSION = packageJson.version;
 const WORKER_REPORT_SCHEMA_PATH = path.join(packageRoot, "schemas", "worker-report-v1.schema.json");
 const DOSSIER_SCHEMA_PATH = path.join(packageRoot, "schemas", "dossier-v1.schema.json");
 const ADAPTERS_ROOT = path.join(packageRoot, "adapters");

package/docs/artifacts.md

@@ -8,6 +8,7 @@ In Git-backed codebases, `.workflow/` is local working state. Ensure `<workspace
 
 ## Workflow Control
 
+- `.workflow/LEDGER.md`
 - `.workflow/WORKFLOW.md`
 - `.workflow/SOURCE-CORPUS.md`
 - `.workflow/WORK-UNITS.md`
@@ -40,3 +41,7 @@ In Git-backed codebases, `.workflow/` is local working state. Ensure `<workspace
 ## State Medium
 
 Markdown is the default, but state may also be an inline brief, spreadsheet tab, ticket set, design annotation, CRM note, runbook, decision log, slide appendix, whiteboard note, or chat continuation note.
+
+For `lean_work_unit_runner`, prefer one compact ledger over multiple workflow documents. Each executable row should carry `id`, `source_ref`, `scope`, `done`, `check`, `status`, touched surfaces, and blockers. Escalated units may link to strict-mode SPEC, dossier, or verification artifacts only when needed.
+
+For native thread or subagent delegation, `WORKER-MAP.md` must record the native resource id, terminal report, close action, and close result. Do not mark a native worker closed until the resource close is recorded.

package/docs/portable-delegation.md

@@ -18,6 +18,10 @@ complete intake
 -> final supervisor report
 ```
 
+This document describes strict or explicitly delegated execution. `lean_work_unit_runner` normally stays in same-session phased execution with a compact ledger and targeted checks. It should enter portable delegation only when the user authorizes workers for a batch or a unit hits a strict-mode escalation trigger.
+
+Prefer portable delegation over native threads or subagents when it satisfies the work. Portable delegation is one-shot, so the worker process exits after the report. Native thread or subagent transports are allowed only when the supervisor can record the native resource id and call the matching close operation after terminal report, timeout, blocker, cancellation, or invalid output.
+
 The supervisor remains the only coordinator. Workers do not ask the human questions, choose final disposition, expand scope, approve plans, or talk to each other. If a worker needs a decision, it returns `BLOCKED` with a `blocking_question`; only the supervisor asks the user.
 
 ## Non-Goals
@@ -163,6 +167,7 @@ For git workspaces, the surface guard compares pre/post git status. Mutable role
 | Repair expands scope | Reject unless the repair dossier explicitly allowed the new surfaces and criteria. |
 | Units touch same surfaces | Run sequentially. Parallel delegation requires proven disjoint mutable surfaces. |
 | Platform has no native subagents | Fine. Each role is a fresh one-shot CLI process. |
+| Native subagent close is unavailable | Do not spawn it. Return `worker_resource_close_unavailable` and use portable delegation or same-session phased work only if intake allowed it. |
 | Platform output differs | Platform output is not the contract. `WorkerReportV1` is the only supervisor input. |
 | Platform cannot support a role safely | Adapter role is unsupported. Supervisor chooses another certified adapter or blocks. |
 | Full support is claimed but one CLI is absent | `delegate-doctor --agent all --probe --require-pass` exits nonzero and names the missing adapter. |

package/docs/skill-reference.md

@@ -2,7 +2,7 @@
 
 ## `workflow-supervisor`
 
-Coordinate explicit supervised or agent-loop workflows. It always starts with a complete intake gate before planning, implementation, goal binding, worker delegation, or final disposition. The user must answer every intake item; the supervisor must not infer or skip steps from keywords. After complete intake, it selects either autonomous goal execution or human-in-the-loop execution, then orchestrates named workers from dossiers through the portable delegate command or an approved native adapter. Loading the skill itself does not spawn workers. It binds Codex goals only after complete intake and when the user or environment authorizes goal-oriented work, checks active goal state first, and avoids unrelated active-goal collisions.
+Coordinate explicit supervised or agent-loop workflows with profile-based overhead. It starts by selecting `lean_work_unit_runner`, `strict_full_workflow`, or `planning_only`, then completes the intake needed for that profile before implementation, goal binding, worker delegation, or final disposition. The user must answer required intake items; the supervisor must not infer path, mode, delegation, final disposition, or boundaries from vague keywords. Lean mode is for large already-bounded work-unit backlogs: it keeps a compact ledger with unit id, source reference, scope, done signal, check, status, touched surfaces, and blockers, then executes one ready unit at a time with targeted checks and escalation gates. Strict mode creates a source-requirement coverage ledger and SPEC review gate before work units so controlling-source deliverables, roadmap phases, and exit criteria are either implemented, explicitly deferred, blocked, or marked non-material. In human-in-loop mode, the human can ask questions, request revisions, block, defer, or approve before execution. In autonomous goal mode, human clarification pauses resume from recorded workflow state after the answer updates only affected downstream artifacts. Strict mode can orchestrate named workers from dossiers through the portable delegate command or an approved native adapter. Native threads and subagents require a recorded native resource id plus a close result, such as `close_agent` for Codex subagents, before a worker is `closed`. Loading the skill itself does not spawn workers. It binds Codex goals only after complete intake and when the user or environment authorizes goal-oriented work, checks active goal state first, avoids unrelated active-goal collisions, and treats terminal blocked goals as history when resuming through workflow docs.
 
 ## `source-corpus`
 
@@ -10,7 +10,7 @@ Rank and reconcile sources when authority, freshness, contradictions, access rig
 
 ## `work-unit`
 
-Split broad work into bounded units with objective, scope, dependencies, readiness, done criteria, verification, sequencing, and parallel-safety notes.
+Split broad work into bounded units with objective, scope, dependencies, readiness, done criteria, verification, sequencing, and parallel-safety notes. It prevents broad roadmap or source-of-truth requests from collapsing into one giant unit unless all current-scope material requirements can be implemented and verified in that unit.
 
 ## `dossier-builder`
 
@@ -22,12 +22,12 @@ Define role contracts and solo-mode phase separation. It prevents role bleed: ve
 
 ## `acceptance-matrix`
 
-Create formal evidence-mapped acceptance rows for high-risk, supervised, ambiguous, resumable, or delegated workflows.
+Create formal evidence-mapped acceptance rows for high-risk, supervised, ambiguous, resumable, or delegated workflows. Rows must preserve source requirement strength, including named systems, quantities, live integration language, and exit criteria; weaker proxy checks require explicit user waiver or scope narrowing.
 
 ## `loop-policy`
 
-Define execution path, execution mode, worker delegation, approval gates, repair limits, parallel safety, no-progress rules, and Codex goal tool policy.
+Define execution path, execution mode, worker delegation, approval gates, repair limits, parallel safety, no-progress rules, human-decision resume rules, and Codex goal tool policy.
 
 ## `workflow-docs`
 
-Create durable workflow-state or documentation-production artifacts. Markdown artifacts default to `<workspace>/.workflow/` unless the user or project convention says otherwise. It also supports inline briefs, tickets, design annotations, runbooks, decision logs, and other usable state media.
+Create durable workflow-state or documentation-production artifacts. Markdown artifacts default to `<workspace>/.workflow/` unless the user or project convention says otherwise. It includes `SPEC.md` for human-readable interpretation, Q&A, and approval before work units, plus `GOAL-STATE.md` and resume fields for blocked-goal history and human-decision continuation. It also supports inline briefs, tickets, design annotations, runbooks, decision logs, and other usable state media.

package/docs/troubleshooting.md

@@ -23,10 +23,36 @@ Use `.workflow/GOAL-STATE.md` or a workflow continuation document. The superviso
 
 Use `$workflow-docs` with a minimal artifact request. The skill must reject "create every document just in case."
 
+## Large backlogs run slowly or exhaust memory
+
+Use `lean_work_unit_runner` instead of `strict_full_workflow` when the source already contains clear work units and the user's priority is throughput. Keep one compact ledger with `id`, `source_ref`, `scope`, `done`, `check`, `status`, touched surfaces, and blockers. Run one unit at a time by default, avoid subagents unless explicitly authorized, avoid broad scans unless required for the current unit, and checkpoint by batch rather than rewriting full workflow docs after every unit.
+
+Do not remove work units to make the process lean. If a unit cannot name its boundary, done signal, or targeted check, mark it `blocked` or escalate that unit to strict mode.
+
+## Native subagents remain open after completion
+
+Treat this as a lifecycle bug, not a cosmetic cleanup task. A terminal report or completed notification does not close a native Codex subagent. Record every native worker id in `WORKER-MAP.md`, call the native close action such as `close_agent` after the terminal report or blocker is captured, and block the final outcome if any native worker lacks a close result. Prefer one-shot portable delegation when it satisfies the work.
+
 ## Verification rubber-stamps the result
 
 Use `$acceptance-matrix` for formal evidence rows. A PASS requires row-by-row evidence or explicit waiver evidence.
 
+## A broad roadmap becomes one giant work unit
+
+Use the source-requirement coverage gate before work-unit finalization. Every material roadmap item, exit criterion, named integration, and numeric target should be mapped to a unit and acceptance row, explicitly deferred by the user, blocked for a decision, or marked non-material with a reason. Do not accept "future work" or residual risk notes as a substitute for work units.
+
+## Residual risks contain required work
+
+Treat this as FAIL or BLOCKED. Residual risks may describe remaining uncertainty after acceptance, but they must not contain unimplemented material source requirements, skipped mandatory checks, or source-of-truth deliverables that were quietly downgraded.
+
+## Humans need to review scope before work units
+
+Create or refresh `.workflow/SPEC.md` before final work units. The human can ask questions in the Q&A section, request revision, block the workflow, defer items, or approve. In `human_in_loop`, the supervisor must not continue to final work units, dossiers, or implementation until the SPEC decision is approved and Q&A is answered.
+
+## Autonomous workflow paused for a human decision
+
+Record the blocker before asking the human. When the answer arrives, update `.workflow/SPEC.md`, `.workflow/WORKFLOW.md`, `.workflow/GOAL-STATE.md`, and `DECISIONS.md` when present. Re-run only the affected coverage, SPEC, work-unit, acceptance, dossier, worker-plan, verification, or final-disposition steps. Do not restart complete intake unless the answer changes a required intake decision. If the old Codex goal is terminal blocked, reference it as history and continue from workflow state or a newly authorized goal binding.
+
 ## An existing skill folder blocks install
 
 Use:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow-supervisor",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Portable workflow supervision skills for Codex, Claude Code, and generic agent workspaces.",
   "type": "module",
   "repository": {
@@ -19,9 +19,15 @@
     "skills",
     "adapters",
     "schemas",
-    "docs",
+    "docs/artifacts.md",
+    "docs/cli.md",
+    "docs/compatibility.md",
+    "docs/portable-delegation.md",
+    "docs/skill-reference.md",
+    "docs/troubleshooting.md",
     "assets",
     "bin",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],

package/skills/acceptance-matrix/SKILL.md

@@ -15,15 +15,39 @@ This skill owns evidence rows and supervisor verdict mapping. `$work-unit` may d
 
 - Every requirement needs evidence.
 - Evidence must name a source, command, artifact, UI state, test, inspection, or user decision.
+- Acceptance rows must preserve the source requirement's strength: named systems, quantities, live/integration wording, exit criteria, and "must" language.
+- A weaker proxy check is not equivalent evidence unless the user explicitly waives or narrows the original requirement.
 - PASS requires all material rows to be satisfied or explicitly waived by the user.
 - FAIL requires at least one material row with unmet evidence.
 - BLOCKED applies when evidence cannot be obtained or sources conflict.
 - Residual risks must not be hidden inside PASS.
+- If residual risks, skipped checks, future work, or next recommended actions contain an unimplemented material source requirement, the matrix status is FAIL or BLOCKED, not PASS.
+
+## Source Fidelity Rules
+
+When a source-requirement coverage ledger exists, every `in_current_scope` material requirement needs at least one matrix row. Preserve exact source details that affect scope or verification, including:
+
+- named integrations or providers
+- corpus sizes, question counts, coverage thresholds, or latency/cost budgets
+- "live" versus artifact-only behavior
+- required data sources, credentials, services, or indexes
+- roadmap phase exit criteria
+- mandatory checks, screenshots, reports, or review states
+
+Do not downgrade requirements while making them testable. Examples of invalid substitutions:
+
+- live service load/query verification -> generated export file only
+- required validation corpus size -> small starter fixture
+- named provider support -> generic extension hook
+- required analysis and report generation -> keyword metadata only
+- provider-backed extraction or indexing -> deterministic placeholder logic
+
+If a requirement cannot be verified in the current environment, mark it BLOCKED or require a user waiver. Do not convert it into an easier row.
 
 ## Row Shape
 
-| ID | Requirement | Evidence Required | Verification Method | Adversarial Check | Status | Evidence |
-|---|---|---|---|---|---|---|
+| ID | Source Ref | Requirement | Evidence Required | Verification Method | Adversarial Check | Status | Evidence |
+|---|---|---|---|---|---|---|---|
 
 Use statuses: Pending, PASS, FAIL, BLOCKED, Waived.
 
@@ -46,6 +70,9 @@ Consider:
 - missing citation or unsupported claim
 - document structure regression
 - stakeholder requirement omitted
+- source requirement weakened or omitted
+- roadmap exit criteria demoted to future work
+- material requirement hidden in residual risks
 - artifact cannot be reused by a fresh agent or human
 
 ## Verification Report Shape