# Workflow Repair

> Apply safe source-workflow fixes from a `WORKFLOW_QUESTIONS.md` report. Use when re-checking an embedded Trellis temp project report, consulting prior workflow issue history, and repairing `docs/workflows/新项目开发工作流/`.

- Skill: `starforall/workflow-repair` (Agent Skill, multi-file: 71 files)
- Install (CLI): `npx skillmds@latest add starforall/workflow-repair`
- Raw SKILL.md: https://api.skillmd.com/api/skills/starforall/workflow-repair/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: starforall (https://skillmd.com/u/starforall)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/starforall/workflow-repair

---


# workflow-repair

## Version History

- **v3.10**: Required focused truth precheck for findings with existing
  temp-project evidence files before cross-task lineage escalation or other
  downstream repair actions
- **v3.9**: Added repair-side false-positive handling for installed shared
  templates versus later-generated task-local runtime evidence files, and
  clarified that filename/path-shape document-reference findings require
  focused content-level verification before adoption
- **v3.8**: Clarified that scan findings based only on empty
  `.codex/skills/`, uppercase `SKILL.md`, or disabled-command active absence
  such as removed `parallel` surfaces default to `ignored` unless another
  installed surface contradicts the current temp-project contract
- **v3.7**: Clarified the positive shared-surface ownership path so findings
  on workflow-owned or workflow-patched shared carriers must still enter normal
  verification instead of being ignored solely because the surface lives under
  a shared carrier directory
- **v3.6**: Clarified compatibility with scan-side ownership gating so older
  reports that still flag non-workflow-owned shared baseline surfaces default
  to `ignored` unless temp-project evidence shows current workflow ownership
- **v3.5**: Clarified that legacy scan findings which only complain about a
  retained carrier explicitly documented as temporarily disabled must default
  to `ignored` unless another installed surface contradicts that disabled
  contract
- **v3.4**: Required behavior-level closure verification for runtime-carrier /
  runtime-patch stop semantics so closure can no longer rely on
  marker/text-only checks for those repair families
- **v3.3**: Added cross-task repair-lineage escalation so a third ordinary
  repair attempt on the same temp-project/report lineage stops as
  `needs-audit` instead of continuing the incremental discovery loop
- **v3.1**: Clarified that repair-side defect judgment in this skill version is
  limited to Claude Code / OpenCode / Codex workflow surfaces; findings that
  only depend on other CLI usage stay out of scope unless the managed surface
  later expands
- **v3.2**: Clarified that valid `.backup-original/` carrier trees paired with
  active patched/overlay assets default to `ignored`, not repairable defects
- **v3.0**: Upgraded the shared contract to `workflow-scan-repair-v4`,
  requires three-way same-version report validation, replaces cross-version
  issue-history memory with task-local closure artifacts, and makes bounded
  closure part of repair convergence

- **v2.8**: Added report-side repair-classification gating so
  `confirmed-defect` is the only default repair-ready class, while
  `design-debt` and `evidence-gap` stop conservative by default, and upgraded
  the prior shared report contract to `workflow-scan-repair-v3`
- **v2.7**: Tightened `--auto` commit-scope confirmation boundaries so mixed-
  scope prompts and misleading all-success/result wording block instead of
  auto-confirming, and formally defined `current repair-task artifacts`
- **v2.6**: Expanded `--auto` commit-confirmation detection to accept explicit
  current-task commit-plan/scope confirmations that enumerate proposed commits
  or task-local artifacts while still asking for one-shot `ok`/yes approval
- **v2.5**: Refined `--auto` into a current-task Trellis close-out loop driven
  by `continue` first, added command-surface to skill-surface fallback rules
  for `continue` / `finish-work`, and defined stop conditions when `continue`
  closes the task or cannot safely advance further
- **v2.4**: Added explicit `--auto` follow-through mode so repair can continue
  into task close-out only after successful repair verification, using current-
  task-scoped commit confirmation plus the platform's available Trellis
  finish-work command surface
- **v2.3**: Clarified that repair-side intake is execution-mode agnostic and
  depends only on the validated `WORKFLOW_QUESTIONS.md` contract, whether the
  scan ran inline or with explicit `--agent` assistance
- **v2.2**: Clarified that successful `workflow-scan` output must already pass
  scan-side read-back validation and that repair-side intake stops when the
  shared report contract is still incomplete
- **v2.1**: Added mandatory repair-task bootstrap, `tmp/workflow-issues/` history documents, all-history replay on every run, strict-review completion rules without mandatory re-embed, and expanded write-scope rules for task and issue-history artifacts
- **v2.0**: Aligned intake with temp-project-only scan reports; removed source-project-root matching and source-location requirements from the shared report contract
- **v1.4**: Added recurrence-closure, contract-surface coverage, and anti-regression gates to reduce repeated repairs and leftover issues
- **v1.3**: Aligned frontmatter with the latest public skill spec by making the description explicitly cover both purpose and trigger, and by adding compatibility requirements
- **v1.2**: Replaced misleading fixed example paths and task-directory placeholders with runtime-sensitive placeholders
- **v1.1**: Clarified temp-project-first verification, explicit repair authorization, no-agent execution, and same-pattern variant handling
- **v1.0**: Initial release

## Purpose

Consume a `WORKFLOW_QUESTIONS.md` report produced by `workflow-scan`, verify
each finding against the temp project and the source project, and apply safe
repairs to workflow source files — ONLY within
`docs/workflows/新项目开发工作流/`.

This skill is the **consumer/fixer** half of the `workflow-scan` /
`workflow-repair` coupled pair.

Its target of judgment is still the embedded workflow result in
`/tmp/trellis-{VERSION}-2`; the source repository is the repair location, not
the primary truth source for whether a reported issue exists.

This skill now requires bounded same-run closure verification using fresh
task-local fixtures. Strict source-side review still matters, but it is no
longer the only convergence gate.

This skill also treats repeated repair attempts across multiple repair tasks as
a convergence signal rather than as isolated fresh starts. If the same report /
temp-project lineage has already produced two earlier ordinary repair tasks, a
third ordinary repair attempt must stop and escalate to audit instead of
continuing the loop.

## When to Use

Use this skill when any of the following is true:

- a `WORKFLOW_QUESTIONS.md` report exists in the temp project and needs to be
  consumed
- the user wants to analyze `/tmp/trellis-{VERSION}-2` and fix the source
  workflow based on real confirmed problems
- the user asks to "repair workflow issues" or "fix workflow findings"
- the user asks to "apply workflow corrections" or "run workflow-repair"
- the user wants the repair flow to continue automatically into normal task
  close-out by explicitly adding `--auto`
- the same class of workflow issue has already reappeared after one or more
  earlier repair attempts
- a workflow-scan cycle has completed and the repair phase should begin

## When Not to Use

- you need to scan for issues first: use `workflow-scan` in the temp project
- you need a comprehensive audit with version gates and runtime validation: use
  `workflow-audit`
- you need version-drift analysis: use `workflow-capability-audit`
- you are doing a normal implementation task without workflow repair

## Core Rules

1. **Fix scope**: ONLY modify files within
   `docs/workflows/新项目开发工作流/`, the current repair task directory, and
   `tmp/workflow-issues/`. No other directories.
2. **Main CLI only**: do not use agents, sub-agents, or task orchestration to
   perform the repair. Work directly in the current CLI session.
3. **Temp-project-first verification**: the report and the temp project are the
   primary behavior evidence. The source repo explains and repairs the issue,
   but does not by itself prove the issue exists.
4. **Do no harm**: must not introduce new problems when fixing. Every proposed
   change must include side-effect analysis and strict source-side review.
5. **Explicit repair language counts as authorization**: if the current user
   instruction already says to fix real confirmed issues, that instruction
   counts as permission after the correction plan is echoed. If the user only
   asked for analysis/judgment, stop after the plan.
6. **Reports are evidence, not truth**: re-check every finding. A scan finding
   is a hypothesis, not a confirmed fact.
7. **Dedicated repair task is required**: this skill must always run inside a
   dedicated trellis repair task. If there is no active task, create one and
   continue. If there is already an active task, create a new repair task and
   switch to it instead of reusing the existing task.
8. **Same-version truth only**: repair may consume only reports whose
   workflow-version matches the temp-project install record and the current
   source `WORKFLOW_VERSION`.
9. **Cross-version issue-history replay is removed**: old
   `tmp/workflow-issues/` memory is not part of the `v4` repair decision path.
10. **Repair artifacts persist**: task files remain the audit trail, including
    task-local closure-round artifacts.
11. **Conservative adoption**: only adopt a fix where the repair is clear,
    minimal, and safe. If in doubt, mark as `manual-decision`.
12. **Root-cause closure is required**: do not stop at symptom repair. Every
    adopted or trellis-native fix must explain why the issue survived into the
    temp project and what source-side change closes that path.
13. **Variant sweep is required**: once a finding is confirmed, search only
    within `docs/workflows/新项目开发工作流/` for the same pattern or same
    root-cause class and fix safe siblings together.
14. **Contract-surface closure is required**: if a fix changes a behavior
    contract, path, marker, declaration, or workflow rule, update every
    in-scope source surface that must stay aligned in the same repair batch when
    safe. This can include scripts, docs, metadata declarations, and in-tree
    tests under the workflow directory.
15. **Bounded closure is required**: after source edits, repair must run fresh
    closure verification rounds and may not close out or bump the workflow
    version while unresolved new in-scope findings remain.
16. **Truth precheck precedes escalation**: when a finding points at existing
    temp-project files or installed artifacts, read the relevant contents and
    focused source workflow surfaces needed to decide whether the problem is
    real before cross-task lineage escalation, repair execution, closure, or
    version-bump decisions. False alarms discovered here must be recorded as
    `ignored` rather than escalated as broader non-convergence.
17. **Cross-task loop escalation is required**: after the truth precheck above,
    if two earlier repair tasks already consumed the same repair lineage and
    one or more truth-surviving findings remain, a third ordinary repair
    attempt must stop as `needs-audit` / broader closure escalation instead of
    continuing as another routine repair batch.
18. **Repair lineage matching must survive version bumps**: later repair tasks
    on the same temp-project/report lineage must still be treated as the same
    loop even if an earlier repair task already bumped `WORKFLOW_VERSION`.
19. **Closure scope is bounded**: closure may auto-absorb only same-family,
    same-contract-surface findings. New-family findings stop automatic
    progression of the current repair batch.
20. **Trellis-native routing**: when Origin = `trellis-native`, the fix must
    NOT modify files outside the workflow directory. Design a patch within the
    workflow so the installer can apply it (add patch script to `commands/`,
    update `HELPER_SCRIPTS`, or add overlay/post-install adjustment).
21. **Round-local rollback**: if closure-added repairs fail inside a round, the
    round's additions must roll back without forcing a full repair-batch reset.
22. **Current closure truth wins**: current same-version closure evidence
    overrides older scan interpretation when they conflict.
23. **Coupled contract**: this skill must consume `WORKFLOW_QUESTIONS.md` in
    the exact format defined in
    `skills/workflow-scan/references/scan-output-template.md`. If the protocol
    version does not match, stop.
24. **Execution-mode agnostic intake**: repair-side validation depends on the
    final `WORKFLOW_QUESTIONS.md` contract only. A report produced by
    `workflow-scan --agent` is acceptable only if the coordinator's final
    output still passes the same shared read-back validation as an inline scan.
25. **No implied repair-side agent mode**: scan-side `--agent` support does
    not extend to `workflow-repair`. Repair remains main-CLI-only unless its
    own contract changes in a separate scoped update.
26. **`--auto` is explicit and gated**: auto follow-through is allowed only
    when the input explicitly includes `--auto`. It never bypasses correction-
    plan presentation, repair authorization, post-repair verification, current-
    task commit readiness, or the normal safety gates required before
    `finish-work`.
27. **Default repair-ready scope is narrow**: only findings whose report-side
    repair classification is `confirmed-defect` may enter the ordinary adopted
    repair path by default.
28. **Design debt is not auto-repair**: `design-debt` findings must default to
    `manual-decision` or `ignored` unless the user explicitly broadens scope
    beyond confirmed defects after the correction plan is shown.
29. **Evidence gaps block source edits**: `evidence-gap` findings must default
    to `blocked` or `manual-decision` until further temp-project or audit
    evidence closes the gap.
30. **Supported CLI defect scope is fixed for this skill version**: repair-side
    adoption may concern only the current workflow's Claude Code / OpenCode /
    Codex managed surfaces. If a finding depends only on behavior in some other
    CLI and does not break these three supported surfaces, it is out of scope
    and must not be treated as a current workflow defect.
31. **Preserved restore surfaces are not auto-defects**: findings that only
    complain about `.backup-original/` carrier trees must default to `ignored`
    when temp-project evidence shows those copies are intentional restore
    surfaces paired with active patched/overlay assets in
    `.trellis/workflow-installed.json`.
32. **Explicitly disabled retained carriers are not auto-defects**: findings
    that only complain that a retained compatibility/subagent carrier remains
    on disk must default to `ignored` when the temp project's installed docs
    or runtime rules explicitly say that carrier is currently unavailable or
    intentionally disabled, unless another installed surface contradicts that
    disabled contract. Contradictions include installed workflow docs still
    teaching its usage, hooks/config/runtime controls still invoking it, or
    another installed command/skill/agent surface still routing through it.
33. **Codex secondary skill emptiness is not an auto-defect**: findings that
    only complain that `.codex/skills/` is empty, or that shared workflow
    skills are absent there, must default to `ignored` when the temp project's
    installed workflow surfaces treat `.agents/skills/` as the shared workflow
    primary carrier and `.codex/skills/` only as a secondary carrier for
    Codex-specific or project-local extra skills.
34. **Uppercase `SKILL.md` is not an auto-defect when contract-consistent**:
    findings that only complain about uppercase `SKILL.md` instead of
    lowercase `skill.md` must default to `ignored` when the temp project's
    installed workflow surfaces and runtime docs consistently use uppercase
    `SKILL.md`.
35. **Disabled-command active absence is not an auto-defect**: findings that
    only complain that an intentionally disabled command/skill surface such as
    `parallel` has no active command file, marker, or stub must default to
    `ignored` when the temp project's installed workflow contract says that
    the surface is disabled and removed from the active embedded state, unless
    another installed surface explicitly requires a retained active marker or
    stub.
36. **Template/runtime file separation is not an auto-defect**: findings that
    only complain that an installed document references a task-local runtime
    file which does not yet exist must default to `ignored` when the temp
    project contains the corresponding installed template and the installed
    workflow surfaces explain that the runtime file is generated later during
    the relevant stage. For example,
    `.trellis/workflow-docs/finish-work-checklist-template.md` is the installed
    shared template, while `finish-work-checklist.md` is current-task
    close-out evidence created when a task reaches delivery / finish-work
    readiness. Treat it as actionable only if the template is missing, a task
    has already reached the gate where the runtime file is required and the
    file is absent, or another installed surface explicitly claims the runtime
    file must exist immediately after install.

### Repair Lineage

For cross-task convergence control, a repair run must treat the following as
its lineage identity:

- `source-report` path
- `temp-project-root`
- `trellis-version`

When available, `scan-timestamp` and an explicit `repair-lineage-key` recorded
in earlier repair logs should be used as stronger evidence of the same lineage.
When older repair logs predate those fields, fallback matching may use the
legacy combination above instead of pretending there is no prior lineage.

Normalization rule:

- `repair-lineage-key` must be recorded as
  `normalize(source-report) + "|" + normalize(temp-project-root) + "|" + trellis-version`
- `normalize(path)` means: resolve to an absolute path when available, convert
  path separators to `/`, collapse redundant separators, and strip a trailing
  `/` unless the path is filesystem root
- do not hash the lineage key, and do not include `scan-timestamp` in the key
  itself; `scan-timestamp` remains supporting evidence rather than identity
- when comparing against older logs that only recorded repo-relative paths,
  normalize those stored paths against the current repo root when possible
  before falling back to raw textual comparison

Workflow version bumps do **not** reset lineage by themselves. If the temp
project and report path are the same and the loop is still unfolding across
newly generated same-version reports, the later repair tasks remain part of the
same cross-task convergence problem.

## Inputs

| Input | Required | Default | Meaning |
|-------|----------|---------|---------|
| `report_path` | No | auto-detect | Absolute path to `WORKFLOW_QUESTIONS.md` |
| `temp_project_path` | No | from report | Absolute path to the temp project root |
| `target_focus` | No | empty | Specific WS-NNN IDs to prioritize |
| `--auto` | No | off | After a successful repair run, continue into the current repair task's normal Trellis close-out flow instead of stopping at the repair summary. Eligible commit confirmations, independent scope proof, blocker rules, and post-commit continuation are defined in `Auto Follow-Through Mode` and Step 12.8 below. |

### Report Path Resolution

1. If `report_path` is explicitly provided, use it.
2. Otherwise: run `trellis -v` to get VERSION, construct path
   `/tmp/trellis-{VERSION}-2/WORKFLOW_QUESTIONS.md`.
3. Validate: the file must exist and have `document-type: workflow-questions`
   in frontmatter.
4. If not found: stop as **Blocked / Report Not Found**.

### Repair Authorization Mode

Determine execution mode from the current user request:

- If the user explicitly says to fix, repair, or process real confirmed issues,
  use `authorized-to-repair`.
- If the user asks only to analyze, judge, or produce a plan, use
  `analysis-only`.
- If ambiguous, default to `analysis-only`.
- If the request started as `analysis-only` and the user later explicitly
  accepts all or partial execution in Step 8, switch authorization mode to
  `post-plan-confirmation` for the actual repair execution, repair-log
  recording, and any later auto follow-through decisions.

### Auto Follow-Through Mode

Determine continuation mode from the current user request:

- If the user explicitly includes the literal `--auto` token, use
  `auto-follow-through`.
- Otherwise, use `stop-after-summary`.
- `--auto` changes only what happens after a successful repair run. It does not
  skip correction-plan presentation, repair authorization, post-repair
  verification, or any required Trellis close-out prerequisite.
- When `target_focus` explicitly narrows the repair scope, findings outside that
  focus do not participate in the close-out safety decision for `--auto`.
  If those out-of-focus findings carry higher severity, surface that fact in
  the correction plan so the user can see that auto close-out is proceeding on
  a narrowed repair scope rather than on a fully clean report.
- In `auto-follow-through` mode, if the current repair task reaches a normal
  close-out prompt that asks for its one-shot commit confirmation, including an
  explicit commit-plan/scope confirmation that asks for `ok`/yes-style
  approval while naming proposed commits, unrecognized working-tree files that the
  prompt explicitly frames as part of the current repair task's commit scope,
  or current repair-task artifacts, reply `ok` exactly once and continue.
- `unrecognized working-tree files` means working-tree paths that the close-out
  flow surfaces outside the proposed commit batches and requires the operator
  to include or exclude explicitly; they may be modified or untracked.
- `current repair-task artifacts` means any file that lives inside the current
  repair task directory and is being enumerated by the close-out flow as part
  of the task's commit scope.
- Current repair-task artifacts are acceptable by task-directory membership
  plus explicit current-task prompt scoping; they do not need separate current-
  run output proof.
- The current repair run's independently provable output set applies only to
  out-of-directory files from the skill's other allowed write-scope locations
  when this run can tie them to its own recorded outputs:
  - workflow source files changed by confirmed repair work under
    `docs/workflows/新项目开发工作流/`
  - the current run's own optional `tmp/workflow-issues/NNNN.md` audit shadow
- A file counts as tied to this run's recorded outputs only when the current
  run's repair log records it as a changed, written, or output file for this
  run.
- Exclude reverted files from that independently provable output set; a file
  changed and later reverted during post-repair verification is not a remaining
  current-run output for close-out.
- Reverted files inside the current repair task directory are likewise not
  remaining current-run outputs for close-out, even though the files still live
  in the task directory.
- If the prompt includes working-tree files outside the current repair task's commit
  scope, or the close-out flow does not make that scope explicit enough to
  prove current-task-only scope, stop and report the blocker instead of
  treating it as eligible for auto-confirmation.
- Minimum-acceptable explicit current-task scoping examples include wording
  such as `commit the current repair task changes`, `commit the current repair
  task artifacts`, or `commit the focused repairs` when the rest of the prompt
  stays consistent with that scope.
- Those examples are illustrative rather than exhaustive; semantically
  equivalent phrasing may also qualify when it meets the same explicit
  current-task scope bar.
- Insufficient scoping examples include wording such as `commit these changes`
  or `commit working tree changes` when they do not explicitly frame the scope
  as the current repair task.
- If the prompt's commit-scope or repair-result wording would materially
  misstate the actual repair outcome, such as implying that all attempted fixes
  are verified even though some were reverted, failed, left unresolved, or
  left out by `target_focus`, stop and report the blocker instead of
  auto-confirming it.
- Wording such as `commit the successful repairs` or `commit the current repair
  task changes` may be honest when it does not imply every attempted or every
  reported fix was verified and when the file list remains consistent with that
  narrower claim.
- Bounded auto-confirmation rule: per Step 12.8, reply `ok` exactly once, and
  only for the current repair task's eligible commit confirmation. Here
  `exactly once` means once per close-out run for the first qualifying one-shot
  confirmation prompt, not once per subsequent qualifying prompt inside that
  same run and not once for the entire repair task across later resumed runs.
- If any other interactive prompt appears, stop and report the blocker instead
  of guessing a reply.
- In `auto-follow-through` mode, the post-repair close-out path must re-enter
  the current repair task's normal Trellis flow through the available
  `continue` surface before attempting `finish-work`.
- One close-out run means the full post-repair continuation sequence beginning
  with the first `continue` re-entry for this repair task and ending only when
  the task reaches `finish-work`, `reached-task-close`, or stops with a
  blocker.
- If a blocker ends that sequence and the task is later resumed, treat the
  resumed continuation as a new close-out run rather than as a continuation of
  the previous one.
- Treat a Trellis surface as available in this priority order:
  1. callable platform command surface for the current session
  2. same-session skill surface available in the current project/runtime
  Only when both are unavailable should the surface be treated as missing.
- For `continue`, examples include `trellis-continue` or
  `/trellis:continue` as command surfaces, plus a same-session
  `trellis-continue` skill surface when the platform exposes the behavior as a
  skill instead of a command.
- For `finish-work`, examples include `trellis-finish-work` or
  `/trellis:finish-work` as command surfaces, plus a same-session
  `trellis-finish-work` skill surface when the platform exposes the behavior as
  a skill instead of a command.
- If no Trellis `continue` surface is available in the current
  platform/session, stop and report the blocker. Do not simulate or replace
  `continue`.
- If no Trellis finish-work command surface is available in the current
  platform/session, fall back to the same-session `trellis-finish-work` skill
  surface when it exists.
- If no Trellis `finish-work` surface is available in the current
  platform/session after checking both the command surface and the same-session
  skill surface, stop and report the blocker. Do not simulate or replace
  `finish-work`.
- If the current task is not ready for commit or finish-work, stop after the
  repair summary and report the blocker instead of forcing completion.
- If authorization mode stays `analysis-only` and the user rejects or never
  confirms execution, `--auto` has no effect because no repair run completed.
- If the request also includes `--agent`, ignore that flag for mode expansion:
  repair remains main-session-only and `--auto` does not introduce any
  repair-side agent interaction.

### Optional Legacy Issue-History Shadow

Optional location: `tmp/workflow-issues/`

- A `v4` repair run may still write one numeric Markdown file there as an
  audit shadow.
- `v4` repair decisions must not depend on reading that directory as a
  cross-version memory source.

## Output

Four artifacts:

1. **Correction plan**: presented to the user inline (not written to file
   unless the user requests it). Format: see
   `references/correction-plan-template.md`.
2. **Repair log**: written to the current repair task directory. Format: see
   `references/repair-log-template.md`.
3. **Closure round artifacts**: written to the current repair task directory
   as `closure-round-<N>.md`. Format: see
   `references/closure-round-template.md`.
4. **Issue-history shadow**: optional, written to
   `tmp/workflow-issues/{NNNN}.md` only as an audit shadow. Format: see
   `references/issue-history-template.md`.

If continuation mode = `auto-follow-through`, the skill also continues into the
current task's normal close-out flow after these repair artifacts are written
and echoes that follow-through result inline.

## Workflow

### Step 0: Ensure Report Path and Repair Task Context

1. Resolve the report path (see Path Resolution above).
2. Read enough of the report to derive a short topic:
   - prefer `target_focus` when provided
   - otherwise use the first finding title if available
   - otherwise fall back to `workflow-issues`
3. Sanitize the short topic to a compact kebab-style fragment.
4. Check whether an active task already exists.
5. If there is **no** active task:
   - create a new task titled `workflow-repair-<date>-<short-topic>`
   - start that task
6. If there **is** an active task:
   - create a new task titled `workflow-repair-<date>-<short-topic>`
   - switch to the new repair task
   - do **not** reuse the previous task
7. From this point onward, all task-local artifacts belong to the dedicated
   repair task.
8. If task creation or task start fails: stop as
   **Blocked / Repair Task Setup Failed**.

### Step 1: Locate and Validate Report

1. Read `WORKFLOW_QUESTIONS.md` and validate frontmatter:
   - `document-type` must be `workflow-questions`
   - `protocol` must be `workflow-scan-repair-v4`
   - the shared scan-side report keys must still be present:
     `trellis-version`, `workflow-version`, `workflow-schema-version`,
     `scan-timestamp`, `temp-project-root`, `total-findings`, `p0-count`,
     `p1-count`, `p2-count`
   - required report sections must still exist:
     `## Scan Summary`, `## Analysis Summary`, and `### WS-NNN` finding blocks
   - the `total-findings`, `p0-count`, `p1-count`, and `p2-count` values must
     match the actual finding count and per-severity counts in the report body
   - each finding block must include `Repair Classification`
   - the analysis summary must expose `Confirmed Defects`,
     `Design-Debt Items`, and `Evidence-Gap Items`
2. Read version fields:
   - `trellis-version` from report vs `trellis -v` current
   - `workflow-version` from report
   - `workflow-schema-version` from report
   - current source `WORKFLOW_VERSION`
   - current source `WORKFLOW_SCHEMA_VERSION`
   - temp-project install-record `workflow_version`
   - temp-project install-record `workflow_schema_version`
3. Resolve the temp project root:
   - use `temp_project_path` if provided
   - otherwise read `temp-project-root` from the report
   - if neither is available, derive `/tmp/trellis-{VERSION}-2`
4. Determine repair authorization mode and continuation mode (see the
   `Repair Authorization Mode` and `Auto Follow-Through Mode` sections above).
   If the request also included `--agent`, note once that repair-side
   `--agent` is not supported and that any `--auto` follow-through still runs
   in main-session-only mode.
5. If protocol mismatch: stop as **Blocked / Protocol Version Mismatch**.
6. If report workflow version, temp-project install-record workflow version,
   and current source `WORKFLOW_VERSION` are not all equal: stop as
   **Blocked / Stale Scan Report** and tell the user to re-embed and re-run
   `workflow-scan`.
7. If the workflow versions match but any compared
   `workflow-schema-version` does not match the current source schema version:
   stop as **Blocked / Invalid Embedded State**.
8. If the temp project root does not exist or does not match the report
   context: stop as **Blocked / Temp Project Mismatch**.
9. If the shared keys/sections above are missing, treat the report as a
   scan-side contract failure and stop instead of trying to infer the intended
   fields from alternate names such as `generated_at`, `trellis_version`,
   `temp_project_path`, or `total_findings`.
10. Do not reject or special-case the report based on whether the scan was run
   inline or with `--agent`; only the validated document contract matters.

### Step 2: Parse and Classify Findings

1. Extract all findings from the report. Each finding has: WS-NNN ID, Category,
   Severity Estimate, Repair Classification, Origin, Evidence Layer, Evidence
   list, Temp Project Location, Description, Suggested Investigation.
2. Group findings first by Repair Classification (`confirmed-defect`,
   `design-debt`, `evidence-gap`).
3. Within each repair-classification group, group by Origin
   (`trellis-native` vs `workflow-source`).
4. Within each origin group, sort by Severity Estimate (P0 first, then P1,
   then P2).

### Step 2A: Apply The Default Repair-Eligibility Gate

Before any source-side fix decision is drafted:

1. `confirmed-defect` findings may proceed into the ordinary verification and
   adoption flow.
2. `design-debt` findings must not be treated as adopted-fix candidates by
   default.
   - Keep them at `manual-decision` when a broader design trade-off or explicit
     user scope choice is still needed.
   - Keep them at `ignored` when they are merely optimization ideas and the
     current request is still limited to real confirmed defects.
3. `evidence-gap` findings must not enter source-edit execution.
   - Keep them at `blocked` when more temp-project proof or broader audit
     evidence is needed.
   - Keep them at `manual-decision` only when the missing evidence can be
     closed by an explicit user decision rather than by guessing.
4. The correction plan must make this gating visible instead of silently
   treating every finding as equally repair-ready.

### Step 2B: Run Evidence-File Truth Precheck

Before cross-task lineage escalation or any downstream repair action:

1. For every finding whose `Temp Project Location` points at existing files or
   installed artifacts, read the relevant temp-project contents needed to judge
   whether the reported problem actually exists.
2. Read only the focused source workflow surfaces needed to compare the
   temp-project evidence against the source contract. Prefer exact referenced
   docs, scripts, declarations, and `workflow_assets.py` entries over broad
   directory scans.
3. Apply the repair-side false-positive guardrails during this precheck,
   including retained disabled carriers, `.backup-original` restore surfaces,
   `.codex/skills/` secondary-carrier emptiness, uppercase `SKILL.md`,
   disabled-command active absence, and installed-template versus task-local
   runtime-file separation.
4. If the finding does not survive the temp-project/source cross-check, mark it
   `ignored` immediately and record the concrete evidence source. It must not
   participate in later cross-task lineage escalation.
5. If the relevant temp-project file is missing, ambiguous, or insufficient to
   decide truth, leave the finding as truth-surviving with a tentative
   `blocked` / `manual-decision` / normal-verification disposition, then
   continue the ordinary flow.
6. If all report findings resolve to `ignored` during this precheck:
   - write/summarize the task-local truth judgment and repair log
   - stop with no source edits, no closure round, and no workflow version bump
   - do not escalate the run as broader non-convergence merely because earlier
     repair tasks shared the same lineage

### Step 3: Build Same-Version Repair Context

After Step 2B has separated false alarms from truth-surviving findings:

1. Check the current repair task directory for earlier repair logs or
   closure-round artifacts if this run is being resumed.
2. Treat same-version task-local closure artifacts as the only convergence
   memory surface for this repair task.
3. Do not read old `tmp/workflow-issues/` documents as cross-version repair
   memory in `v4`.
4. Build cross-task repair-lineage context from other repair tasks before
   assuming the remaining truth-surviving findings belong to a fresh ordinary
   run:
   - inspect other repair-task logs under `.trellis/tasks/` and archive
   - prefer exact lineage matches via `repair-lineage-key`
   - when older logs do not yet record `repair-lineage-key`, fall back to
     matching `source-report` + `temp-project-root` + `trellis-version`
   - do not let an intervening workflow version bump hide the same repeated
     temp-project/report lineage
5. If two earlier repair tasks already match the same lineage and one or more
   truth-surviving findings remain, stop ordinary repair execution and escalate
   to audit:
   - mark the run as broader cross-task non-convergence rather than as a fresh
     ordinary repair batch
   - return to a planning / decision checkpoint instead of drafting another
     routine adopted-fix batch
   - do not apply source edits, write closure rounds, or bump the workflow
     version in that ordinary repair attempt
   - report explicitly that the loop crossed task boundaries and now requires
     `workflow-audit`, `trellis-break-loop`, or an equivalent broader closure
     decision
6. Build recurrence notes from current-task same-version evidence only when the
   cross-task lineage gate above does not already stop the remaining
   truth-surviving findings:
   - `first-seen`
   - `repeated-within-current-repair`
   - `no-prior-task-evidence`

### Step 4: Verify Each Finding Against Temp Project and Source Project

For each finding that was not already marked `ignored` / terminal by Step 2B,
re-check against both the temp project and the source project:

1. Read the `Temp Project Location` artifact (if specified) in the temp
   project.
2. Infer the likely source-side repair surface from the finding's temp-project
   evidence and description.
3. Read the relevant source-project file(s) needed to test that hypothesis.
4. For document-reference and post-install-artifact findings whose claim turns
   on wording, filename mismatch, or missing-path shape, inspect only the
   relevant file contents and surrounding wording needed to decide whether the
   finding is real. Do not adopt a finding solely from filename mismatch,
   missing-path existence checks, report title wording, or the scan-side
   `confirmed-defect` label.
5. Compare the temp-project behavior/evidence against the source-side
   declaration and the finding evidence.
6. Cross-reference with workflow-local declarations such as
   `workflow_assets.py` when relevant to the suspected repair path.
7. Identify the root-cause class before deciding:
   - stale declaration drift
   - incomplete installer patch
   - partial cross-file update
   - wrong runtime assumption
   - missing cleanup / residual artifact
   - another clearly named root-cause class
8. Assign a verification result:
   - **Confirmed**: the finding is real in the temp project and the source
     workflow contains a clear, safe repair path → mark as `adopted`
   - **False alarm**: the finding is already fixed, was misidentified, or does
     not survive the temp-project/source cross-check → mark as `ignored`
   - **Blocked**: verification cannot proceed due to missing files, ambiguous
     paths, or external constraints → mark as `blocked`
   - **Needs user input**: the finding is real but the fix involves ambiguity,
     risk, or a trade-off → mark as `manual-decision`
   - **Trellis-native**: the issue is in a trellis-installed artifact, not
     workflow source → mark as `trellis-native`
9. Apply the **negative-optimization guardrail**: if a fix would change
   behavior that currently works correctly (even if the code looks wrong),
   prefer `manual-decision` over `adopted`.
10. If the symptom depends only on a CLI outside the current supported
   three-platform surface (Claude Code / OpenCode / Codex), downgrade the item
   to `ignor

…(truncated)