docs(agents): 优化 Astra 自主执行、授权与完成规则

.claude/agents/trellis-check.md

@@ -21,7 +21,7 @@ You are already the `trellis-check` sub-agent that the main session dispatched.
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
 - **If the marker is present**: task artifacts, spec, and research files have already been auto-loaded for you above. Proceed with the check work directly.
-- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/check.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.
+- **If the marker is absent**: use the task path and scope in the dispatch brief. Read existing `check.jsonl` entries and task artifacts when present. For taskless work, use the brief and relevant specs directly; missing optional artifacts do not block review.
 
 ## Context
 
@@ -38,11 +38,11 @@ Before checking, read:
 2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
 3. **Check against specs** - Verify code follows guidelines
 4. **Self-fix** - Fix issues yourself, not just report them
-5. **Run verification** - typecheck and lint
+5. **Run verification** - checks proportionate to the affected behavior and project contracts
 
 ## Important
 
-**Fix issues yourself**, don't just report them.
+Fix task-related issues when the dispatch authorizes fixes. A read-only review returns findings without edits. Preserve unrelated changes and do not broaden the task to repair pre-existing failures.
 
 You have write and edit tools, you can modify code directly.
 
@@ -79,9 +79,9 @@ After finding issues:
 
 ### Step 4: Run Verification
 
-Run project's lint and typecheck commands to verify changes.
+Run applicable checks for the affected code or instruction surface; lint/typecheck are not required for prose-only changes.
 
-If failed, fix issues and re-run.
+After authorized fixes, rerun affected checks. Broaden only for a concrete unresolved concern; report persistent environment or unrelated failures rather than retrying indefinitely.
 
 ---
 

.claude/agents/trellis-implement.md

@@ -21,7 +21,7 @@ You are already the `trellis-implement` sub-agent that the main session dispatch
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
 - **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.
-- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/implement.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.
+- **If the marker is absent**: use the task path and scope in the dispatch brief. Read existing `implement.jsonl` entries and task artifacts when present. For authorized taskless work, use the brief and relevant specs directly; do not create missing manifests or repeat planning solely to satisfy context loading.
 
 ## Context
 
@@ -75,7 +75,7 @@ Read the task's prd.md, design.md if present, and implement.md if present:
 
 ### 4. Verify
 
-Run project's lint and typecheck commands to verify changes.
+Run checks applicable to the changed behavior and relevant project contracts. Code changes may require lint/typecheck; prose-only work needs consistency and relevant parser checks. Reuse valid checks on unchanged state and report environmental blockers separately from regressions.
 
 ---
 

.claude/agents/trellis-research.md

@@ -1,7 +1,7 @@
 ---
 name: trellis-research
 description: |
-  Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory.
+  Code and tech search expert. Finds files, patterns, and technical evidence within a bounded research brief. Persists findings when the caller needs durable output; does not modify application code.
 tools: Read, Write, Glob, Grep, Bash, Skill, mcp__*
 ---
 # Research Agent
@@ -10,28 +10,28 @@ You are the Research Agent in the Trellis workflow.
 
 ## Core Principle
 
-**You do one thing: find, explain, and PERSIST information.**
+**Find and explain the evidence needed by the research brief.**
 
-Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session.
+Return concise findings with source locations. Persist expensive-to-recover evidence or an explicitly requested research artifact under the caller's task research directory. A brief read-only lookup can return directly; file count does not establish research quality.
 
 ---
 
 ## Core Responsibilities
 
 1. **Internal Search** — locate files/components, understand code logic, discover patterns (Glob, Grep, Read)
 2. **External Search** — library docs, API references, best practices (web search)
-3. **Persist** — write each research topic to `{TASK_DIR}/research/<topic>.md`
-4. **Report** — return file paths + one-line summaries to the main agent (not full content)
+3. **Persist when useful** — write durable output to `{TASK_DIR}/research/<topic>.md` when requested or needed
+4. **Report** — return key findings, evidence locations, material gaps, and any artifact paths
 
 ---
 
 ## Workflow
 
 ### Step 1: Resolve Current Task
 
-Run `python3 ./.trellis/scripts/task.py current --source` → active task path. If no active task is set, ask the user where to write output; do NOT guess.
+Use the task path in the dispatch brief first; inspect `task.py current --source` only when needed. If no task/output path is provided, return findings to the caller. Ask the supervising agent for a path only if a file deliverable is required; do not interrupt the user for routine dispatch context.
 
-Ensure `{TASK_DIR}/research/` exists:
+When a file deliverable needs it, ensure `{TASK_DIR}/research/` exists:
 
 ```bash
 mkdir -p <TASK_DIR>/research
@@ -47,17 +47,17 @@ Run independent searches in parallel (Glob + Grep + web) for efficiency.
 
 ### Step 4: Persist Each Topic
 
-For each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.
+When durable output is required, write the relevant findings at `{TASK_DIR}/research/<topic-slug>.md`. Combine related topics when clearer and use only applicable sections of the file format below.
 
 ### Step 5: Report to Main Agent
 
-Reply with ONLY:
+Reply with:
 
-- List of files written (paths relative to repo root)
-- One-line summary per file
+- Findings with concrete source paths/lines or URLs
+- Any files written and their purpose
 - Any critical caveats that the main agent needs to know right now
 
-Do NOT paste full research content into the reply. The files are the contract.
+Avoid duplicating lengthy saved artifacts. A concise chat response satisfies a read-only research brief when no durable artifact was requested.
 
 ---
 
@@ -125,13 +125,13 @@ Each `{TASK_DIR}/research/<topic>.md` should follow:
 
 - Provide specific file paths and line numbers
 - Quote actual code snippets
-- Persist every topic to its own file
-- Return file paths in your reply, not the full content
+- Persist durable evidence when useful or requested
+- Return the evidence needed for the caller's next decision
 - Mark "not found" explicitly when searches come up empty
 
 ### DON'T
 
 - Don't write code or modify files outside `{TASK_DIR}/research/`
 - Don't guess uncertain info
-- Don't paste full research text into the reply (files are the deliverable)
+- Don't replace useful findings with a demand to create a task or choose an output path
 - Don't propose improvements or critique implementation (that's not your role)

.claude/commands/trellis/continue.md

@@ -1,56 +1,32 @@
 # Continue Current Task
 
-Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`.
+Resume the first unfinished applicable step in `.trellis/workflow.md`. Preserve the original objective, accepted decisions, and existing authorization. A status or phase change does not require another approval.
 
----
-
-## Step 1: Load Current Context
+## Load Context
 
 ```bash
 python3 ./.trellis/scripts/get_context.py
-```
-
-Confirms: current task, git state, recent commits.
-
-## Step 2: Load the Phase Index
-
-```bash
 python3 ./.trellis/scripts/get_context.py --mode phase
 ```
 
-Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
+Inspect current task, relevant artifacts, git state, and prior authorization. A request to continue an implementation task resumes implementation. If the prior scope was explicitly planning-only or a consequential decision remains unresolved, keep that boundary and continue independent preparation.
 
-## Step 3: Decide Where You Are
+## Route by Remaining Work
 
-`get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
+- No active task: follow request triage; reuse/create a suitable task when useful or proceed inline for taskless work. Do not ask for process consent.
+- `planning` with insufficient goal/acceptance: **1.1**, inspecting evidence before clarifying consequential gaps.
+- `planning` with sufficient scope/acceptance: **1.4**, run `task.py start` and proceed if implementation is authorized. Extra documents are needed only for a concrete purpose; JSONL context is needed only for agents actually consuming it.
+- `in_progress` with implementation unfinished: **2.1**.
+- Implementation done but required verification missing: **2.2**.
+- Verification passed: **3.3** assess useful spec updates, **3.4** perform authorized commits, then **3.5** execute wrap-up.
+- `completed` but not archived: verify acceptance and run authorized finish-work steps. Never archive merely because the status says completed.
 
-- `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
-- `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
-- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (only the seed `_example` row) → **1.3**
-- `status=planning` + required artifacts complete + required jsonl curated or inline mode → **1.4** (ask for start review; only run `task.py start` after user confirms)
-- `status=in_progress` + implementation not started → **2.1**
-- `status=in_progress` + implementation done, not yet checked → **2.2**
-- `status=in_progress` + check passed → **3.3** (spec update) → **3.4** (commit)
-- `status=completed` (rare; usually archived immediately) → archive flow
+Skip applicable steps whose outputs are already valid. Revisit only facts affected by new evidence or scope; do not restart planning or repeat passing checks without cause.
 
-Phase rules (full detail in `.trellis/workflow.md`):
-
-1. Run steps **in order** within a phase — `[required]` steps must not be skipped
-2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough only for lightweight tasks; complex tasks also need `design.md` and `implement.md`.
-3. You may go back to an earlier phase if discoveries require it
-
-## Step 4: Load the Specific Step
-
-Once you know which step to resume at:
+## Execute
 
 ```bash
-python3 ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform claude
+python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>
 ```
 
-Follow the loaded instructions. After each `[required]` step completes, move to the next.
-
----
-
-## Reference
-
-Full workflow and detailed phase steps live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there.
+Load the relevant guidance and keep progressing to the requested outcome. Use available skills/tools; unavailable slash commands or agent types have an inline equivalent. Report an exact blocker only after independent authorized work is done. Local completion, commits, review, merge, and deployment are separate states.

.claude/commands/trellis/finish-work.md

@@ -1,66 +1,45 @@
 # Finish Work
 
-Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command.
+Complete the current request's authorized wrap-up. Check acceptance before task bookkeeping; a session ending or a commit existing does not establish task completion. Apply `.trellis/workflow.md` and AGENTS.md for authorization, branches, and PR review.
 
-## Step 1: Survey current state
+## Step 1: Inspect Current State
 
 ```bash
 python3 ./.trellis/scripts/get_context.py --mode record
+git status --porcelain
 ```
 
-This prints:
+Read the current task's acceptance and verification evidence. Inspect the task-owned diff and actual commits. Leave unrelated tasks alone unless the user asked to clean them up; do not introduce an unsolicited archive-confirmation prompt.
 
-- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
-- **Git status** — quick visual on what's dirty.
-- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
+## Step 2: Finish the Deliverable
 
-If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
+- If implementation or required checks remain, execute the applicable workflow step directly, then return here. Do not send the user away to invoke another command.
+- If task changes are uncommitted and commits are authorized, perform Phase 3.4 directly. Otherwise retain the verified local diff and report commit status separately. An unrequested commit is not a local-delivery gate.
+- Preserve unrelated dirty paths. Inspect mixed files/hunks before classifying ownership; stage only attributable task changes. Ask only if essential ownership cannot be established and the requested next action would affect unknown work.
+- A requested PR/merge/release must satisfy its own authorization and latest-commit review requirements. Pending external work does not erase completed local work, but remains incomplete when included in the requested outcome.
 
-## Step 2: Sanity check — classify dirty paths
+## Step 3: Archive Only Completed Tasks
 
-Run:
+Archive a task only when its own acceptance is met, including merge/release if that task requires them. Archive only the current task or others explicitly included in the requested cleanup. Never archive an unfinished task to clear the active pointer.
 
 ```bash
-git status --porcelain
+python3 ./.trellis/scripts/task.py archive --help
 ```
 
-Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work.
-
-For each remaining dirty path, decide whether it belongs to **the current task** or to **other parallel work** (e.g., another terminal window editing the same repo). Heuristics:
-
-- Paths referenced in the current task's `prd.md` / `implement.jsonl` / `check.jsonl` → current task
-- Paths in code areas matching the task's stated scope, or that you remember editing this session → current task
-- Paths in unrelated areas you have no recollection of touching this session → other parallel work
-
-Then route:
-
-- **Any remaining path looks like current-task work** — bail out with:
-  > "Working tree has uncommitted code changes from this task: `<list>`. Return to workflow Phase 3.4 to commit them before running `/trellis:finish-work`."
-
-  Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
-- **All remaining paths look unrelated** (other parallel-window work) — report them once and continue to Step 3:
-  > "FYI, dirty files outside this task's scope — leaving them for the other window: `<list>`."
-- **Genuinely unsure** — ask the user once: "Are `<list>` this task's work I forgot to commit, or another window's? (commit / ignore)" — then route per their answer.
-
-## Step 3: Archive task(s)
+Inspect script/configuration side effects first. Archive can auto-commit: use a supported no-commit option when requested/needed, or leave the task unarchived if the operation cannot honor current constraints. Run permitted archive operations on a task branch only:
 
 ```bash
 python3 ./.trellis/scripts/task.py archive <task-name>
 ```
 
-At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
+If the user only asks to clear active state, `task.py finish` clears the session pointer without declaring completion. No active task means no archive step; do not manufacture one for this command.
 
-If there is no active task and the user did not confirm any cleanup archives, skip this step.
+## Step 4: Preserve Useful Context and Report
 
-## Step 4: Record session journal
+Record a journal only when it adds useful cross-session context and its side effects are authorized. Inspect `add_session.py --help` and auto-commit settings. Use actual task commit hashes; omit unsupported claims or fabricated hashes. Do not create commits merely to make a journal possible.
 
 ```bash
-python3 ./.trellis/scripts/add_session.py \
-  --title "Session Title" \
-  --commit "hash1,hash2" \
-  --summary "Brief summary"
+python3 ./.trellis/scripts/add_session.py --title "Session Title" --commit "<actual-task-hashes>" --summary "Useful decisions and verified outcome"
 ```
 
-Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
-
-Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
+Remove only this session's disposable temporary files. Report what was delivered, the meaningful verification, and any requested step still blocked. Distinguish local delivery, commits, PR review, merge, deployment, and task archive where relevant. Finish authorized actions yourself rather than ending with a reminder for the user to run this command.