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

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)