workflow-supervisor 0.1.1 → 0.1.3

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/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. 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 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 the SPEC before final work units. In autonomous goal mode, human clarification pauses resume from recorded workflow state after the answer updates Q&A, decisions, coverage, and affected downstream artifacts. It then 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, 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

@@ -27,6 +27,22 @@ Use `$workflow-docs` with a minimal artifact request. The skill must reject "cre
 
 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.1",
+  "version": "0.1.3",
   "description": "Portable workflow supervision skills for Codex, Claude Code, and generic agent workspaces.",
   "type": "module",
   "repository": {

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

package/skills/loop-policy/SKILL.md

@@ -21,7 +21,8 @@ For loop-oriented supervisor work, define how the workflow uses Codex goals afte
 - goal_state_mirror_cadence: each work unit, each verification result, each repair loop, and final outcome
 - goal_completion_rule: evidence required before completion
 - goal_blocked_rule: same material blocker across the required consecutive goal turns and no meaningful progress
-- goal_resume_rule: read active goal before workflow docs, then reconcile
+- goal_resume_rule: read active goal before workflow docs, reconcile state, and continue from the recorded next action after human decisions
+- human_decision_resume_rule: ask the smallest blocking decision, update state, invalidate only affected downstream artifacts, and resume without restarting intake unless intake changed
 
 Do not create goals for small direct tasks. A goal is the state container for open-ended loops, not a wrapper around every command.
 
@@ -36,7 +37,7 @@ Do not create goals for small direct tasks. A goal is the state container for op
 - Budget: time, token, command, cost, or file-change limits.
 - Escalation: when to ask the user, delegate to a specialist worker, or stop.
 - Completion: evidence required before marking done.
-- Resume: artifacts needed before pausing or compacting.
+- Resume: artifacts needed before pausing, compacting, or waiting for a human decision.
 - Mutation conflict: whether units touch the same mutable surfaces or decisions.
 
 ## Default Policy
@@ -63,6 +64,7 @@ workflow_unit_blocked_after: first material blocker may stop the unit while the
 codex_goal_blocked_after: same material blocker across 3 consecutive goal turns and no meaningful progress
 completion_requires: acceptance evidence plus residual risk report
 resume_requires: workflow state or outcome doc for long workflows
+human_decision_resume_rule: record blocker and next action before asking; after answer, update Q&A/decision/coverage state, re-run only affected downstream steps, invalidate stale artifacts, and continue from recorded next action
 missing_prerequisites: discovery-first, not failure
 goal_start: after complete intake only; create only when completed intake and environment authorize goal binding, otherwise mirror state in docs
 goal_state_mirror_cadence: after unit terminal states and final outcome
@@ -98,6 +100,7 @@ escalation_rules:
 stop_gates:
 completion_rule:
 resume_artifacts:
+human_decision_resume_rule:
 goal_policy:
 final_disposition_policy:
 ```

package/skills/work-unit/SKILL.md

@@ -43,6 +43,23 @@ Work-unit drafts coarse done criteria only. Use `$acceptance-matrix` when those
 
 For over-broad one-pass requests, produce a sequencing recommendation and invoke or mirror `$loop-policy` fields for mode, parallel safety, approval gates, and repair limits.
 
+## One-Pass Collapse Guard
+
+Do not collapse a multi-phase roadmap, spec, or "source of truth" corpus into one broad implementation unit unless every material requirement can be completed and verified inside that unit. If the source contains phases, exit criteria, named integrations, scale targets, or different risk classes, split them into independently verifiable units.
+
+Treat these as separate-unit signals:
+
+- roadmap phases or milestones
+- multiple external data sources, providers, services, or credentials
+- live system integration plus local artifact fallback
+- extraction/indexing/retrieval/evaluation/reporting layers with different evidence needs
+- numeric targets such as corpus size, eval question count, latency budget, or coverage threshold
+- implementation work that would otherwise be described as residual risk, future work, or next recommended action
+
+If a supervisor provides a source-requirement coverage ledger, every `in_current_scope` material requirement must appear in at least one work unit's done criteria. Every `explicit_user_deferred`, `blocked_needs_decision`, or `out_of_scope_by_user` item must remain visible in `blocked_units` or a separate deferral list; do not hide it inside a unit note.
+
+Create exactly one `WU-001` only when the task is genuinely tiny or the full current-scope ledger can be implemented, verified, and documented as one bounded unit without deferred material requirements.
+
 ## Output Shape
 
 ```yaml
@@ -60,10 +77,12 @@ units:
     forbidden_surfaces:
     readiness:
     done_criteria:
+    source_requirements_covered:
     verification:
     sequence:
 parallel_groups:
 blocked_units:
+deferred_or_out_of_scope_requirements:
 first_recommended_unit:
 ```
 

package/skills/workflow-docs/SKILL.md

@@ -62,6 +62,7 @@ For documentation work, start with `DOCUMENTATION-BRIEF.md` unless the user prov
 
 - `.workflow/WORKFLOW.md`: overall objective, policy, state, units, and next action.
 - `.workflow/SOURCE-CORPUS.md`: source map, authority ranking, contradictions, gaps.
+- `.workflow/SPEC.md`: human-reviewable interpretation contract, requirement coverage, Q&A, and approval decision before final work units.
 - `.workflow/WORK-UNITS.md`: decomposition and sequencing.
 - `.workflow/DOSSIER.md`: delegation contract for one unit.
 - `.workflow/WORKER-MAP.md`: worker names, roles, transports, dossiers, dependencies, start conditions, report status, and supervisor checkpoints.
@@ -71,7 +72,7 @@ For documentation work, start with `DOCUMENTATION-BRIEF.md` unless the user prov
 - `.workflow/DECISIONS.md`: durable decisions, assumptions, and reversals.
 - `.workflow/HANDOFF.md`: resume state for another agent or session.
 - `.workflow/OUTCOME.md`: final status, checks, risks, and next step.
-- `.workflow/GOAL-STATE.md`: optional fallback record when a Codex goal tool is unavailable or goal state must be mirrored for continuation.
+- `.workflow/GOAL-STATE.md`: optional fallback or mirror for Codex goal state, terminal blocked-goal history, and human-decision resume checkpoints.
 - `.workflow/DOCUMENTATION-BRIEF.md`: audience, purpose, document type, reader task, channel, owner, approvers, and success criteria.
 - `.workflow/CONTENT-INVENTORY.md`: existing materials, reusable sections, gaps, stale areas, and owners.
 - `.workflow/OUTLINE.md`: information architecture, section hierarchy, and required content.

package/skills/workflow-docs/references/goal-resume.md

@@ -12,19 +12,28 @@ In Git-backed codebases, ensure `<workspace>/.gitignore` contains `.workflow/` b
 ## Goal Binding
 
 - Goal Binding: created | reused | skipped | unavailable | conflict
-- Goal Status: active | complete | blocked | unknown
+- Goal Status: active | complete | blocked | blocked old | unknown
 - Last Goal Tool Action: get_goal | create_goal | update_goal | none
 - Next Allowed Goal Action:
 - Goal Objective:
+- Previous Blocked Goal Reference:
+- Human Decision Needed:
+- Human Decision Answer:
+- Resume From:
+- Artifacts To Refresh:
+- Stale Artifacts Invalidated:
 ```
 
 ## Goal-Aware OUTCOME.md Fields
 
 ```md
 Goal Binding: created | reused | skipped | unavailable | conflict
-Goal Status: active | complete | blocked | unknown
+Goal Status: active | complete | blocked | blocked old | unknown
 Last Goal Tool Action: get_goal | create_goal | update_goal | none
 Next Allowed Goal Action:
+Previous Blocked Goal Reference:
+Resume From:
+Human Decision Resume Status:
 ```
 
 ## GOAL-STATE.md
@@ -40,10 +49,18 @@ created | reused | skipped | unavailable | conflict
 
 ## Goal Status
 
-active | complete | blocked | unknown
+active | complete | blocked | blocked old | unknown
 
 ## Why A Goal Was Created Or Skipped
 
+## Previous Blocked Goal
+
+Goal Reference:
+
+Reason:
+
+Use As History Only: yes | no
+
 ## Active Goal Conflict
 
 ## Last Tool Action
@@ -56,9 +73,37 @@ get_goal | create_goal | update_goal | none
 
 ## Current Work Unit
 
+## Current Blocker
+
+## Human Decision Needed
+
+Question:
+
+Smallest Sufficient Answer:
+
+## Human Decision Answer
+
+Answer:
+
+Decision Type: clarification | scope change | requirement waiver | explicit deferral | blocker resolution | final disposition | intake change | workflow cancellation
+
+## Resume Checkpoint
+
+Last Completed Step:
+
+Next Action:
+
+Artifacts To Refresh:
+
+Stale Artifacts Invalidated:
+
 ## Completion Rule
 
 ## Blocked Rule
 
 ## Resume Instructions
 ```
+
+## Human Decision Resume Rule
+
+When a workflow pauses for a human answer, record the blocker before asking. After the answer arrives, update the decision log, SPEC Q&A, coverage dispositions, and goal mirror before continuing. Resume from the recorded next action and re-run only affected downstream steps. Do not restart complete intake unless the answer changes a required intake decision. If the previous Codex goal is terminal blocked and cannot be reopened, keep that goal reference as history and continue with workflow docs or a newly authorized goal binding.

package/skills/workflow-docs/references/templates.md

@@ -34,6 +34,7 @@ Includes:
 
 - `WORKFLOW.md`
 - `SOURCE-CORPUS.md`
+- `SPEC.md`
 - `WORK-UNITS.md`
 - `DOSSIER.md`
 - `WORKER-MAP.md`
@@ -42,6 +43,7 @@ Includes:
 - `REPAIR-TICKETS.md`
 - `DECISIONS.md`
 - `HANDOFF.md`
+- `GOAL-STATE.md`
 - `OUTCOME.md`
 
 ## Goal And Resume

package/skills/workflow-docs/references/workflow-control.md

@@ -38,6 +38,21 @@ Git rule: in a Git-backed codebase, ensure `<workspace>/.gitignore` contains `.w
 
 ## Stop Gates
 
+## Blocking Decision
+
+| ID | Blocked Artifact | Question | Affected Requirements | Affected Work Units | Status | Answer Source |
+|---|---|---|---|---|---|---|
+
+## Resume Checkpoint
+
+Last Completed Step:
+
+Next Action:
+
+Artifacts To Refresh:
+
+Stale Artifacts Invalidated:
+
 ## Next Action
 ```
 
@@ -65,6 +80,80 @@ Git rule: in a Git-backed codebase, ensure `<workspace>/.gitignore` contains `.w
 ## Allowed Next Action
 ```
 
+## SPEC.md
+
+```md
+# SPEC
+
+Status: Draft | Approved | Needs Revision | Blocked
+
+## Objective
+
+## Source Of Truth
+
+| Source | Role | Notes |
+|---|---|---|
+
+## Interpreted Scope
+
+## Non-Goals
+
+## Requirement Coverage
+
+| ID | Source Ref | Requirement | Proposed Disposition | Final Disposition | Decision Source | Work Unit | Acceptance Row |
+|---|---|---|---|---|---|---|---|
+
+## Deferred, Out-Of-Scope, Or Blocked Items
+
+| ID | Requirement | Status | Reason | Needed Decision |
+|---|---|---|---|---|
+
+## Proposed Work Units
+
+| Work Unit | Objective | Depends On | Verification |
+|---|---|---|---|
+
+## Acceptance Summary
+
+## Assumptions And Risks
+
+## Open Questions
+
+| ID | Question | Asked By | Answer | Status |
+|---|---|---|---|---|
+
+## Q&A Log
+
+| ID | Question | Answer | Spec Change Required | Status |
+|---|---|---|---|---|
+
+## Resume Checkpoint
+
+Blocked At:
+
+Required Human Decision:
+
+Affected Requirement IDs:
+
+Affected Work Units:
+
+Next Action After Answer:
+
+Artifacts To Refresh:
+
+Stale Artifacts Invalidated:
+
+## Human Verification
+
+Reviewer:
+
+Decision: Approved | Needs Revision | Blocked
+
+Decision Source:
+
+Notes:
+```
+
 ## WORK-UNITS.md
 
 ```md
@@ -249,6 +338,66 @@ Acceptance Criteria:
 ## Next Recommended Action
 ```
 
+## GOAL-STATE.md
+
+```md
+# Goal State
+
+## Objective
+
+## Goal Binding
+
+created | reused | skipped | unavailable | conflict
+
+## Goal Status
+
+active | complete | blocked | blocked old | unknown
+
+## Previous Blocked Goal
+
+Goal Reference:
+
+Reason:
+
+Use As History Only: yes | no
+
+## Last Tool Action
+
+get_goal | create_goal | update_goal | none
+
+## Next Allowed Goal Action
+
+## Last Completed Step
+
+## Current Work Unit
+
+## Current Blocker
+
+## Human Decision Needed
+
+Question:
+
+Smallest Sufficient Answer:
+
+## Human Decision Answer
+
+Answer:
+
+Decision Type: clarification | scope change | requirement waiver | explicit deferral | blocker resolution | final disposition | intake change | workflow cancellation
+
+## Resume Checkpoint
+
+Next Action:
+
+Artifacts To Refresh:
+
+Stale Artifacts Invalidated:
+
+## Completion Rule
+
+## Blocked Rule
+```
+
 ## OUTCOME.md
 
 ```md