flower-trellis 0.5.2-beta.0 → 0.5.2

package/enhancements/0.6/overrides/patches/skills/trellis-meta/managed-workflow-owners/patch.json

@@ -0,0 +1,106 @@
+{
+  "schemaVersion": 2,
+  "id": "trellis-meta-managed-workflow-owners",
+  "purpose": "managed_workflow_owners",
+  "operations": [
+    {
+      "id": "trellis-meta-managed-workflow-source",
+      "operation": "replace",
+      "targetPolicy": "each-existing",
+      "targets": [
+        { "kind": "skill", "path": ".agent/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".agents/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".claude/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".codebuddy/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".cursor/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".devin/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".factory/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".github/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kilocode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kiro/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".opencode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".pi/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".qoder/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".reasonix/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".trae/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" }
+      ],
+      "selector": { "type": "literal", "source": "workflow-source-selector.md", "expectedMatches": 1 },
+      "content": { "source": "workflow-source-content.md" }
+    },
+    {
+      "id": "trellis-meta-managed-owner-routing",
+      "operation": "replace",
+      "targetPolicy": "each-existing",
+      "targets": [
+        { "kind": "skill", "path": ".agent/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".agents/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".claude/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".codebuddy/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".cursor/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".devin/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".factory/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".github/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kilocode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kiro/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".opencode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".pi/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".qoder/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".reasonix/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".trae/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" }
+      ],
+      "selector": { "type": "markdown-section", "heading": "## Skill Routing" },
+      "baselines": ["owner-routing-baseline.md"],
+      "content": { "source": "owner-routing-content.md" }
+    },
+    {
+      "id": "trellis-meta-managed-state-boundary",
+      "operation": "replace",
+      "targetPolicy": "each-existing",
+      "targets": [
+        { "kind": "skill", "path": ".agent/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".agents/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".claude/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".codebuddy/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".cursor/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".devin/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".factory/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".github/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kilocode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kiro/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".opencode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".pi/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".qoder/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".reasonix/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".trae/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" }
+      ],
+      "selector": { "type": "markdown-section", "heading": "## Workflow-State Prompt Blocks" },
+      "baselines": ["state-boundary-baseline.md"],
+      "content": { "source": "state-boundary-content.md" }
+    },
+    {
+      "id": "trellis-meta-managed-workflow-change-map",
+      "operation": "replace",
+      "targetPolicy": "each-existing",
+      "targets": [
+        { "kind": "skill", "path": ".agent/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".agents/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".claude/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".codebuddy/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".cursor/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".devin/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".factory/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".github/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kilocode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kiro/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".opencode/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".pi/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".qoder/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".reasonix/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" },
+        { "kind": "skill", "path": ".trae/skills/trellis-meta/references/local-architecture/workflow.md", "missing": "skip" }
+      ],
+      "selector": { "type": "markdown-section", "heading": "## Local Modification Patterns" },
+      "baselines": ["workflow-change-map-baseline.md"],
+      "content": { "source": "workflow-change-map-content.md" }
+    }
+  ]
+}

package/enhancements/0.6/overrides/patches/skills/trellis-meta/managed-workflow-owners/state-boundary-baseline.md

@@ -0,0 +1,20 @@
+## Workflow-State Prompt Blocks
+
+The bottom of `workflow.md` can contain state blocks like this:
+
+```text
+[workflow-state:no_task]
+...
+[/workflow-state:no_task]
+```
+
+Hooks choose the right block based on current task status and inject it into the conversation. Common states include:
+
+| State | Meaning |
+| --- | --- |
+| `no_task` | The current session has no active task. |
+| `planning` | The task is still in requirements, research, or context configuration. |
+| `in_progress` | The task has entered implementation and checking. |
+| `completed` | The task is complete and waiting for wrap-up or archive. |
+
+If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.

package/enhancements/0.6/overrides/patches/skills/trellis-meta/managed-workflow-owners/state-boundary-content.md

@@ -0,0 +1,7 @@
+## Workflow-State Prompt Blocks
+
+`workflow.md` may contain paired blocks such as `[workflow-state:no_task]...[/workflow-state:no_task]`. Hooks select the current block and inject it as a one-hop next-action guard.
+
+State blocks are not the owner of complete planning, routing, checking, commit, or archive procedures. Keep detailed semantics in the owner skill/helper and keep the state body small enough to identify the immediate gate. If a managed state policy changes, update its Skill-Garden Patch baseline/content and the owning workflow contract together; do not edit only the deployed block.
+
+Treat the status names actually present in the local workflow and task runtime as authoritative. Do not copy a fixed state or error matrix into this reference.

package/enhancements/0.6/overrides/patches/skills/trellis-meta/managed-workflow-owners/workflow-change-map-baseline.md

@@ -0,0 +1,13 @@
+## Local Modification Patterns
+
+Common changes:
+
+| Goal | Edit point |
+| --- | --- |
+| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
+| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
+| Change the default implementation/check path | Update Phase 2 and skill routing. |
+| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
+| Change platform differences | Update routing descriptions grouped by platform. |
+
+After editing, make the AI reread `.trellis/workflow.md`; do not assume the flow from the old conversation is still valid.

package/enhancements/0.6/overrides/patches/skills/trellis-meta/managed-workflow-owners/workflow-change-map-content.md

@@ -0,0 +1,16 @@
+## Local Modification Patterns
+
+Start from the runtime section, then move to its owner:
+
+| Goal | Durable owner route |
+| --- | --- |
+| Add or reorder a phase | Workflow Patch/source plus every affected owner handoff |
+| Change task creation or scope policy | Request Triage, task-intent helper, and the managed workflow/state Patch |
+| Change planning activation | `trellis-task-brief` and the task-start guard |
+| Change implement/check execution | `trellis-route`; Check-All remains the unified check entry |
+| Change automatic continuation | `trellis-auto-loop` and its runner action contract |
+| Change spec/commit/archive behavior | `trellis-update-spec`, `trellis-push`, or `trellis-finish-work` respectively |
+| Change recovery after interruption | `trellis-continue` and task-progress state |
+| Change one platform adapter | The owning platform file/Patch while preserving the shared workflow contract |
+
+In managed mode, update the source Patch and owner, run the synchronization and compiled-target checks, then reread the final `.trellis/workflow.md`. In native mode, a narrow local edit remains valid when no Plugin ownership claim applies.

package/enhancements/0.6/overrides/patches/skills/trellis-meta/managed-workflow-owners/workflow-source-content.md

@@ -0,0 +1 @@
+`.trellis/workflow.md` is the runtime semantic contract for the current project. It is sufficient to understand what should happen now, but not always sufficient to locate the durable edit point: Skill-Garden-managed sections must be traced to their Patch and workflow owner before modification.

package/enhancements/0.6/overrides/patches/skills/trellis-meta/managed-workflow-owners/workflow-source-selector.md

@@ -0,0 +1 @@
+`.trellis/workflow.md` is the Trellis workflow source of truth inside the user project. An AI does not need Trellis source code to understand how the current project should move tasks forward; this file is enough.

package/enhancements/0.6/overrides/patches/workflow/intent-routing/request-triage/content.md

@@ -1,7 +1,8 @@
 - Infer `discuss`, `inspect`, `direct_edit`, `task_plan`, or `workflow_action` from the whole current request, scope, risk, side effects, active-task state, and latest explicit switch. Do not classify from one keyword alone.
+- Asking for an opinion, expressing discomfort, rejecting a proposal, or asking how something should change is `discuss` unless the current request also explicitly authorizes a concrete edit. Asking to inspect, explain, verify, or locate a cause is `inspect`; read-only findings do not expand into repair authorization.
 - Repair authorization and permission to skip task planning are separate. If repair scope is unknown, use `inspect` first and reclassify from evidence before editing.
-- `direct_edit` requires known, bounded, local, low-risk, reversible scope and simple validation. Permission/authentication/data-scope/security, shared contracts, cross-package/layer or multi-entry behavior, database/migration/configuration/release/external effects, historical regressions, systematic validation, or unknown scope are `task_plan` signals.
-- Before choosing an approach for non-trivial project work, run `python3 ./.trellis/scripts/spec_router.py "<short query describing the intended action>"` when project-local SOPs or conventions may change the correct action. Build the query from the request, intended commands, affected files or systems, package/layer, and domain terms; read high-confidence matches before acting and relevant medium-confidence matches when their path, heading, index description, or reason fits.
+- `direct_edit` requires known, bounded, low-risk, reversible scope, no unresolved design choice, and simple validation. Permission/authentication/data-scope/security, database/migration/release/external effects, or unknown scope remain strong `task_plan` boundaries. Shared contracts, cross-package/layer or multi-entry behavior, configuration, historical regressions, and systematic validation raise the evidence and validation bar; they are risk signals, not automatic `task_plan` outcomes. An exact rollback or mechanically synchronized known change may remain `direct_edit` or `workflow_action` when its behavior, scope, side effects, and validation are already determined.
+- Before choosing an approach for non-trivial project work, run `python3 ./.trellis/scripts/spec_router.py "<short query describing the intended action>"` when project-local SOPs or conventions may change the correct action. Build the query from the request, intended commands, affected files or systems, package/layer, and domain terms. For high-confidence matches, follow `load_strategy`: `full` reads the file, `sections` reads the listed ranges, and `outline` inspects headings before reading relevant ranges; expand beyond that plan only when selected context is insufficient. Apply the same plan to medium-confidence matches only when their path, heading, index description, or reason is clearly relevant.
 - Project Knowledge Discovery applies once per user intent, workflow phase, or decision boundary to Trellis/workflow/config/hooks, CLI behavior, release/publish/deploy/tag, Git history actions, data/migration/rollback, cross-layer design, generated artifacts, and install/sync pipelines. Skip it for pure Q&A, simple read-only inspection, opening local tools, or trivial edits unless project rules may alter the approach.
 - When an active task exists, apply the Active Task Scope Guard before artifact ownership, task routing, or file edits. If new implementation work does not belong to the active task title/brief, stop and choose from the user's intent: create a new task, explicitly include it here and update artifacts first, or proceed untracked without reusing the current task or progress. `task_intent.py` only executes the already-decided create/discard/current-task safety boundary; it does not decide semantic ownership.
 - High-confidence reversible steps proceed without a mechanical task-creation question. Clear complex implementation intent authorizes creating a planning task and entering `trellis-brainstorm`; it never authorizes `task.py start` or implementation.

package/enhancements/0.6/overrides/patches/workflow/task-brief-review/phase-1-activate-content.md

@@ -1,10 +1,10 @@
 #### 1.4 Activate task `[required · once]`
 
-Before changing task status, load `trellis-task-brief`, refresh `<task>/brief.md`, display the full brief in chat, then stop the current turn and wait for planning review confirmation. Earlier implementation intent is not confirmation.
+Before changing task status, load `trellis-task-brief`, refresh `<task>/brief.md`, and display the full brief in chat. Unless `trellis-task-brief` validates an explicit preauthorization for the current final Brief, stop the current turn and wait for planning review confirmation. Ordinary implementation or task-creation intent is not confirmation.
 
 Lightweight tasks need `prd.md`; complex tasks also need `design.md` and `implement.md`. Sub-agent routes require real entries in both JSONL manifests.
 
-Only after the user confirms the displayed brief in a later message, run:
+After a later confirmation, or in the same turn when that explicit preauthorization remains valid, run:
 
 ```bash
 python3 ./.trellis/scripts/task.py start <task-dir>

package/enhancements/0.6/scripts/auto_loop.py

@@ -26,6 +26,7 @@ LEGACY_SCHEMA_VERSION = 1
 DEFAULT_PROFILE = "commit-only"
 MAX_FIX_RECHECK = 3
 MAX_PLANNING_REPAIR = 3
+MAX_ARTIFACT_RECONCILE = 3
 DECISION_LOG_LIMIT = 20
 MANIFEST_AUDIT_TAIL_LIMIT = 3
 TASK_PROGRESS_NOTE_LIMIT = 500
@@ -40,6 +41,7 @@ ALLOWED_TASK_STATUSES = {"planning", "in_progress"}
 VALID_IMPLEMENT_ROUTES = {"inline", "subagent"}
 VALID_CHECK_ROUTES = {"check-all-inline", "check-all-subagent"}
 VALID_CHECK_DEPTHS = {"auto", "light", "full"}
+CHECK_ACTIONS = {"run_check_all", "run_recheck"}
 RECOVERABLE_BLOCK_REASONS = {
     "missing-prd",
     "open-questions",
@@ -936,7 +938,12 @@ def _manifest_payload(state: dict[str, Any], revision: int) -> dict[str, Any]:
     }
 
 
-def _append_manifest_revision(state: dict[str, Any], decision_id: str | None = None) -> dict[str, Any]:
+def _append_manifest_revision(
+    state: dict[str, Any],
+    decision_id: str | None = None,
+    change_source: str | None = None,
+    files: list[str] | None = None,
+) -> dict[str, Any]:
     """追加并激活一个 run manifest revision。"""
     revisions = state.get("manifest_revisions")
     if not isinstance(revisions, list):
@@ -948,6 +955,10 @@ def _append_manifest_revision(state: dict[str, Any], decision_id: str | None = N
     payload = _manifest_payload(state, next_revision)
     if decision_id:
         payload["decision_id"] = decision_id
+    if change_source:
+        payload["change_source"] = change_source
+    if files:
+        payload["files"] = sorted(files)
     encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
     payload["sha256"] = hashlib.sha256(encoded.encode("utf-8")).hexdigest()
     revisions.append(payload)
@@ -1548,7 +1559,7 @@ def _make_item(repo_root: Path, task_ref: str) -> dict[str, Any]:
         "blocked_by": [],
         "owned_dirty": [],
         "decision_count": 0,
-        "attempts": {"fix_recheck": 0},
+        "attempts": {"fix_recheck": 0, "artifact_reconcile": 0},
         "last_failure": None,
         "last_check": None,
         "last_action": None,
@@ -1608,11 +1619,17 @@ def _action(action: str, item: dict[str, Any], extra: dict[str, Any] | None = No
     elif action == "run_implement":
         base["instruction"] = "进入 Phase 2.1 implement route，并执行实现。"
     elif action == "run_check_all":
-        base["instruction"] = "进入 Phase 2.2 check route，按 requested_check_depth 执行统一 Check-All；完成后立即 record + next。"
+        base["instruction"] = (
+            "进入 Phase 2.2 check route，按 requested_check_depth 执行统一 Check-All；DOC 修复需精确声明 "
+            "--doc-remediation-file。record 成功后立即 next；返回 retryable 时先在同一 action 自纠。"
+        )
     elif action == "run_fix":
         base["instruction"] = "根据最近失败摘要修复问题。"
     elif action == "run_recheck":
-        base["instruction"] = "修复后重新执行统一 Check-All，不得低于 minimum_check_depth；完成后立即 record + next。"
+        base["instruction"] = (
+            "修复后重新执行统一 Check-All，不得低于 minimum_check_depth；DOC 修复需精确声明 "
+            "--doc-remediation-file。record 成功后立即 next；返回 retryable 时先在同一 action 自纠。"
+        )
     elif action == "run_spec_update":
         base["instruction"] = (
             "执行 trellis-update-spec 并读取 spec_update_result：no-op/written 时 "
@@ -1626,7 +1643,11 @@ def _action(action: str, item: dict[str, Any], extra: dict[str, Any] | None = No
     return base
 
 
-def _remember_action(item: dict[str, Any], action_data: dict[str, Any]) -> dict[str, Any]:
+def _remember_action(
+    item: dict[str, Any],
+    action_data: dict[str, Any],
+    artifact_sha256: dict[str, str] | None = None,
+) -> dict[str, Any]:
     """记录 runner 已发出的待回写 action。"""
     item["last_action"] = {
         "action": action_data.get("action"),
@@ -1636,6 +1657,8 @@ def _remember_action(item: dict[str, Any], action_data: dict[str, Any]) -> dict[
     for key in ("prd_sha256", "planning_sha256", "handoff_sha256"):
         if action_data.get(key):
             item["last_action"][key] = action_data[key]
+    if artifact_sha256 is not None:
+        item["last_action"]["artifact_sha256"] = artifact_sha256
     item["updated_at"] = _utc_now()
     return action_data
 
@@ -1963,7 +1986,7 @@ def _next_running_v2(repo_root: Path, state: dict[str, Any]) -> tuple[dict[str,
             return item, _remember_action(item, _action("run_check_all", item, {
                 "requested_check_depth": _requested_check_depth(state),
                 "minimum_check_depth": _minimum_check_depth(item, "run_check_all"),
-            }))
+            }), _task_artifact_hashes(repo_root, item))
         if step == "fix":
             attempts = int(item.setdefault("attempts", {}).get("fix_recheck", 0))
             if attempts > MAX_FIX_RECHECK:
@@ -1977,7 +2000,7 @@ def _next_running_v2(repo_root: Path, state: dict[str, Any]) -> tuple[dict[str,
             return item, _remember_action(item, _action("run_recheck", item, {
                 "requested_check_depth": _requested_check_depth(state),
                 "minimum_check_depth": _minimum_check_depth(item, "run_recheck"),
-            }))
+            }), _task_artifact_hashes(repo_root, item))
         if step == "spec_update":
             return item, _remember_action(item, _action("run_spec_update", item))
         if step == "commit_only":
@@ -2294,11 +2317,14 @@ def cmd_retry_blocked(args: argparse.Namespace) -> int:
         item["status"] = "pending"
         item["blocked"] = None
         item["last_action"] = None
-        if reason == "retry-budget-exhausted":
+        if reason in {"retry-budget-exhausted", "artifact-drift"}:
             attempts = item.get("attempts")
             if not isinstance(attempts, dict):
                 attempts = {}
-            attempts["fix_recheck"] = 0
+            if reason == "retry-budget-exhausted":
+                attempts["fix_recheck"] = 0
+            else:
+                attempts["artifact_reconcile"] = 0
             item["attempts"] = attempts
         item["task_status"] = _task_status(repo_root, str(item.get("task")))
         item["updated_at"] = _utc_now()
@@ -3031,6 +3057,175 @@ def _consume_pending_artifact_decision(
     }
 
 
+def _consume_check_doc_remediation(
+    repo_root: Path,
+    state: dict[str, Any],
+    item: dict[str, Any],
+    action: str,
+    raw_files: list[str],
+) -> dict[str, Any] | None:
+    """校验并消费 Check-All 声明的低风险任务文档修复。"""
+    if not raw_files:
+        return None
+    if action not in CHECK_ACTIONS:
+        return {
+            "status": "error",
+            "reason": "doc-remediation-action-not-allowed",
+            "message": "--doc-remediation-file 只允许用于 run_check_all 或 run_recheck。",
+        }
+    if isinstance(item.get("pending_artifact_decision"), dict):
+        return {
+            "status": "error",
+            "reason": "doc-remediation-decision-conflict",
+            "message": "当前 action 同时存在待消费的 decide artifact 授权，不能混用 DOC remediation。",
+        }
+
+    last_action = item.get("last_action")
+    previous = last_action.get("artifact_sha256") if isinstance(last_action, dict) else None
+    if not isinstance(previous, dict):
+        return {
+            "status": "error",
+            "reason": "doc-remediation-baseline-missing",
+            "message": "当前 outstanding check action 没有逐文件 artifact baseline，请重新启动安全流程。",
+        }
+
+    task_dir = _task_dir(repo_root, str(item.get("task") or ""))
+    allowed = {
+        _baseline_key(".", _rel_path(repo_root, task_dir / "implement.md")),
+        _baseline_key(".", _rel_path(repo_root, task_dir / "brief.md")),
+    }
+    declared = {_normalize_record_file(value) for value in raw_files}
+    forbidden = sorted(declared - allowed)
+    if forbidden:
+        return {
+            "status": "error",
+            "reason": "doc-remediation-file-not-allowed",
+            "files": forbidden,
+            "allowed_files": sorted(allowed),
+        }
+
+    current = _task_artifact_hashes(repo_root, item)
+    changed = {
+        key
+        for key in set(previous) | set(current)
+        if previous.get(key) != current.get(key)
+    }
+    if changed != declared:
+        return {
+            "status": "error",
+            "reason": "doc-remediation-files-mismatch",
+            "declared_files": sorted(declared),
+            "changed_files": sorted(changed),
+        }
+
+    planning_hash, handoff_hash = _current_artifact_hashes(repo_root, item)
+    item["planning_sha256"] = planning_hash
+    item["handoff_sha256"] = handoff_hash
+    manifest = _append_manifest_revision(
+        state,
+        change_source="check-doc-remediation",
+        files=sorted(changed),
+    )
+    detail = {
+        "files": sorted(changed),
+        "manifest_revision": manifest["revision"],
+        "manifest_sha256": manifest["sha256"],
+    }
+    _append_item_decision(
+        item,
+        "check_doc_artifacts_rebound",
+        "Check-All 低风险任务文档修复已重新绑定到 manifest",
+        detail,
+    )
+    return detail
+
+
+def _record_artifact_drift(
+    path: Path,
+    state: dict[str, Any],
+    item: dict[str, Any],
+    action: str,
+    args: argparse.Namespace,
+    summary: str,
+    detail: dict[str, Any],
+) -> int:
+    """按 action 风险和预算记录 artifact drift。"""
+    if action not in CHECK_ACTIONS or (
+        args.result == "blocked" and args.failure_type == "artifact-drift"
+    ):
+        item["last_action"] = None
+        _block_item(item, "artifact-drift", summary, detail)
+        _write_state(path, state)
+        return _print({
+            "status": "recorded",
+            "run_id": state.get("run_id"),
+            "task": item.get("task"),
+            "item_status": item.get("status"),
+            "current_step": item.get("current_step"),
+            "summary": _format_summary(state, args),
+        })
+
+    attempts = item.setdefault("attempts", {})
+    attempt = int(attempts.get("artifact_reconcile", 0)) + 1
+    attempts["artifact_reconcile"] = attempt
+    item["last_failure"] = {
+        "action": action,
+        "failure_type": "artifact-drift",
+        "summary": summary,
+        "detail": detail,
+        "failed_at": _utc_now(),
+    }
+    if attempt > MAX_ARTIFACT_RECONCILE:
+        item["last_action"] = None
+        _block_item(
+            item,
+            "artifact-drift",
+            "Check action artifact drift 连续自纠超过 3 次",
+            {**detail, "attempt": attempt, "max_attempts": MAX_ARTIFACT_RECONCILE},
+        )
+        _write_state(path, state)
+        return _print({
+            "status": "recorded",
+            "run_id": state.get("run_id"),
+            "task": item.get("task"),
+            "item_status": item.get("status"),
+            "current_step": item.get("current_step"),
+            "summary": _format_summary(state, args),
+        })
+
+    item["updated_at"] = _utc_now()
+    _append_item_decision(
+        item,
+        "warning",
+        summary,
+        {
+            "action": action,
+            "failure_type": "artifact-drift",
+            "attempt": attempt,
+            "max_attempts": MAX_ARTIFACT_RECONCILE,
+            "detail": detail,
+        },
+    )
+    _write_state(path, state)
+    return _print({
+        "status": "retryable",
+        "reason": "artifact-drift",
+        "run_id": state.get("run_id"),
+        "task": item.get("task"),
+        "item_status": item.get("status"),
+        "current_step": item.get("current_step"),
+        "attempt": attempt,
+        "max_attempts": MAX_ARTIFACT_RECONCILE,
+        "outstanding_action": action,
+        "detail": detail,
+        "instruction": (
+            "不要运行 next；撤回本 action 的误改后重录，或为合法 implement.md/brief.md 修复补充 "
+            "--doc-remediation-file。无法安全归因时用 blocked + artifact-drift 重录。"
+        ),
+        "summary": _format_summary(state, args),
+    })
+
+
 def cmd_record(args: argparse.Namespace) -> int:
     """记录 agent 执行结果。"""
     repo_root = _repo_root()
@@ -3144,24 +3339,47 @@ def cmd_record(args: argparse.Namespace) -> int:
                 "current_step": item.get("current_step"),
                 "summary": _format_summary(state, args),
             })
+        doc_rebind = _consume_check_doc_remediation(
+            repo_root,
+            state,
+            item,
+            action,
+            args.doc_remediation_file,
+        )
+        if isinstance(doc_rebind, dict) and doc_rebind.get("status") == "error":
+            doc_rebind.update({"task": item.get("task"), "action": action})
+            return _print(doc_rebind)
         artifact_rebind = _consume_pending_artifact_decision(repo_root, state, item)
         if isinstance(artifact_rebind, dict) and artifact_rebind.get("unauthorized"):
-            item["last_action"] = None
-            _block_item(
+            return _record_artifact_drift(
+                path,
+                state,
                 item,
-                "artifact-drift",
+                action,
+                args,
                 "planning/handoff artifacts 的变化未被当前 AI 决策文件范围授权",
                 artifact_rebind,
             )
-            _write_state(path, state)
-            return _print({
-                "status": "recorded",
-                "run_id": state.get("run_id"),
-                "task": item.get("task"),
-                "item_status": item.get("status"),
-                "current_step": item.get("current_step"),
-                "summary": _format_summary(state, args),
-            })
+        if action in CHECK_ACTIONS and doc_rebind is None and artifact_rebind is None:
+            last_action = item.get("last_action")
+            previous = last_action.get("artifact_sha256") if isinstance(last_action, dict) else None
+            if isinstance(previous, dict):
+                current = _task_artifact_hashes(repo_root, item)
+                changed = sorted(
+                    key
+                    for key in set(previous) | set(current)
+                    if previous.get(key) != current.get(key)
+                )
+                if changed:
+                    return _record_artifact_drift(
+                        path,
+                        state,
+                        item,
+                        action,
+                        args,
+                        "Check action 发出后 planning/handoff 文件发生未声明变化",
+                        {"changed_files": changed},
+                    )
         if item.get("planning_sha256"):
             try:
                 planning_hash, handoff_hash = _current_artifact_hashes(repo_root, item)
@@ -3179,22 +3397,15 @@ def cmd_record(args: argparse.Namespace) -> int:
                 planning_hash != item.get("planning_sha256")
                 or handoff_hash != item.get("handoff_sha256")
             ):
-                item["last_action"] = None
-                _block_item(
+                return _record_artifact_drift(
+                    path,
+                    state,
                     item,
-                    "artifact-drift",
+                    action,
+                    args,
                     "action 发出后 planning/handoff artifacts 发生未授权变化",
                     drift_detail,
                 )
-                _write_state(path, state)
-                return _print({
-                    "status": "recorded",
-                    "run_id": state.get("run_id"),
-                    "task": item.get("task"),
-                    "item_status": item.get("status"),
-                    "current_step": item.get("current_step"),
-                    "summary": _format_summary(state, args),
-                })
         conflicts = _protected_path_conflicts(state, args.files)
         if conflicts:
             item["last_action"] = None
@@ -3220,6 +3431,8 @@ def cmd_record(args: argparse.Namespace) -> int:
         return _print(check_error)
 
     _record_check_result(state, item, action, args)
+    if action in CHECK_ACTIONS:
+        item.setdefault("attempts", {})["artifact_reconcile"] = 0
     item["last_action"] = None
     if args.result == "ok":
         _advance_after_ok(item, action, args)
@@ -3411,6 +3624,7 @@ def build_parser() -> argparse.ArgumentParser:
     record.add_argument("--failure-type")
     record.add_argument("--summary")
     record.add_argument("--files", nargs="*")
+    record.add_argument("--doc-remediation-file", action="append", default=[])
     record.add_argument("--retained-files", nargs="*")
     record.add_argument("--commit")
     record.add_argument("--commit-message")