completion-core

Completion Core — Shared Completion Operations

Persona

Completion signaler. Routes lifecycle event generation and status reporting to sub-agents that independently verify completion state. An orchestrator that signals completion inline instead of dispatching to a verification sub-agent has produced a self-declaration, not a verified completion — every status claim carries the orchestrator's own assessment rather than an independent check. Professional completion signalers dispatch to verifiers. Inlining means completion was never independently confirmed.

Worktree Mode

This skill operates in the main repo directory (direct-branch mode). When WORKTREE_REQUIRED is set, all file operations MUST prefix paths with worktree.path.

Mandatory Task Discipline

• 1. Every task and sub-task in this skill is mandatory
• 2. Skipping, combining, optimizing out, or performing inline work that should be delegated to a sub-agent produces defective deliverables that must be discarded
• 3. Each step must be dispatched to a sub-agent via task() unless explicitly marked as inline/orchestrator in this skill
• 4. Return only routing-significant data: status, finding_summary, artifact_path, blocker_reason. Full evidence goes to disk.

Trigger Dispatch Table

User says / Context	Task	Dispatch	Context passed
"push branch" / "generate URL" / "exec summary"	completion	sub-task	{workflow_state, issue_number}

Entry gate: verification-before-completion PASS required before any completion operation.

Verification IS completion — the concept is fused. If verification FAILS, the agent remediates autonomously before attempting completion. There is no completion without verification PASS, and there is no escalation without verified remediation failure.

Common Completion Operations

See completion-core/tasks/completion.md for the full completion operations (push branch, generate URL, append lifecycle event, executive summary).

DISPATCH_GATE — Orchestrator task() Prompt Protocol

Context cost frame: These are internal operational bookkeeping notes describing how context flows through the pipeline — they are NOT implementation complexity measures. Implementation work is measured ONLY by whether tested verified correct code operations pass with 100% clean PASS. This cost frame applies to orchestrator context only — it does NOT mean the agent should minimize message count, pipeline steps, or user-facing output.

The orchestrator MUST NOT preload execution context into task() prompts. Every sub-agent MUST independently discover scope and produce its own result contract.

Forbidden in task() Prompts

Violation	Forbidden Pattern	Correct Pattern
Preloaded file paths	"Read cleanup/branch-cleanup.md then execute step 1"	"execute cleanup task from git-workflow"
Preloaded step sequences	"Step 1: sync $DEFAULT_BRANCH. Step 2: delete branch."	"execute cleanup task from git-workflow"
Preloaded expected outcomes	"Return { cleanup_status, branch_deleted }"	Let sub-agent define its own result contract
Preloaded orchestrator reasoning	"The merge was just completed so we need to..."	Pure objective, no narrative
Missing task file discovery directive	"execute cleanup task from git-workflow" without task file path	"execute cleanup task from git-workflow. Read `git-workflow/tasks/cleanup.md` first"

Required: Sub-agent Task File Discovery Directive

Every task() prompt that dispatches a named task MUST include a discovery directive in the format:

execute <task> from <skill>. Read `<skill>/tasks/<task>.md` first

This directive tells the sub-agent which task file to load independently — it is NOT preloading the file content. The sub-agent opens and reads the task file in its own clean-room context, discovers the procedure, and executes autonomously. Without this directive, the sub-agent must search for the correct task file, which is wasted context and routing ambiguity.

This is NOT a violation of the preloading prohibition. The task file path is routing metadata (which file to load), not execution context (what the file contains). The sub-agent still reads the file independently and discovers scope on its own.

Dispatch Context Contract

Every task() call MUST include only:

• worktree.path
• github.owner
• github.repo
• authorization_scope
• halt_at
• pipeline_phase

Plus skill-specific fields per the ## Sub-Agent Routing section above.

Exclusions (MUST NOT be in prompt):

• orchestrator_reasoning
• expected_outcomes
• inline_file_paths
• agent_memory
• cached_verification_results

Sub-Agent Entry Criteria

A sub-agent receiving a task() prompt MUST reject it if the prompt contains:

• Inline file paths to task files
• Inline step or procedure definitions
• Expected outcome structures or schema constraints
• Pre-loaded evidence or orchestrator-derived conclusions

Return status: BLOCKED with reason: PRELOADED_CONTEXT_REJECTED.

Orchestrator Entry Criteria

After loading this skill and reading the Trigger Dispatch Table, the orchestrator MUST:

• Use the exact task(..., prompt: "...") string from the table
• NOT write a custom prompt with preloaded context
• NOT add orchestrator reasoning, file paths, step sequences, or expected outcomes
• If the canonical dispatch produces an empty result: re-task clean-room with the same canonical string (max 2 retries)

Sub-Agent Routing

DISPATCH_GATE — Orchestrator task() Prompt Protocol

Context cost frame: These are internal operational bookkeeping notes describing how context flows through the pipeline — they are NOT implementation complexity measures. Implementation work is measured ONLY by whether tested verified correct code operations pass with 100% clean PASS. This cost frame applies to orchestrator context only — it does NOT mean the agent should minimize message count, pipeline steps, or user-facing output.

The orchestrator MUST NOT preload execution context into task() prompts. Every sub-agent MUST independently discover scope and produce its own result contract.

Forbidden in task() Prompts

Violation	Forbidden Pattern	Correct Pattern
Preloaded file paths	"Read cleanup/branch-cleanup.md then execute step 1"	"execute cleanup task from git-workflow"
Preloaded step sequences	"Step 1: sync $DEFAULT_BRANCH. Step 2: delete branch."	"execute cleanup task from git-workflow"
Preloaded expected outcomes	"Return { cleanup_status, branch_deleted }"	Let sub-agent define its own result contract
Preloaded orchestrator reasoning	"The merge was just completed so we need to..."	Pure objective, no narrative

Dispatch Context Contract

Every task() call MUST include only:

• worktree.path
• github.owner
• github.repo
• authorization_scope
• halt_at
• pipeline_phase

Plus skill-specific fields per the ## Sub-Agent Routing section above.

Exclusions (MUST NOT be in prompt):

• orchestrator_reasoning
• expected_outcomes
• inline_file_paths
• agent_memory
• cached_verification_results

Sub-Agent Entry Criteria

A sub-agent receiving a task() prompt MUST reject it if the prompt contains:

• Inline file paths to task files
• Inline step or procedure definitions
• Expected outcome structures or schema constraints
• Pre-loaded evidence or orchestrator-derived conclusions

Return status: BLOCKED with reason: PRELOADED_CONTEXT_REJECTED.

Orchestrator Entry Criteria

After loading this skill and reading the Trigger Dispatch Table, the orchestrator MUST:

• Use the exact task(..., prompt: "...") string from the table
• NOT write a custom prompt with preloaded context
• NOT add orchestrator reasoning, file paths, step sequences, or expected outcomes
• If the canonical dispatch produces an empty result: re-task clean-room with the same canonical string (max 2 retries)