workflow-supervisor 0.1.0 → 0.1.2

package/schemas/worker-report-v1.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workflow-supervisor.local/schemas/worker-report-v1.schema.json",
+  "title": "WorkerReportV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "status",
+    "role",
+    "unit_id",
+    "summary",
+    "changed_surfaces",
+    "evidence",
+    "checks_run",
+    "skipped_checks",
+    "findings",
+    "blocking_question",
+    "next_action",
+    "adapter",
+    "guard",
+    "reason"
+  ],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "WorkerReportV1"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["PASS", "FAIL", "BLOCKED"]
+    },
+    "role": {
+      "type": "string",
+      "enum": ["implementer", "verifier", "repair", "documenter"]
+    },
+    "unit_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "summary": {
+      "type": "string"
+    },
+    "changed_surfaces": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "checks_run": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "skipped_checks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "blocking_question": {
+      "type": ["string", "null"]
+    },
+    "next_action": {
+      "type": "string"
+    },
+    "adapter": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": [],
+      "properties": {}
+    },
+    "guard": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": [
+        "allowed_surface_violations",
+        "role_violations",
+        "warnings"
+      ],
+      "properties": {
+        "allowed_surface_violations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "role_violations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "reason": {
+      "type": ["string", "null"]
+    }
+  }
+}

package/skills/acceptance-matrix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acceptance-matrix
-description: Convert requirements into formal, evidence-mapped acceptance criteria only for supervised, high-risk, ambiguous, resumable, or handoff workflows. Use when verification must map each requirement to evidence, adversarial cases, PASS/FAIL/BLOCKED states, review states, and residual risk. Do not use for ordinary code review, small scoped edits, routine test runs, trivial explicit acceptance, or declaring completion unless the user asks for an acceptance matrix or evidence-mapped verification.
+description: Convert requirements into formal, evidence-mapped acceptance criteria only for supervised, high-risk, ambiguous, resumable, or delegated workflows. Use when verification must map each requirement to evidence, adversarial cases, PASS/FAIL/BLOCKED states, review states, and residual risk. Do not use for ordinary code review, small scoped edits, routine test runs, trivial explicit acceptance, or declaring completion unless the user asks for an acceptance matrix or evidence-mapped verification.
 ---
 
 # Acceptance Matrix
@@ -53,7 +53,7 @@ Consider:
 ```yaml
 status: PASS|FAIL|BLOCKED
 verified_work_unit:
-verified_thread:
+verified_worker:
 matrix:
   - id:
     requirement:

package/skills/dossier-builder/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: dossier-builder
-description: Create a concrete handoff contract only when one already-bounded work unit needs a dossier for another agent, thread, future session, formal worker prompt, or durable handoff. Use when objective, sources, boundaries, acceptance rows, checks or evidence, stop gates, thread naming, start conditions, and report schemas must be captured before delegation. Do not use to plan work Codex will perform directly in the current turn, for unbounded work, or for ordinary same-thread implementation.
+description: Create a concrete delegation contract only when one already-bounded work unit needs a dossier for another agent, automated worker run, future session, formal worker prompt, or durable continuation. Use when objective, sources, boundaries, acceptance rows, checks or evidence, stop gates, worker naming, start conditions, and report schemas must be captured before delegation. Do not use to plan work Codex will perform directly in the current turn, for unbounded work, or for ordinary same-session implementation.
 ---
 
 # Dossier Builder
 
-Use this skill to prevent vague handoffs. A dossier is the contract between the supervisor and a worker.
+Use this skill to prevent vague delegation. A dossier is the contract between the supervisor and a worker.
 
 ## Domain Neutral Inputs
 
@@ -26,6 +26,14 @@ The dossier does not own acceptance design. It references or embeds acceptance r
 
 If these inputs are missing, create a discovery dossier or return BLOCKED.
 
+Before delegation, validate the dossier with:
+
+```bash
+workflow-supervisor validate-dossier <dossier-path> --role <role> --unit <unit-id> --json
+```
+
+If validation fails, do not start a worker. Return BLOCKED, create a discovery dossier, or ask the supervisor/user for the missing decision.
+
 For early discovery, the only source may be conversation context and the only allowed surface may be a planned brief, doc, or question list. Do not require repository paths or existing files.
 
 Use a provisional dossier for low-risk drafts, plans, outlines, rubrics, and options when sources are thin but the output can clearly mark assumptions. Use BLOCKED for factual, irreversible, regulated, publication, or production changes that lack material sources or boundaries.
@@ -33,11 +41,13 @@ Use a provisional dossier for low-risk drafts, plans, outlines, rubrics, and opt
 ## Dossier Shape
 
 ```yaml
+schema: DossierV1
 workflow:
 work_unit:
 dossier_id:
-thread_name:
-thread_role:
+worker_name:
+worker_role:
+delegation_transport:
 start_condition:
 title:
 objective:
@@ -57,7 +67,7 @@ acceptance_matrix:
 adversarial_checks:
 required_commands_or_evidence:
 worker_role:
-handoff_message:
+worker_prompt:
 supervisor_checkpoints:
 completion_report_schema:
 verification_report_schema:
@@ -66,7 +76,9 @@ assumptions:
 open_questions:
 ```
 
-## Handoff Rules
+The machine gate requires concrete strings or arrays for the core fields. Use `open_questions: [none]` only when no open question remains. Do not use placeholders such as `TBD`, `unknown`, `all files`, `entire repo`, `as needed`, or `use your judgment`.
+
+## Delegation Rules
 
 - Name exact files, docs, systems, or artifact paths when available.
 - Prefer concrete boundaries over broad module names.
@@ -76,10 +88,12 @@ open_questions:
 - Require workers to report skipped checks and assumptions.
 - For non-code work, use evidence such as citations, before/after excerpts, review rubrics, examples, artifact diffs, or explicit user decisions instead of commands.
 - Require repair tickets to cite the verification finding or acceptance row they repair.
-- Include a deterministic `thread_name` when delegation is planned. Use `wf/<workflow-slug>/<unit-id>-<role>-<dossier-slug>`.
+- Include a deterministic `worker_name` when delegation is planned. Use `wf/<workflow-slug>/<unit-id>-<role>-<dossier-slug>`.
 - Include `start_condition`, such as `after path gate`, `after human plan approval`, `after autonomous execution plan`, `after implementer report`, `after verification FAIL`, or `after repairs complete`.
-- Include a ready-to-send `handoff_message` that contains only the worker's role, dossier, sources, acceptance rows, stop gates, and report schema.
+- Include the selected `delegation_transport`, such as `portable_delegate`, `native_thread`, `native_subagent`, or `same_session_phased`.
+- Include a ready-to-send `worker_prompt` that contains only the worker's role, dossier, sources, acceptance rows, stop gates, and report schema.
 - Include supervisor checkpoints for kickoff acknowledgement, blocker questions, terminal report, and closeout.
+- Run `workflow-supervisor validate-dossier` before `workflow-supervisor delegate`. Treat validation failure as a stop gate.
 
 ## Failure Modes
 

package/skills/dossier-builder/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Dossier Builder"
-  short_description: "Create concrete thread handoff contracts"
-  default_prompt: "Use $dossier-builder to create a grounded handoff dossier with thread name, start condition, and report schema for this work unit."
+  short_description: "Create concrete worker delegation contracts"
+  default_prompt: "Use $dossier-builder to create a grounded worker dossier with worker name, delegation transport, start condition, and report schema for this work unit."
 
 policy:
   allow_implicit_invocation: false

package/skills/loop-policy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loop-policy
-description: Define execution policy only for supervised, multi-agent, multi-thread, long-running, resumable, autonomous-goal, human-in-loop, approval-gated, or repair-loop workflows. Use for execution path selection, sequential or parallel execution, thread orchestration, retry and repair limits, budgets, escalation, Codex goal binding, blocking rules, continuation criteria, and no-progress detection. Do not use for one failing command, normal retrying, routine user approval, or a one-shot task with obvious completion.
+description: Define execution policy only for supervised, multi-agent, portable-worker, long-running, resumable, autonomous-goal, human-in-loop, approval-gated, or repair-loop workflows. Use for execution path selection, sequential or parallel execution, worker delegation, retry and repair limits, budgets, escalation, Codex goal binding, blocking rules, continuation criteria, and no-progress detection. Do not use for one failing command, normal retrying, routine user approval, or a one-shot task with obvious completion.
 ---
 
 # Loop Policy
@@ -30,11 +30,11 @@ Do not create goals for small direct tasks. A goal is the state container for op
 - 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 thread creation, before implementation, before verification, before repair, before publication, before irreversible action, before each unit, or path-gated.
-- Delegation orchestration: thread or subagent availability, naming scheme, spawn timing, supervisor checkpoint cadence, terminal report collection, and fallback when delegation tools are unavailable.
+- 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.
 - Repair limit: maximum repair loops per unit.
 - Budget: time, token, command, cost, or file-change limits.
-- Escalation: when to ask the user, spawn a specialist, or stop.
+- 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.
 - Mutation conflict: whether units touch the same mutable surfaces or decisions.
@@ -44,7 +44,7 @@ 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
-intake_required_when: every supervisor invocation before goal creation, planning beyond intake, thread or subagent creation, implementation, verification, repair, final disposition, publication, or irreversible action
+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
 use_judgment_defaults: none; user must answer every required intake decision explicitly
@@ -54,15 +54,15 @@ 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
-thread_spawn_rule: after complete intake, path gate, and concrete dossier
-subagent_spawn_rule: after complete intake, path gate, and concrete dossier when the environment exposes subagent tools
-thread_name_template: wf/<workflow-slug>/<unit-id>-<role>-<dossier-slug>
-supervisor_checkpoint_cadence: after handoff acknowledgement, terminal report, repair ticket creation, re-verification, and final disposition
+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_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
 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: handoff or outcome doc for long workflows
+resume_requires: workflow state or outcome doc for long workflows
 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

package/skills/loop-policy/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Loop Policy"
-  short_description: "Control path, threads, retries, and gates"
+  short_description: "Control path, workers, retries, and gates"
   default_prompt: "Use $loop-policy to enforce complete intake before work starts, forbid keyword shortcuts, require explicit user answers for every intake field, then define execution path, delegation, retry, approval, and stopping rules."
 
 policy:

package/skills/work-unit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: work-unit
-description: Decompose fuzzy or broad objectives into bounded, sequenced, verifiable work units. Use when a task is too large, ambiguous, multi-phase, dependency-heavy, or risky to execute as one edit; when a supervisor needs packets, milestones, slices, tickets, or agent handoffs; or when scope must be narrowed before implementation. Do not use for already-small tasks with clear files and acceptance.
+description: Decompose fuzzy or broad objectives into bounded, sequenced, verifiable work units. Use when a task is too large, ambiguous, multi-phase, dependency-heavy, or risky to execute as one edit; when a supervisor needs packets, milestones, slices, tickets, or agent delegation; or when scope must be narrowed before implementation. Do not use for already-small tasks with clear files and acceptance.
 ---
 
 # Work Unit
@@ -16,7 +16,7 @@ Work units can be bounded by code package, document section, source set, stakeho
 A good work unit has:
 
 - one objective
-- a stable unit ID suitable for dossier and thread naming
+- a stable unit ID suitable for dossier and worker naming
 - named dependencies
 - explicit in-scope and out-of-scope surfaces
 - known sources or source gaps
@@ -49,7 +49,7 @@ For over-broad one-pass requests, produce a sequencing recommendation and invoke
 parent_objective:
 units:
   - id:
-    thread_slug:
+    worker_slug:
     title:
     objective:
     in_scope:

package/skills/worker-roles/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: worker-roles
-description: Define narrow role contracts only when creating explicit worker prompts or separating responsibilities across multiple agents, threads, reviewers, or formal handoffs. Use to prevent role bleed such as verifiers editing implementation, implementers self-approving, repair authors inventing scope, or documenters starting before evidence exists. Do not use for ordinary single-agent reviewing, editing, researching, documenting, or implementing in the current thread.
+description: Define narrow role contracts only when creating explicit worker prompts or separating responsibilities across multiple agents, automated worker runs, reviewers, or formal delegation. Use to prevent role bleed such as verifiers editing implementation, implementers self-approving, repair authors inventing scope, or documenters starting before evidence exists. Do not use for ordinary single-agent reviewing, editing, researching, documenting, or implementing in the current session.
 ---
 
 # Worker Roles
 
 Use this skill to make delegation safe. Each worker prompt should include one role, one objective, allowed behavior, forbidden behavior, sources to read, and a report schema.
 
-No worker thread should start before the supervisor intake and path gates are satisfied. In `human_in_loop`, that means complete intake plus human plan approval. In `autonomous_goal`, that means complete intake selecting `autonomous_goal` plus a recorded execution plan. Role-specific start conditions below are additional gates after the path gate.
+No worker should start before the supervisor intake and path gates are satisfied. In `human_in_loop`, that means complete intake plus human plan approval. In `autonomous_goal`, that means complete intake selecting `autonomous_goal` plus a recorded execution plan. Role-specific start conditions below are additional gates after the path gate.
 
 ## Domain Neutrality
 
@@ -15,7 +15,7 @@ Use "Executor" or "Producer" instead of "Implementer" when the work is documenta
 
 ## Solo Mode
 
-When separate agents, threads, or reviewers are unavailable, collapse roles into phases in the same session. Label verification as `self-check`, not independent verification. Require independent review only when the user asks, the work is high-risk, publication-bound, regulated, security-sensitive, or the loop policy requires it.
+When separate automated workers, agents, or reviewers are unavailable, collapse roles into phases in the same session. Label verification as `self-check`, not independent verification. Require independent review only when the user asks, the work is high-risk, publication-bound, regulated, security-sensitive, or the loop policy requires it.
 
 ## Role Contracts
 
@@ -91,13 +91,13 @@ When separate agents, threads, or reviewers are unavailable, collapse roles into
 - A repair author that adds product requirements is expanding scope.
 - A documenter that hides unknowns is corrupting resume state.
 - A supervisor that implements code should mark that role switch explicitly.
-- Same-thread verification is a self-check unless an independent verifier separately inspects the evidence.
+- Same-session verification is a self-check unless an independent verifier separately inspects the evidence.
 
 ## Worker Prompt Minimums
 
 Include:
 
-- thread name
+- worker name
 - role name
 - work unit and objective
 - must-read sources
@@ -106,10 +106,10 @@ Include:
 - stop gates
 - exact report schema
 
-## Thread Interaction Rules
+## Worker Interaction Rules
 
-- Workers should acknowledge the handoff before acting.
-- Workers should ask the supervisor for clarification when a blocker affects scope, sources, surfaces, checks, or acceptance.
-- Workers should not message other worker threads directly unless the supervisor allows it in the loop policy.
+- Workers should confirm they received the assigned dossier before acting when the transport supports acknowledgement.
+- Workers should return `BLOCKED` to the supervisor when a blocker affects scope, sources, surfaces, checks, or acceptance.
+- Workers should not message other workers directly unless the supervisor allows it in the loop policy.
 - Workers should send one terminal report with PASS, FAIL, BLOCKED, or PARTIAL status using the assigned schema.
-- Verifier and repair threads should cite acceptance row IDs and prior report IDs so the supervisor can route the loop.
+- Verifier and repair workers should cite acceptance row IDs and prior report IDs so the supervisor can route the loop.

package/skills/worker-roles/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Worker Roles"
-  short_description: "Define narrow worker thread contracts"
-  default_prompt: "Use $worker-roles to assign strict thread roles and prevent role bleed in this workflow."
+  short_description: "Define narrow worker role contracts"
+  default_prompt: "Use $worker-roles to assign strict worker roles and prevent role bleed in this workflow."
 
 policy:
   allow_implicit_invocation: false

package/skills/workflow-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-docs
-description: Generate or refresh durable workflow-state, handoff, resume, verification, repair, decision, or documentation-production control artifacts. Use when the work needs reusable state such as workflow control docs, documentation briefs, source inventories, review plans, revision queues, publishing checklists, or maintenance plans. Do not use for ordinary README edits, help article drafting, prose cleanup, summaries, marketing copy, decorative docs, or documentation content unless reusable workflow/documentation-production state is requested.
+description: Generate or refresh durable workflow-state, delegation, resume, verification, repair, decision, or documentation-production control artifacts. Use when the work needs reusable state such as workflow control docs, documentation briefs, source inventories, review plans, revision queues, publishing checklists, or maintenance plans. Do not use for ordinary README edits, help article drafting, prose cleanup, summaries, marketing copy, decorative docs, or documentation content unless reusable workflow/documentation-production state is requested.
 ---
 
 # Workflow Docs
@@ -13,7 +13,7 @@ Do not require existing Markdown files. You may create a minimal doc set from co
 
 ## State Artifact Medium
 
-Markdown is the default when the workspace/file medium is appropriate, but reusable workflow state may also be an inline brief, spreadsheet tab, ticket set, design annotation, CRM note, runbook, decision log, slide appendix, whiteboard note, or chat handoff. Choose the medium that the next human or agent can actually use.
+Markdown is the default when the workspace/file medium is appropriate, but reusable workflow 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. Choose the medium that the next human or agent can actually use.
 
 ## Default Artifact Directory
 
@@ -21,11 +21,13 @@ When creating Markdown workflow artifacts, use `<workspace>/.workflow/` as the d
 
 Use another location only when the user names one, the project has an existing workflow-state convention, the target medium is not files, or the artifact is a final deliverable that belongs elsewhere. Keep control artifacts under `.workflow/` even when implementation files, docs, or product outputs are created in normal project locations.
 
+In a Git-backed codebase, `.workflow/` is local supervisor state by default. Before creating `.workflow/` artifacts, ensure `<workspace>/.gitignore` contains `.workflow/`. Create `.gitignore` if needed. Do not stage, commit, or publish `.workflow/` unless the completed intake explicitly names workflow state as a final deliverable.
+
 ## Artifact Lanes
 
 Use two lanes:
 
-- Workflow control: preserve state, decisions, work units, handoffs, verification, and outcomes.
+- Workflow control: preserve state, decisions, work units, delegation, verification, and outcomes.
 - Documentation production: define audience, purpose, content inventory, outline, style, review path, publication readiness, and maintenance.
 
 For documentation work, start with `DOCUMENTATION-BRIEF.md` unless the user provides an equivalent brief. Without audience, reader task, document type, owner, source expectations, and publishing target, create a brief or ask for the missing decision before drafting final content.
@@ -35,15 +37,15 @@ For documentation work, start with `DOCUMENTATION-BRIEF.md` unless the user prov
 - Scaffold blank artifacts for a new workflow.
 - Generate artifacts from conversation, source inspection, or supervisor state.
 - Refresh existing artifacts while preserving unresolved questions and decisions.
-- Create a resume pack for another thread or future session.
+- Create a resume pack for another worker or future session.
 - Convert verification and repair results into durable reports.
-- Preserve thread plans, worker handoffs, terminal reports, and final disposition decisions when supervised work spans threads.
+- Preserve worker delegation plans, terminal reports, and final disposition decisions when supervised work spans workers or sessions.
 
 ## Rules
 
 - Load [references/templates.md](references/templates.md) first when choosing exact templates, then load only the referenced lane file needed for the task.
 - Load [references/documentation-production.md](references/documentation-production.md) for documentation deliverables, content drafts, claims registers, review plans, publishing, and maintenance.
-- Load [references/workflow-control.md](references/workflow-control.md) for supervised workflow state, work units, dossiers, acceptance, verification, repairs, decisions, handoffs, and outcomes.
+- Load [references/workflow-control.md](references/workflow-control.md) for supervised workflow state, work units, dossiers, acceptance, verification, repairs, decisions, delegation state, and outcomes.
 - Load [references/goal-resume.md](references/goal-resume.md) for Codex goal mirrors, active-goal conflicts, and resume packs.
 - Keep facts, assumptions, open questions, and inferences separate.
 - Include paths, commands, sources, and evidence when available.
@@ -52,6 +54,7 @@ For documentation work, start with `DOCUMENTATION-BRIEF.md` unless the user prov
 - Do not create files the workflow will not use.
 - Reject requests to create every possible workflow document "just in case"; select the smallest doc set that preserves state or enables production.
 - Do not treat workflow docs as a required provenance ledger; use them as lightweight working memory.
+- Keep `.workflow/` ignored by Git in codebases; workflow state is private working memory unless the user explicitly chooses to publish it.
 - Adapt headings from files and commands to artifacts and evidence for non-code workflows.
 - Preserve acceptance matrices and verification reports; do not reinterpret evidence rows or change verdicts unless the workflow explicitly asks for a review/update.
 
@@ -60,15 +63,15 @@ 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/WORK-UNITS.md`: decomposition and sequencing.
-- `.workflow/DOSSIER.md`: handoff contract for one unit.
-- `.workflow/THREAD-MAP.md`: thread names, roles, dossiers, dependencies, start conditions, report status, and supervisor checkpoints.
+- `.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/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 handoff.
+- `.workflow/GOAL-STATE.md`: optional fallback record when a Codex goal tool is unavailable or goal state must be mirrored for continuation.
 - `.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/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Workflow Docs"
-  short_description: "Preserve workflow and thread state"
-  default_prompt: "Use $workflow-docs to create or refresh .workflow/ artifacts that preserve workflow, thread, handoff, verification, and outcome state."
+  short_description: "Preserve workflow and worker state"
+  default_prompt: "Use $workflow-docs to create or refresh .workflow/ artifacts that preserve workflow, worker delegation, verification, and outcome state."
 
 policy:
   allow_implicit_invocation: false

package/skills/workflow-docs/references/documentation-production.md

@@ -4,6 +4,8 @@ Use these for documentation production. Do not create all of them by default; se
 
 Default path: create documentation-production control artifacts under `<workspace>/.workflow/` unless the user names another artifact directory or the project already has an established workflow-state location. Final public docs, app files, articles, or published content may still belong in their normal product or documentation locations.
 
+In Git-backed codebases, ensure `<workspace>/.gitignore` contains `.workflow/` before creating these control artifacts. Workflow state is local working memory and should not be staged or published unless explicitly selected as a final deliverable.
+
 ## Presets
 
 - Public article: `DOCUMENTATION-BRIEF.md`, `CONTENT-INVENTORY.md`, `OUTLINE.md`, `CONTENT-DRAFT.md`, `REVIEW-PLAN.md`, `PUBLISHING-CHECKLIST.md`.

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

@@ -4,6 +4,8 @@ Use these only for Codex goal mirroring, active-goal conflicts, or resume packs.
 
 Default path: create `GOAL-STATE.md` and goal-aware workflow artifacts under `<workspace>/.workflow/` unless the user provides another artifact directory or the project already has an established workflow-state location.
 
+In Git-backed codebases, ensure `<workspace>/.gitignore` contains `.workflow/` before creating these artifacts. Workflow state is local working memory and should not be staged or published unless explicitly selected as a final deliverable.
+
 ## Goal-Aware WORKFLOW.md Fields
 
 ```md

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

@@ -4,6 +4,8 @@ Load only the lane needed for the task.
 
 Create Markdown artifacts under `<workspace>/.workflow/` by default. Use another directory only when the user names one, the project already has a clearer workflow-state convention, or the artifact is a final deliverable that belongs elsewhere.
 
+In Git-backed codebases, ensure `<workspace>/.gitignore` contains `.workflow/` before creating the directory. Workflow state is local working memory and should not be staged or published unless explicitly selected as a final deliverable.
+
 ## Documentation Production
 
 Read [documentation-production.md](documentation-production.md) when creating or revising documentation deliverables, briefs, outlines, factual source registers, review plans, publication assets, or maintenance plans.
@@ -26,7 +28,7 @@ Includes:
 
 ## Workflow Control
 
-Read [workflow-control.md](workflow-control.md) when preserving supervised workflow state, work units, dossiers, acceptance matrices, verification reports, repairs, decisions, handoffs, or outcomes.
+Read [workflow-control.md](workflow-control.md) when preserving supervised workflow state, work units, dossiers, acceptance matrices, verification reports, repairs, decisions, delegation state, or outcomes.
 
 Includes:
 
@@ -34,7 +36,7 @@ Includes:
 - `SOURCE-CORPUS.md`
 - `WORK-UNITS.md`
 - `DOSSIER.md`
-- `THREAD-MAP.md`
+- `WORKER-MAP.md`
 - `ACCEPTANCE-MATRIX.md`
 - `VERIFICATION-REPORT.md`
 - `REPAIR-TICKETS.md`

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

@@ -1,9 +1,11 @@
 # Workflow Control Templates
 
-Use these for supervised workflow state. Do not use them for ordinary documentation drafting unless workflow state or handoff is required.
+Use these for supervised workflow state. Do not use them for ordinary documentation drafting unless workflow state or continuation is required.
 
 Default path: create these files under `<workspace>/.workflow/` unless the user provides another artifact directory or the project already has an established workflow-state location.
 
+Git rule: in a Git-backed codebase, ensure `<workspace>/.gitignore` contains `.workflow/` before creating this directory. Treat `.workflow/` as local workflow memory; do not stage, commit, push, or include it in a PR unless the user explicitly makes workflow state a final deliverable.
+
 ## WORKFLOW.md
 
 ```md
@@ -68,7 +70,7 @@ Default path: create these files under `<workspace>/.workflow/` unless the user
 ```md
 # Work Units
 
-| ID | Thread Slug | Title | Objective | Dependencies | Status | Verification |
+| ID | Worker Slug | Title | Objective | Dependencies | Status | Verification |
 |---|---|---|---|---|---|---|
 
 ## Sequencing
@@ -85,9 +87,11 @@ Default path: create these files under `<workspace>/.workflow/` unless the user
 
 ## Dossier ID
 
-## Thread Name
+## Worker Name
+
+## Worker Role
 
-## Thread Role
+## Delegation Transport
 
 ## Start Condition
 
@@ -117,7 +121,7 @@ Default path: create these files under `<workspace>/.workflow/` unless the user
 
 ## Owner Or Contributor Role
 
-## Handoff Message
+## Worker Prompt
 
 ## Supervisor Checkpoints
 
@@ -128,19 +132,19 @@ Default path: create these files under `<workspace>/.workflow/` unless the user
 ## Open Questions
 ```
 
-## THREAD-MAP.md
+## WORKER-MAP.md
 
 ```md
-# Thread Map
+# Worker Map
 
-| Thread Name | Role | Work Unit | Dossier | Start Condition | Dependencies | Status | Last Supervisor Message | Terminal Report |
+| Worker Name | Role | Transport | Work Unit | Dossier | Start Condition | Dependencies | Status | Terminal Report |
 |---|---|---|---|---|---|---|---|---|
 
 ## Supervisor Checkpoints
 
-## Blocked Threads
+## Blocked Workers
 
-## Closed Threads
+## Closed Workers
 ```
 
 ## ACCEPTANCE-MATRIX.md
@@ -165,7 +169,7 @@ Status: PASS | FAIL | BLOCKED | NEEDS REVISION | APPROVED WITH CAVEATS | READY T
 
 Verified Work Unit:
 
-Verified Thread:
+Verified Worker:
 
 ## Sources Inspected
 
@@ -262,7 +266,7 @@ Final Disposition Policy:
 
 ## Work Completed
 
-## Worker Threads
+## Workers
 
 ## Verification Evidence