workflow-supervisor 0.1.2 → 0.1.4

package/skills/loop-policy/SKILL.md

@@ -21,22 +21,24 @@ 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.
 
 ## Policy Dimensions
 
+- Profile: `lean_work_unit_runner`, `strict_full_workflow`, or `planning_only`; choose before heavy artifacts, goals, workers, or implementation.
 - Intake: whether every required intake decision has an explicit user answer, and which unanswered items must be re-asked before any work can start.
 - Execution path: autonomous_goal or human_in_loop, from completed intake only.
 - Mode: sequential, parallel, staged parallel, or discovery-first, from completed intake only.
 - Approval: none, before worker delegation, before implementation, before verification, before repair, before publication, before irreversible action, before each unit, or path-gated.
-- Delegation orchestration: selected transport, adapter availability, naming scheme, start timing, supervisor checkpoint cadence, terminal report collection, and stop behavior when automated delegation is unavailable.
+- Delegation orchestration: selected transport, adapter availability, naming scheme, start timing, supervisor checkpoint cadence, terminal report collection, native resource close behavior, and stop behavior when automated delegation is unavailable.
 - Repair limit: maximum repair loops per unit.
 - 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
@@ -44,25 +46,38 @@ Do not create goals for small direct tasks. A goal is the state container for op
 Use this default unless the task says otherwise:
 
 ```yaml
+profile_selection: before goal creation, heavy planning, worker delegation, implementation, verification, repair, final disposition, publication, or irreversible action
+profiles:
+  lean_work_unit_runner: large bounded backlog, pure work units, low-footprint direct execution, compact ledger, no default subagents
+  strict_full_workflow: ambiguous, high-risk, delegated, source-of-truth, security, external-service, publication, or broad interpretation work
+  planning_only: intake, scope review, sequencing, risks, and recommendations without implementation
 intake_required_when: every supervisor invocation before goal creation, planning beyond intake, worker delegation, implementation, verification, repair, final disposition, publication, or irreversible action
 intake_question_count: ask the complete intake packet first; on follow-up ask every unanswered or ambiguous item
-required_intake_decisions: objective_and_source, execution_path, mode, delegation, final_disposition, mutation_boundaries, state_artifacts
+required_intake_decisions: objective_and_source, profile, execution_path, mode, delegation, final_disposition, mutation_boundaries, state_artifacts
 use_judgment_defaults: none; user must answer every required intake decision explicitly
-keyword_shortcuts: forbidden; do not infer path, mode, delegation, final disposition, or boundaries from prompt keywords
+keyword_shortcuts: forbidden for path, mode, delegation, final disposition, and boundaries; profile may be selected only from explicit user intent plus controlling source
 mode: from completed intake only
 execution_path: from completed intake only
 approval_gate: path-gated; complete intake before any path-specific plan; human approval for human_in_loop plans; explicit completed-intake authorization for autonomous_goal; explicit completed-intake authorization for irreversible or user-visible publication
 repair_limit_per_unit: 2
 parallel_allowed_when: units do not share mutable surfaces
-worker_delegation_rule: after complete intake, path gate, concrete dossier, and supported automated transport
-native_transport_rule: after complete intake, path gate, and concrete dossier when the environment exposes approved thread or subagent tools
+worker_delegation_rule: strict mode after complete intake, path gate, concrete dossier, supported automated transport, and supported resource close; lean mode only after explicit authorization or escalation trigger
+native_transport_rule: after complete intake, path gate, concrete dossier, and confirmed close operation when the environment exposes approved thread or subagent tools
 worker_name_template: wf/<workflow-slug>/<unit-id>-<role>-<dossier-slug>
-supervisor_checkpoint_cadence: after worker start, terminal report, repair ticket creation, re-verification, and final disposition
+supervisor_checkpoint_cadence: after worker start, native resource id capture, terminal report, native resource close, repair ticket creation, re-verification, and final disposition
+native_worker_lifecycle:
+  required_fields: worker_name, transport, native_resource_id, status, terminal_report, close_action, close_result
+  codex_close_action: close_agent
+  final_outcome_gate: blocked if any native worker lacks close_result
+lean_checkpoint_cadence: after each unit ledger update, at user-selected batch size, on blocker, on risk escalation, and final outcome
+lean_unit_readiness: id, source_ref, scope, done, check, status
+lean_resource_gates: no unapproved subagents, no broad scans unless needed for current unit, one active unit by default, stop or ask when memory/process churn threatens throughput
 final_disposition_policy: from completed intake only; if set to ask_at_end, stop and ask at final disposition
 workflow_unit_blocked_after: first material blocker may stop the unit while the Codex goal remains active
 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
@@ -86,11 +101,21 @@ Do not run units in parallel when they edit the same files, documents, datasets,
 
 ```yaml
 workflow:
+profile:
 intake:
 execution_path:
 mode:
 approval_gates:
 delegation_policy:
+native_worker_lifecycle:
+  required_close_action:
+  open_native_workers:
+lean_policy:
+  ledger:
+  unit_readiness:
+  batch_checkpoint:
+  focused_check:
+  escalation_triggers:
 repair_limit:
 parallel_rules:
 budgets:
@@ -98,6 +123,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

@@ -61,17 +61,19 @@ For documentation work, start with `DOCUMENTATION-BRIEF.md` unless the user prov
 ## Artifact Selection
 
 - `.workflow/WORKFLOW.md`: overall objective, policy, state, units, and next action.
+- `.workflow/LEDGER.md`: compact lean-runner state for large bounded backlogs, with one row per work unit and targeted check evidence.
 - `.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.
+- `.workflow/WORKER-MAP.md`: worker names, roles, transports, native resource ids, dossiers, dependencies, start conditions, report status, close actions, close results, and supervisor checkpoints.
 - `.workflow/ACCEPTANCE-MATRIX.md`: verifiable done criteria.
 - `.workflow/VERIFICATION-REPORT.md`: evidence-backed PASS/FAIL/BLOCKED report.
 - `.workflow/REPAIR-TICKETS.md`: actionable repair tasks from verifier findings.
 - `.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,9 +38,57 @@ 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
 ```
 
+## LEDGER.md
+
+Use this for `lean_work_unit_runner` when the backlog is already bounded and the workflow needs high throughput with human-verifiable state.
+
+```md
+# Lean Work Unit Ledger
+
+Profile: lean_work_unit_runner
+Execution Path:
+Mode:
+Delegation:
+Final Disposition:
+Batch Checkpoint:
+
+## Scope Contract
+
+Objective:
+Controlling Backlog Or Source:
+Allowed Surfaces:
+Forbidden Surfaces:
+Escalation Triggers:
+
+## Units
+
+| ID | Source Ref | Scope | Done Signal | Check | Status | Touched Surfaces | Evidence | Blocker Or Next Action |
+|---|---|---|---|---|---|---|---|---|
+
+## Batch Checkpoints
+
+| Batch | Units | Result | Checks | Human Review Needed | Next Action |
+|---|---|---|---|---|---|
+```
+
 ## SOURCE-CORPUS.md
 
 ```md
@@ -65,6 +113,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
@@ -137,14 +259,16 @@ Git rule: in a Git-backed codebase, ensure `<workspace>/.gitignore` contains `.w
 ```md
 # Worker Map
 
-| Worker Name | Role | Transport | Work Unit | Dossier | Start Condition | Dependencies | Status | Terminal Report |
-|---|---|---|---|---|---|---|---|---|
+| Worker Name | Role | Transport | Native Resource ID | Work Unit | Dossier | Start Condition | Dependencies | Status | Terminal Report | Close Action | Close Result |
+|---|---|---|---|---|---|---|---|---|---|---|---|
 
 ## Supervisor Checkpoints
 
 ## Blocked Workers
 
 ## Closed Workers
+
+Closed means the terminal report has been consumed and any native thread or subagent resource has a recorded close result. For Codex subagents, record the `spawn_agent` id as Native Resource ID and `close_agent` as Close Action. A workflow with open native workers must remain BLOCKED until the close result is recorded.
 ```
 
 ## ACCEPTANCE-MATRIX.md
@@ -249,6 +373,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