Complete Implementation (Quality Gates + Recursion)

<sam_cli> uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" </sam_cli>

The references/recursive-follow-up-handling.md file loaded by this skill is a plain file, not substituted — it shows bare SAM CLI subcommands and args only (e.g. backlog list --title "..."), never the invocation prefix. Prepend the command in <sam_cli/> above to every one of them.

---

[!IMPORTANT] When provided a process map or Mermaid diagram, treat it as the authoritative procedure. Execute steps in the exact order shown, including branches, decision points, and stop conditions. A Mermaid process diagram is an executable instruction set. Follow it exactly as written: respect sequence, conditions, loops, parallel paths, and terminal states. Do not improvise, reorder, or skip steps. If any node is ambiguous or missing required detail, pause and ask a clarifying question before continuing. When interacting with a user, report before acting the interpreted path you will follow from the diagram, then execute.

---

Input Format Detection

Parse $ARGUMENTS to determine the input type before proceeding. A plan address is an opaque logical identifier returned by sam_plan; pass it through unchanged.

flowchart TD
    Input["Read $ARGUMENTS"] --> Q2{"starts with '#'?"}
    Q2 -->|Yes| IssueHash["Strip '#' → issue_number<br>→ proceed to 'Resolve Issue'"]
    Q2 -->|No| Q3{"matches ^[0-9]+$ ?"}
    Q3 -->|Yes| IssueBare["issue_number = input<br>→ proceed to 'Resolve Issue'"]
    Q3 -->|No| Q4{"contains '/issues/'?"}
    Q4 -->|Yes| IssueURL["Extract number from URL path<br>→ proceed to 'Resolve Issue'"]
    Q4 -->|No| Q5{"work-item reference?<br>e.g. bd-a3f8"}
    Q5 -->|Yes| IssueBeads["issue_id = input str<br>→ Resolve Issue"]
    Q5 -->|No| Q6{"non-empty string?"}
    Q6 -->|Yes| PlanAddress["PLAN ADDRESS format<br>→ proceed to 'Resolve Plan Address'"]
    Q6 -->|No| Err["ERROR: empty input.<br>Expected: plan address or work-item reference."]

---

Resolve Issue

Entered when input is #N, bare N, GitHub URL, or another work-item reference such as bd-a3f8. Normalize it to the opaque {item_ref} used by the selected backend. Skip for plan address input.

Step 1 -- Fetch issue data:

uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" backlog view --selector "{item_ref}"

If the response contains an error key:

ERROR: Work item {item_ref} not found. Verify the reference and try again.

Stop.

Step 2 -- Check for linked plan:

Read the plan field from the response.

flowchart TD
    Plan{plan field<br>present and non-empty?}
    Plan -->|Yes| AutoResolve["Read opaque plan address from plan field<br>→ proceed to 'Resolve Plan Address'<br>(existing 7-phase flow)"]
    Plan -->|No| PropFlow["→ proceed to 'Proportional Quality Gates'"]

When auto-resolving to the SAM path, output:

Work item {item_ref} has linked plan: {plan_address}
Proceeding with full quality gates.

Step 3 -- Extract context for proportional gates:

From the backlog_view response, extract and store:

• item_ref: str (the response's opaque reference)
• title: str
• body: str (full issue body text)
• labels: list[str]
• issue_number: int or None (GitHub only; used solely for commit-history discovery)

These values are used by the Proportional Quality Gates section below. Set {item_slug} to the lowercase {item_ref} with each non-alphanumeric run replaced by one hyphen.

---

Proportional Quality Gates

Entered only when the work item has no linked plan. Skip this section for plan-address input or when the work item has a linked plan (auto-resolved to the SAM path).

Step 1 -- Discover modified files:

git log --all --grep="#${issue_number}" --format=%H

Run the commit search only when issue_number is present. For each commit SHA returned:

git diff-tree --no-commit-id --name-only -r {sha}

Deduplicate the file list. If no commits reference the issue number, fall back to:

git diff --name-only main...HEAD

Store the deduplicated file list as modified_files.

If modified_files is empty after both strategies:

WARNING: No modified files found for work item {item_ref}.
Code review and test verification will run against the full working tree.

Step 2 -- Extract acceptance criteria from issue body:

Parse the body field for an acceptance criteria section. Search for these markers (case-insensitive, in order):

1. ## Acceptance Criteria header -- extract all content until next ## header
2. **Acceptance Criteria**: bold marker -- extract all content until next bold marker or ## header
3. Lines starting with - [ ] (unchecked checkboxes) -- collect all such lines

Store as acceptance_criteria (string or None). If none found, set to None.

Step 3 -- Build proportional quality gate plan:

Create the SAM plan directly with 5 tasks. The documentation pass (T4 Documentation Drift Audit + T5 Documentation Update) is included on this direct/issue-only route exactly as it is on the full SAM path — a feature reached through proportional gates is held to the same documentation standard as one reached through a linked plan:

mcp__plugin_dh_sam__sam_plan(
    config={"action": "create",
            "slug": "pqg-{item_slug}",
            "goal": "Proportional quality gate verification for work item {item_ref}",
            "owner_reference": "{item_ref}",
            "tasks": [
                {"id": "T1", "title": "Code Review",        "agent": "code-reviewer",   "dependencies": [],    "priority": 1, "complexity": "medium",
                 "body": "Review files modified for work item {item_ref}: {modified_files}. Check against acceptance criteria: {acceptance_criteria}"},
                {"id": "T2", "title": "Test Verification",  "agent": "feature-verifier","dependencies": ["T1"],"priority": 1, "complexity": "medium",
                 "body": "Verify work item {item_ref} acceptance criteria are met. Files in scope: {modified_files}"},
                {"id": "T3", "title": "Acceptance Check",   "agent": "integration-checker","dependencies": ["T2"],"priority": 1, "complexity": "low",
                 "body": "Confirm acceptance criteria for work item {item_ref} pass end-to-end: {acceptance_criteria}"},
                {"id": "T4", "title": "Documentation Drift Audit", "agent": "doc-drift-auditor","dependencies": ["T3"],"priority": 1, "complexity": "low",
                 "body": "Audit documentation for drift introduced by work item {item_ref}. item_id={item_ref} (REQUIRED — register the audit-report artifact against it; block if absent). project_root is the repository root (your current working directory). Files in scope: {modified_files}. Report any docs that are now stale, missing, or contradicted by the change."},
                {"id": "T5", "title": "Documentation Update", "agent": "service-docs-maintainer","dependencies": ["T4"],"priority": 1, "complexity": "low",
                 "body": "Update documentation to resolve the drift found in T4 for work item {item_ref}. item_id={item_ref} (read the audit-report artifact registered against it). project_root is the repository root (your current working directory). Files in scope: {modified_files}."}
            ]}
)

The pqg- prefix (proportional quality gate) distinguishes this plan from full SAM gates. Store the response's opaque plan_ref as {pqg_plan_address} and pass it unchanged throughout the dispatch loop.

Step 4 -- SAM dispatch loop:

Use the same SAM Dispatch Loop as the full-plan flow (see "SAM Dispatch Loop (Phases T0-T6)" section). The loop operates identically — 5 tasks instead of 7 is the only structural difference. The proportional plan omits T0 (Multi-Perspective Review) and T6 (Context Refinement), but retains the T4/T5 documentation pass.

Phase-specific post-dispatch actions for proportional gates:

flowchart TD
    Done{Which task<br>just completed?}
    Done -->|"T1 Code Review"| T1Post["No follow-up extraction<br>(proportional gates do not<br>generate follow-ups)"]
    Done -->|"T2 Test Verification"| T2Post["Check test results in agent output<br>If failures: log but do not block<br>(completion gate handles pass/fail)"]
    Done -->|"T3 Acceptance Check"| T3Post["No post-dispatch action"]
    Done -->|"T4 Drift Audit"| T4Post{"Read the Total findings count<br>from T4's ARTIFACTS return block<br>(full report is in the audit-report artifact)"}
    T4Post -->|"0 findings — no drift"| SkipT5["sam_task(plan='{pqg_plan_address}', task='T5',<br>config={action:'state', status:'skipped'})"]
    T4Post -->|"1 or more findings — drift"| T5Ready["T5 remains NOT_STARTED — will be<br>dispatched on next loop iteration"]
    Done -->|"T5 Documentation Update"| T5Post["No post-dispatch action"]
    T1Post --> Continue["Continue loop"]
    T2Post --> Continue
    T3Post --> Continue
    SkipT5 --> Continue
    T5Ready --> Continue
    T5Post --> Continue

Detecting drift in T4 output: The @dh:doc-drift-auditor agent returns a Total findings: {count} line in its ARTIFACTS block and registers the full drift report as the audit-report artifact. No drift = Total findings: 0 → skip T5. Drift = Total findings of 1 or more → dispatch T5. If the count line is absent, read the audit-report artifact and treat a non-empty ## Findings by Category as drift.

Step 5 -- Completion verification gate:

Execute the shared procedure in ./references/completion-verification-gate.md with {plan_address} = {pqg_plan_address}, {gate_name} = "Proportional Quality Gate Incomplete", {resume_arg} = {item_ref}, {next_step} = "Step 6".

Step 6 -- Apply status:verified label:

On verification success:

mcp__plugin_dh_backlog__backlog_update(selector="{item_ref}", verified=True)

Note — the CLI's backlog update has no --verified flag. This call must stay MCP.

Beads backend: No dh:state:verified label — skip this call, continue.

On failure (GitHub only), output:

COMPLETION BLOCKED — status:verified label could not be applied.

Error: {error}
Work item: {item_ref}

Fix the error (check backend credentials and access), then re-run /complete-implementation {item_ref}.

Stop. Do not proceed to the Final Step commit.

Step 7 -- No recursive follow-up handling:

The issue-only path does not produce follow-up plans. Skip directly to "Final Step: Commit and Push Remaining Changes", then "Confirm All Workers Finished", then "Resolve the Issue".

---

Resolve Plan Address

Treat the supplied plan address as opaque. Pass the exact value to every sam_plan, sam_task, CLI --plan-address, and skill invocation below. Read the plan once with sam_plan(plan="{plan_address}", config={"action": "read"}); use its feature field as {slug} and its issue field as {item_ref} when present. Do not derive either value from a path.

---

Pre-Phase 1: TN Verification Check

Before invoking Phase 1, check for a TN verification report produced by tn-verification-gate (which reads the T0 baseline written by t0-baseline-capture).

Use the {slug} and {item_ref} resolved from the plan. When {item_ref} is present, read the TN-verification artifact via artifact_read(item_id={item_ref}, artifact_type="TN-verification"). When it is absent, proceed to Phase 1 because no artifact owner is addressable.

The artifact content contains a list of per-criterion BookendVerification records — one per acceptance-criteria-structured entry. There is no top-level verdict field. Aggregate the verdict by scanning all records: the overall result is FAIL if any record has status: regressed; otherwise PASS.

flowchart TD
    Read["artifact_read(item_id={item_ref}, artifact_type='TN-verification')"] --> Exists{Artifact exists?}
    Exists -->|No| Proceed["No structured criteria — proceed to Phase 1"]
    Exists -->|Yes| Scan["Scan all per-criterion records<br>for status: regressed"]
    Scan --> AnyRegressed{Any criterion<br>has status: regressed?}
    AnyRegressed -->|No| Proceed
    AnyRegressed -->|Yes| Stop["STOP — report regressions and block completion"]
    Stop --> Report["Display each criterion with status: regressed<br>Show check_command, T0 stdout, TN stdout<br>Instruct: fix regressions before re-running"]

If any criterion has status: regressed:

1. List each criterion where status: regressed with its check_command, T0 captured stdout, and TN captured stdout.
2. Output:

COMPLETION BLOCKED — TN Verification Failed

Regressed criteria:
  {criterion-id}: {description}
    command: {check_command}
    T0 result: exit {code}, stdout: {stdout}
    TN result: exit {code}, stdout: {stdout}

Fix the regressions, then re-run /complete-implementation.

3. Stop. Do not proceed to Phase 1.

---

Pre-Phase 1a: Migration Fidelity Sign-Off

Before proceeding to Artifact Discovery, check for migration signals.

Execute the full gate procedure defined in ./references/migration-fidelity-gate.md.

Summary of detection signals (full evaluable criteria in the reference):

• Issue title or body contains: "migrat", "convert format", "replace .md", "format conversion", "move from", "transition from"
• Any task acceptance_criteria field contains: "delete", "remove source", "after migration complete", "drop the source"

If no signal found — skip gate, proceed to Artifact Discovery.

If signal found — confirm all four fidelity items from the reference before proceeding. If any unconfirmed, emit COMPLETION BLOCKED — Migration Fidelity Gate (format in reference) and stop.

---

Pre-Phase: Artifact Discovery

When {item_ref} is known, query its artifact manifest to discover all plan artifacts for this feature:

uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" artifact list --item-id "{item_ref}"

If the response contains artifacts, pass the manifest and {item_ref} to quality gate agents (Phases T0-T6) so they can retrieve content with artifact_read. If the manifest is empty, proceed without optional artifacts. If the call errors, report the provider error and stop; artifact content has no second high-level storage route.

---

Pre-Phase 1b: Process Accumulated Concerns

Execute the full procedure defined in ./references/concerns-processing.md.

Summary: Read backlog item → if ## Concerns has unchecked items, verify each (create backlog item if real; mark unconfirmed if not) → update section → proceed to Quality Gate Plan Creation. If no concerns section, proceed immediately.

---

Quality Gate Plan Creation

After the pre-phases complete, set up the SAM-enforced quality gate plan.

Use the {slug} resolved from the implementation plan's feature field.

Step 1: Check for existing QG plan

uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan list --search "qg-{slug}"

flowchart TD
    List["sam_plan(config={action:'list', search:'qg-{slug}'})"] --> Found{QG plan found?}
    Found -->|No| Create["sam_plan(config={action:'create', ...})<br>tasks list from phase mapping table"]
    Found -->|Yes| Check{All tasks terminal?}
    Check -->|"Yes — COMPLETE or SKIPPED"| Skip["Skip to Completion Verification Gate"]
    Check -->|"No — tasks remain"| Reset["Reset BLOCKED tasks to NOT_STARTED,<br>resume SAM dispatch loop"]
    Create --> Loop["Enter SAM Dispatch Loop"]
    Reset --> Loop

When a QG plan is found, store that list entry's opaque plan_ref as {qg_plan_address}. Omit owner_reference from the create call below only when {item_ref} is absent.

Step 2: Create QG plan (if not found)

If no QG plan exists, create it directly using the phase mapping table above:

mcp__plugin_dh_sam__sam_plan(
    config={"action": "create",
            "slug": "qg-{slug}",
            "goal": "Quality gate enforcement for {slug}",
            "owner_reference": "{item_ref}",
            "tasks": [
                {"id": "T0", "title": "Multi-Perspective Review", "agent": "task-worker",     "dependencies": [],           "priority": 1, "complexity": "high"},
                {"id": "T1", "title": "Code Review",              "agent": "code-reviewer",   "dependencies": [],           "priority": 1, "complexity": "medium"},
                {"id": "T2", "title": "Feature Verification",     "agent": "feature-verifier","dependencies": ["T1"],       "priority": 1, "complexity": "medium",
                 "body": "Verify goal achievement for {slug} (work item {item_ref}). plan_address={plan_address} (REQUIRED — this is the original feature plan to read for goals, tasks, and artifacts; the address used to dispatch this task is a separate quality-gate plan used only to claim and complete your own task). item_id={item_ref} (needed to read the architect artifact)."},
                {"id": "T3", "title": "Integration Check",        "agent": "integration-checker","dependencies": ["T2"],   "priority": 1, "complexity": "medium",
                 "body": "Verify cross-module integration for {slug} (work item {item_ref}). plan_address={plan_address} (REQUIRED — this is the original feature plan to read for exports, imports, and data flows; the address used to dispatch this task is a separate quality-gate plan used only to claim and complete your own task). item_id={item_ref}."},
                {"id": "T4", "title": "Documentation Drift Audit","agent": "doc-drift-auditor","dependencies": ["T3"],     "priority": 1, "complexity": "low",
                 "body": "Audit documentation for drift in {slug} (work item {item_ref}). item_id={item_ref} (REQUIRED — register the audit-report artifact against it; block if absent). project_root is the repository root (your current working directory)."},
                {"id": "T5", "title": "Documentation Update",     "agent": "service-docs-maintainer","dependencies": ["T4"],"priority": 1, "complexity": "low",
                 "body": "Update documentation to resolve the drift found in T4 for {slug} (work item {item_ref}). item_id={item_ref} (read the audit-report artifact registered against it). project_root is the repository root (your current working directory)."},
                {"id": "T6", "title": "Context Refinement",       "agent": "context-refinement","dependencies": ["T5"],    "priority": 1, "complexity": "medium",
                 "body": "Refine context and audit plan artifacts for {slug} (work item {item_ref}). plan_address={plan_address} (REQUIRED — this is the original feature plan to analyze; the address used to dispatch this task is a separate quality-gate plan used only to claim and complete your own task). item_id={item_ref} (needed only to read and annotate the architect and feature-context artifacts — if empty, skip that part and report it as a gap)."}
            ]}
)

Store the response's opaque plan_ref as {qg_plan_address}. This is the only address used for subsequent QG plan and task operations.

Step 3: Reset BLOCKED tasks (on re-run)

If the QG plan already exists and has BLOCKED tasks, reset each to NOT_STARTED before entering the dispatch loop:

For each task where status == "blocked":
    mcp__plugin_dh_sam__sam_task(
        plan="{qg_plan_address}",
        task="{task_id}",
        config={"action": "state", "status": "not-started"}
    )

This allows re-running complete-implementation to resume from the blocked phase without re-executing completed phases.

---

SAM Dispatch Loop (Phases T0-T6)

Phase task mapping:

Task	Phase	Agent
T0	Multi-Perspective Review	dh:multi-perspective-review (orchestrated)
T1	Code Review	code-reviewer
T2	Feature Verification	feature-verifier
T3	Integration Check	integration-checker
T4	Documentation Drift Audit	doc-drift-auditor
T5	Documentation Update	service-docs-maintainer
T6	Context Refinement	context-refinement

Dispatch Loop

Repeat until sam_plan(plan="{qg_plan_address}", config={"action": "ready"}) returns a ReadyTasksResult with an empty ready_tasks list:

1. Get next ready task:

uv run "${CLAUDE_PLUGIN_ROOT}/sam_schema/cli.py" plan ready --plan-address "{qg_plan_address}"

If the result is empty, exit the loop and proceed to Completion Verification Gate.

2. Dispatch the task:

flowchart TD
    Ready["Next ready task_id"] --> IsT0{task_id == 'T0'?}
    IsT0 -->|"Yes"| Direct["Run T0 directly — see below"]
    IsT0 -->|"No"| Delegate["Run the start-task workflow<br>against {qg_plan_address} --task {task_id}"]

T1-T6 — delegate: run the dh:start-task workflow (name it in prose — a harness-specific invocation form reaches only the harness that defines it) against {qg_plan_address} --task {task_id}. start-task claims the task and marks it complete on finish. Do not call sam_task(plan="{qg_plan_address}", task="{task_id}", config={"action": "claim"}) in the orchestrator before this step — claiming here causes a double-claim that causes start-task to receive claimed: false and stop without executing the task body.

T0 — run it directly, in your own context; do not delegate it. Its agent is dh:multi-perspective-review (orchestrated) — a workflow that already dispatches its own reviewers, so a delegated worker would only add a hop to reach the same call.

1. Commit any outstanding changes (git add -A && git commit ...).

2. Read sam_plan(plan="{plan_address}", config={"action": "read"}).context for **Implementation base SHA**: <sha> (implement-feature's "Record the Implementation Base SHA" step). If absent, or if git cat-file -e "<sha>" fails (the commit no longer resolves), stop:

   COMPLETION BLOCKED — No Implementation Base SHA
   
   This plan has no recorded starting commit for T0's diff review. Every ref-based substitute
   (a branch name, a merge-base) can silently miss commits once this plan's own work reaches
   origin/main — falling back to one would report success without reviewing everything changed.
   
   To resume: determine the correct starting commit and record it —
   sam_plan(plan="{plan_address}", config={"action": "update", "context": "**Implementation
   base SHA**: <sha>\n\n{existing context}"}) — then re-run /complete-implementation.
   

   Do not proceed to Step 1 (no QG plan is created); do not apply status:verified.

3. Run the workflow (name it in prose) with --diff "<sha>..HEAD", adding --issue {item_ref} when known.

There is no subagent here to claim or complete the task, so do that yourself: sam_task(plan="{qg_plan_address}", task="T0", config={"action": "claim"}) before running the workflow, sam_task(plan="{qg_plan_address}", task="T0", config={"action": "state", "status": "complete"}) after — then continue to Step 3 below exactly as for any other completed task.

3. Phase-specific post-dispatch actions:

After each dispatched phase completes, run the phase-specific processing before querying sam_plan(plan="{qg_plan_address}", config={"action": "ready"}) again: