@pennixrv/trellis 0.7.0-beta.5 → 0.7.0-beta.50

package/dist/templates/common/bundled-skills/trellis-session-insight/references/triggering-patterns.md

@@ -1,6 +1,8 @@
 # Triggering Patterns
 
-Verbatim user phrasings that should make an AI reach for `trellis mem`. Calibrate instinct against these — if a user message hits one of these patterns and you do not reach for `mem`, you probably missed an obvious recall.
+Verbatim user phrasings that suggest local conversation recall. Check the intent
+and available current evidence before calling `trellis mem`; these examples do
+not require an unconditional history search.
 
 Patterns are grouped by the *intent* behind the phrasing, not the surface words. The same intent shows up in different languages and registers.
 
@@ -32,7 +34,8 @@ Reach: `trellis mem search "<decision keyword>"` to find the session, then `extr
 
 ## Cross-session continuation
 
-The user resumed work after a gap and the context is implicit.
+The user resumed work after a gap and the context is implicit. Read the active
+task and current files first; use raw history only for missing discussion.
 
 - "Where were we?"
 - "Continue from last time."
@@ -84,6 +87,11 @@ Reach: identify the current task's session id (from `.trellis/.runtime/sessions/
 
 ## Anti-patterns: do NOT reach for `mem` here
 
+- "Find our maintained deployment notes" → the configured native knowledge tool.
+- "Save this reusable result to my notebook" → explicit knowledge write through its owner.
+- "Promote this method into a Skill" → verify the evidence, then the source Skill owner.
+- Current task artifacts already answer the question → use those artifacts.
+
 - "What does this function do?" → read the file.
 - "Why is this test failing?" → read the test output and the file.
 - "What's the right pattern for X in our codebase?" → grep / read spec files.

package/dist/templates/common/commands/continue.md

@@ -4,31 +4,59 @@ Resume work on the current task — pick up at the right phase/step in `.trellis
 
 ---
 
-## Step 1: Load Current Context
+## Step 1: Reuse the Checkpoint; Fill Only Missing Context
+
+If the current conversation or compaction summary already supplies project root,
+task, phase, authorization and pending action, resume that action directly. Keep
+running tool handles and completed work; skip the queries below and Steps 2–4
+unless a specific fact or instruction is missing/conflicting. A plain continue
+does not require startup, Git/status/history or formal handoff validation.
+
+After compaction, never repeat or re-answer the last consumed user input from
+before compaction. Continue from the actual checkpoint. Handle genuinely new
+post-compaction input normally.
+
+For a fresh session, changed target, missing/conflicting facts or explicit
+inspection, use the minimum query that resolves the gap:
 
 ```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
+{{PYTHON_CMD}} ./.trellis/scripts/task.py current --json
 ```
 
-Confirms: current task, git state, recent commits.
+Use full `get_context.py` only when its identity/project/Git overview is needed.
+Protected native writes still enforce identity, binding and ownership through
+their owner; this shortcut never bypasses those checks.
+
+Before routing by status, distinguish identity from task binding. A non-null
+`session_source` confirms available identity; only `source=session:...` confirms
+a direct task binding. For `unbound` / `unbound_ambiguous`, review existing task
+artifacts and select by the user's explicit intent. Exit code 1 for ambiguity
+does not mean identity is absent. Do not guess, duplicate tasks, invent identity,
+or edit runtime pointers. Return a planning candidate to the planning gates below;
+use native `task.py select <task>` to bind planning context after any required
+Channel drain; use `task.py start` only when its activation contract permits it.
+An eligible `analysis_only` candidate remains in planning without start.
+If `session_source` is null, report unavailable identity separately.
 
-## Step 2: Load the Phase Index
+## Step 2: Load the Phase Index Only When Needed
 
 ```bash
 {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
 ```
 
-Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
+Run only when the phase or routing rule is missing; otherwise reuse it.
 
 ## Step 3: Decide Where You Are
 
 `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.
 
-- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → complete the PRD's bounded evidence work, verify its acceptance criteria and no-change boundary, then commit task artifacts and archive directly. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
+- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → verify the PRD's bounded evidence deliverable and protected-target no-change boundary, then complete the evidence and archive directly regardless of complexity or cross-owner scope. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
 - `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
+- `status=planning` + a recorded `decision-needed` or unsealed decision chain → return to `pennix-decision-grill` only for a change-bearing decision or a user-owned choice that materially defines the requested research scope or method; research recommendations and open product choices alone do not trigger the gate.
+- `status=in_progress` + a material unresolved decision → record the reason and run `task.py replan <task> "<reason>"`; do not ask a native question during implementation.
 - `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 (empty, or only a legacy `_example` placeholder 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=planning` + required artifacts complete + required jsonl curated or inline mode → for change-bearing work, run the Planning Seal closure pass, then **1.4**; require later explicit implementation approval for the current sealed revision and use native plan seal/approve/start. `analysis_only` work completes its evidence and archives without this path. A replan invalidates change-bearing approval; minor progress edits do not.
 - `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)
@@ -42,7 +70,7 @@ Phase rules (full detail in `.trellis/workflow.md`):
 
 ## Step 4: Load the Specific Step
 
-Once you know which step to resume at:
+Only if the identified step's instructions are missing:
 
 ```bash
 {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform {{CLI_FLAG}}

package/dist/templates/common/commands/finish-work.md

@@ -16,7 +16,7 @@ This prints:
 - **Git status** — quick visual on what's dirty.
 - **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
 
-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 `--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; archive the current task only after the acceptance check below.
 
 ## Step 2: Sanity check — classify dirty paths
 
@@ -44,13 +44,28 @@ Then route:
   > "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.
 
+### Acceptance check before archive
+
+Compare the task's PRD-defined endpoint and required acceptance criteria with
+actual evidence in its records and verification results. Reuse valid results;
+state which checks ran, did not run, were blocked, or had limited coverage.
+Installation, publishing, project updates or live execution require their own
+evidence when they are part of the authorized endpoint; static readiness or
+isolated tests cannot stand in for them. Clean bootstrap/cleanup is conditional
+on the task goal and authorization, not an automatic finishing step.
+
+If a required criterion is unmet or lacks sufficient evidence, return to the
+corresponding work and leave the task unarchived. Reporting a limitation does
+not satisfy a required criterion. Keep this conclusion in the existing task
+record; do not add a separate acceptance receipt.
+
 ## Step 3: Archive task(s)
 
 ```bash
 {{PYTHON_CMD}} ./.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.
+Archive the current active task and any extra tasks confirmed in Step 1 only when their required acceptance has been verified. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
 
 If there is no active task and the user did not confirm any cleanup archives, skip this step.
 

package/dist/templates/common/commands/start.md

@@ -2,6 +2,12 @@
 
 Initialize a Trellis-managed development session. This platform has no session-start hook, so manually load the equivalent compact context by following these steps.
 
+Run this initialization once when project context is genuinely missing or the
+target project changes. Existing session context and a sufficient compaction
+summary count as loaded context. An ordinary continue or new task in the same
+known project resumes the pending action without repeating these steps. For
+partial missing/conflicting facts, query only the needed owner evidence.
+
 ---
 
 ## Step 1: Current state
@@ -39,11 +45,12 @@ From Step 1 you know the current task and status. Check the task directory:
 - **Active task with `task.json.meta.delivery_mode = "analysis_only"`** → keep `planning`, complete the PRD's bounded evidence work, then verify the no-change boundary, commit task artifacts, and archive directly. Do not run `task.py start`; any protected-target change needs a separate change-bearing task.
 - **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
 - **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Load the relevant Phase 1 step detail before `task.py start`.
+- **Existing task selected by explicit intent but not bound** → use native `task.py select` for context only. Drain already dispatched Channel units before a real task switch. Planned/change-bearing start requires native plan seal and matching later approval for this task's current material revision; selecting or recovering context does not approve implementation.
 - **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
   ```bash
   {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
   ```
-- **No active task** → classify first. For simple conversation / small task, ask only whether this turn should create a Trellis task. For complex work, ask whether you may create a Trellis task and enter planning. If the user says no, skip Trellis for this session.
+- **No active task** → classify first. Simple conversation needs no task. Bounded direct work uses the workflow's direct path without a mandatory task-creation question. Complex work creates a task and enters planning when authorized; ask only if the necessary authorization is missing.
 
 ---
 

package/dist/templates/common/skills/brainstorm.md

@@ -6,12 +6,26 @@ A request to build, implement, fix, refactor, or "go ahead" is not approval to l
 
 For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final planning summary described below.
 
-While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
+Keep the task in planning while a user-owned choice needed to define the requested work remains unresolved. For `analysis_only`, findings, recommendations, and open product options do not block evidence work or require a sealed decision chain. For other work, screen consequential user-owned choices with `pennix-decision-grill`, including a single choice; it owns progressive decision method, not task lifecycle. Do not implement or run `task.py start` until change decisions are sealed and approved.
+
+## Idea-to-Plan Route
+
+When the input is an idea, suspected gap, review finding, or loosely stated improvement, route it through the smallest complete chain:
+
+1. State the user outcome and the concrete problem or gap in one sentence.
+2. Separate repository-answerable facts from user-owned choices; inspect the repository, task history, and applicable specs before asking about facts.
+3. Record the current evidence and its recovery point in the natural task artifact: research matrix for research, PRD/design for planning, and the diff or Git history for code.
+4. Screen only the choices that change scope, owner, risk, public behavior, release, or acceptance through `$pennix-decision-grill`.
+5. Define observable acceptance, boundaries, rollback, and the next dependency-ready action; then use the normal seal and approval gate.
+
+An issue discovered while doing this work is not automatically part of the task. Compare its owner, target, risk, and acceptance with the sealed scope. Record every consequential finding and ask whether it should be included; a same-owner, reversible, low-risk correction may use the existing in-progress addition rule. Otherwise use `task.py replan` and reseal before dependent implementation.
 
 ## Analysis-Only Exception
 
 When `task.json.meta.delivery_mode = "analysis_only"` exactly and the PRD names a bounded evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems, task-creation consent authorizes that evidence work. Do not require a second planning approval or run `task.py start`: perform the declared research, audit, or design work while status remains `planning`, record the evidence, verify acceptance criteria and the boundary, commit task artifacts, and archive directly. If the evidence recommends a protected-target change, record it and create a separate change-bearing task before doing it.
 
+This route remains eligible for bounded evidence work regardless of complexity, cross-owner scope, multiple evidence units, or whether conclusions include recommendations or unresolved product choices. Record findings and recommendations in task artifacts; do not change protected targets, deploy, release, alter credentials, or mutate external systems. The initial request authorizes the requested main-session research, so do not require a second implementation approval, Planning Seal, or `task.py start` to complete it. If the user requests independent subnode evidence, freeze its dispatch plan in the task first and obtain explicit approval of that plan before any spawn/send; this approval authorizes only the listed evidence dispatch. If implementation is later requested, create or replan a change-bearing task and use its normal Planning Seal and implementation approval gates.
+
 All other tasks follow the planning and implementation approval gates below.
 
 ## Non-Negotiable Evidence Rule
@@ -24,6 +38,19 @@ Do not ask the user to confirm facts that the repository can answer. Ask only fo
 
 Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
 
+## Evidence Units For Read-Heavy Work
+
+When research, audit, review, or investigation is too large to leave one independently useful conclusion in the current bounded session, split it into evidence units. Each unit must have one question or scope, a minimal evidence range, a destination artifact, and a stop condition; write its facts, conclusion or blocker, unknowns, and recovery point before starting another unit. Size units so one normal context window can finish and persist one useful result; do not promise an exact token or time limit. Routine navigation and transient tool output do not need an artifact. Create a child task only when the unit has an independent owner, lifecycle, and acceptance contract.
+
+Persist the unit-to-point mapping in this task's existing plan/matrix before
+dispatch. Include workload rationale, dependencies, minimal evidence, shared
+context, and per-point delivery. Combine points only when each is quick/simple
+and they are obviously related; explain the grouping and bounded total workload.
+Complex or lengthy points need separate units or further splitting. Slots and
+owner domains do not determine unit count. Explicit independent subnodes use
+`trellis-channel`'s unit-plan and multi-target procedure; planning itself does
+not authorize dispatch.
+
 ---
 
 Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
@@ -54,18 +81,21 @@ Use a concise title from the user's request. Both the title and `--description`
    - product intent still needed from the user
    - scope or risk decisions still needed from the user
    - likely out-of-scope items
-4. If a user-owned decision remains, ask the single highest-value question, include your recommendation and trade-off, then stop. Do not perform implementation work in the same turn.
-5. After each user answer, update `prd.md`, recompute the decision inventory, and repeat from step 2.
-6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
-7. Run the requirement convergence gate, then the PRD convergence pass.
-8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
-9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If the artifacts change materially after approval, repeat the final review.
+4. Screen genuine user-owned decisions; resolve repository facts and settled local details directly. Use `pennix-decision-grill` progressively: dependency readiness first, then impact/priority; ask only the coherent current frontier and reassess after answers. For bounded research, ask only when its requested scope or method depends on the choice; findings and recommendations need no implementation decision.
+5. If the user requests independent subnode evidence, first freeze the dispatch plan in the task: question, evidence-unit mapping and grouping rationale, brief scope/stop conditions/destinations, concurrency and FIFO refill/acceptance method. Obtain the user's explicit approval of that frozen plan before any spawn/send. This approval covers only the listed evidence dispatch; material changes to units, scope, method, owner, risk, or acceptance require reapproval. Main-session evidence work may continue while dispatch approval is pending.
+6. When a needed answer returns, persist it and the affected dependencies, recheck evidence, and continue the same task. Before substantial evidence work, save the current decision, known answers, missing facts, return point and stop condition. Use bounded local/web evidence or explicitly approved independent subnodes; they establish facts, not user decisions. An empty ready frontier can mean missing evidence, not planning closure. Do not create a second lifecycle for the same decision chain.
+7. For `analysis_only`, record and verify the declared evidence and no-change boundary in planning; do not require `design.md`, `implement.md`, a Planning Seal, implementation approval, or `task.py start` merely because the research is complex.
+8. For change-bearing work, resolve material decisions, create/update complex-task artifacts, run the requirement convergence and PRD passes, then close and present the Planning Seal. Stop before implementation. Only a later explicit approval for this task's current sealed revision authorizes native plan approval and `task.py start`. Initial requests, parent-task approvals, and design answers do not qualify. Material changes require `task.py replan` and approval of its newly sealed revision; progress and wording edits do not.
+
+When changing the active task only for planning, use native `task.py select`,
+not start. `create --no-start` intentionally preserves the old pointer. Follow
+the Channel drain procedure before switching with live evidence workers.
 
 Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
 
 ## Question Rules
 
-Ask only one question per message.
+Ask one to three independent, coherent, ready decisions per round, ordered by impact. One high-priority decision is sufficient even when other choices exist; never fill a batch just to reach a count. Dependent questions wait for the preceding answer, and later rounds may discover new branches. Use the host's blocking native question tool; never choose by elapsed time or an unanswered required decision.
 
 Each question must include:
 
@@ -78,9 +108,7 @@ Do not ask process questions such as whether to search, inspect files, or contin
 
 Recommendations are not default selections. Never choose a recommended product decision on the user's behalf merely because the user asked for implementation.
 
-Do not manufacture clarification questions when the request and repository evidence already resolve every decision. In that case, proceed directly to the final planning summary, which still requires a subsequent explicit approval.
-
-The final review is a required phase-transition gate, not a prohibited process question. Task-creation consent, the initial implementation request, and approval given before the latest final summary do not satisfy this gate.
+Do not manufacture clarification questions when the request and repository evidence already resolve the scope and method. For `analysis_only`, proceed with the requested evidence work; no final implementation review or approval is required. The final review and subsequent approval are phase-transition gates for change-bearing implementation only.
 
 ## Thinking Framework: First Principles Analysis
 
@@ -136,10 +164,12 @@ Before final review, verify all of the following:
 - blocking open questions are empty
 - technical unknowns are researched or explicitly deferred without changing MVP behavior
 
-Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evidence inspection, requirement convergence, final review, or fresh implementation approval.
+For `analysis_only`, keep the task PRD bounded to evidence and the protected-target no-change boundary; it may omit `design.md` and `implement.md` and does not need an implementation review or approval. Change-bearing tasks retain their applicable evidence, convergence, final review, and fresh implementation approval gates.
 
 The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
 
+For change-bearing work, the Planning Seal closure pass reconciles task artifacts, targets, branches, dependencies, release, validation, rollback, dynamic facts, and material decisions before implementation; unresolved implementation ambiguity invalidates the seal. This closure pass is not an eligibility or completion gate for `analysis_only` evidence work.
+
 ## Artifact Rules
 
 `prd.md` records requirements and acceptance:
@@ -187,15 +217,12 @@ After the pass, read `prd.md` top to bottom and verify that no fact is repeated
 
 ## Quality Bar
 
-Before declaring planning ready:
+Before declaring change-bearing planning ready:
 
-- `prd.md` contains testable acceptance criteria.
-- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.
-- Repository-answerable questions have already been answered through inspection.
-- Blocking open questions are empty.
-- Complex tasks have `design.md` and `implement.md`.
-- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
-- The latest final planning summary has been presented to the user.
-- In a subsequent message, the user explicitly approved that summary for implementation.
+- `prd.md` contains testable acceptance criteria and has passed the PRD convergence pass.
+- Repository-answerable questions have been answered; blocking implementation questions are resolved.
+- Complex change-bearing tasks have `design.md` and `implement.md`; sub-agent-dispatch implementation tasks have curated manifests.
+- The Planning Seal and final summary cover the implementation target, validation, and rollback.
+- The user subsequently approved this task's current sealed plan.
 
-Do not start implementation merely because the user originally asked for implementation.
+For `analysis_only`, verify the declared evidence deliverable and protected-target no-change boundary, then proceed to complete the research in planning without an implementation summary approval. Do not start change-bearing implementation merely because the user originally requested it.

package/dist/templates/common/skills/break-loop.md

@@ -8,6 +8,8 @@ When debug is complete, use this for deep analysis to break the "fix bug -> forg
 
 Analyze the bug you just fixed from these 5 dimensions:
 
+Start with a short causal loop before filling the five dimensions: expected behavior → observed failure → discriminating evidence → root cause → prevention check. If the failure is not reproduced, label the uncertainty and do not promote a plausible explanation to a confirmed cause.
+
 ### 1. Root Cause Category
 
 Which category does this bug belong to?
@@ -169,16 +171,10 @@ Never express binary certainty when evidence is incomplete. Use "most likely", "
 
 ## After Analysis: Immediate Actions
 
-**IMPORTANT**: After completing the analysis above, you MUST immediately:
-
-1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
-   - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
-   - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
-   - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
-   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
+Record verified findings in the active task. Update a spec only when the finding establishes a reusable, executable contract owned by that project and the current task authorizes the change. Routine progress and one-off observations stay in task records.
 
-2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
+Consumer projects do not sync specs into Trellis templates. When working on the Trellis source itself, update a corresponding template under `packages/cli/src/templates/markdown/` only if it exists and the change is intended for generated consumers. Keep root coordination contracts in their owner; do not copy them into component specs.
 
-3. **Commit the spec updates** - This is the primary output, not just the analysis text
+Follow the task's existing commit and release process. This skill does not independently authorize source changes, commits, publication, or new tickets.
 
-> **The analysis is worthless if it stays in chat. The value is in the updated specs.**
+When the analysis reveals a neighboring defect, compare its owner, target, risk, and acceptance with the current task. Record the finding and ask for inclusion when it changes material scope; only a same-owner, reversible, low-risk correction may continue under the existing in-progress addition rule. This keeps root-cause learning broad while keeping implementation scope explicit.

package/dist/templates/common/skills/check.md

@@ -1,6 +1,6 @@
 # Code Quality Check
 
-Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+Verify the task's affected behavior against the current implementation, applicable specs, and acceptance criteria.
 
 ---
 
@@ -11,6 +11,11 @@ git diff --name-only HEAD
 git status
 ```
 
+Use the diff as the entry point. Follow the affected behavior through existing
+implementation, necessary callers, configuration, tests, documentation and
+generated consumers. Expand when evidence of an existing problem could affect
+the task result; do not default to a whole-module or whole-repository audit.
+
 ## Step 2: Read Task Artifacts and Applicable Specs
 
 Read the current task artifacts in order:
@@ -35,6 +40,12 @@ Read the specific guideline files referenced — the index is a pointer, not the
 
 Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
 
+Choose checks by changed behavior and risk. When the task includes installation,
+release or a live workflow, verify its normal entry and required endpoint;
+isolated tests do not prove those endpoints. A clean bootstrap or destructive
+cleanup applies only when required by the task and authorized. Reuse valid
+results and distinguish checks run, not run, blocked, or limited.
+
 ## Step 4: Review Against Checklist
 
 ### Code Quality
@@ -47,9 +58,9 @@ Run the project's lint, type-check, and test commands. Fix any failures before p
 
 ### Test Coverage
 
-- [ ] New function → unit test added?
-- [ ] Bug fix → regression test added?
-- [ ] Changed behavior → existing tests updated?
+- [ ] Non-trivial behavior and material risks covered by meaningful checks?
+- [ ] Bug fix has a regression that reaches the failing path?
+- [ ] Existing tests updated when their behavior changed, without duplicating trivial implementation?
 
 ### Spec Sync
 
@@ -62,7 +73,7 @@ Run the project's lint, type-check, and test commands. Fix any failures before p
 - [ ] Any tidying of code the task did not require?
 - [ ] Any abstraction, config or extension point added for a case that does not exist yet?
 - [ ] Any speculative fallback for a state that cannot occur?
-- [ ] Any file changed that the acceptance criteria do not mention?
+- [ ] Each changed file serves the task or a necessary consumer, even if the AC do not name it individually?
 - [ ] Any workaround added at the caller instead of a fix where the behavior actually lives?
 
 ## Step 5: Cross-Layer Dimensions (if applicable)
@@ -100,7 +111,25 @@ Skip this step if your change is confined to a single layer.
 
 Report every violation you find. Then:
 
+Verify important findings against current requirements, actual sources, callers
+and relevant counterevidence before prioritizing. Separate observed facts from
+inferences; a rule's presence, a zero call count or an intentional behavior is
+not by itself proof of a defect. Record task-relevant findings and their effect
+on acceptance; new consequential scope choices follow the task's decision gate.
+
 - Mechanical and local (lint nit, missing type, wrong import, dead branch, failing assertion) → fix in place, then re-run project checks.
 - Design or judgment (naming a shared concept, moving a module boundary, changing a public interface, reassigning where behavior lives) → record the evidence and your recommendation, and stop. Do not rewrite it silently.
 
 If a fix would touch files outside the current task's scope, say so and stop instead of widening the change.
+
+## Step 7: Close the Review Loop
+
+For each material finding, preserve the chain from evidence to action:
+
+1. State the observed behavior, source or test evidence, and confidence.
+2. Identify the affected acceptance criterion, owner, target, and risk.
+3. Classify the finding as an in-scope correction, a separately owned issue, or a consequential scope change.
+4. Fix only in-scope mechanical corrections. Record separately owned or consequential findings and use the task's decision/replan gate before dependent work.
+5. Re-run the smallest check that exercises the finding, then re-read the affected acceptance criteria and final diff.
+
+Do not silently absorb newly discovered work because it is nearby. A user-requested addition can remain in the current task only when the existing same-owner, reversible, low-risk rule applies; otherwise ask through the normal decision route and update the sealed plan before implementation.

package/dist/templates/copilot/hooks/session-start.py

@@ -244,12 +244,10 @@ def _get_task_status(trellis_dir: Path, hook_input: dict) -> str:
         )
 
     task_json_path = task_dir / "task.json"
-    task_data: dict = {}
-    if task_json_path.is_file():
-        try:
-            task_data = json.loads(task_json_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, PermissionError):
-            pass  # Optional task metadata; fall back to generic status.
+    from common.io import read_json_checked
+    task_data, _reason = read_json_checked(task_json_path)
+    if task_data is None or not isinstance(task_data.get("status"), str) or not task_data["status"].strip():
+        return f"Status: TASK_ERROR\nTask: {task_ref}\nNext: Repair the existing task record through its owner before continuing; do not create a replacement task."
 
     task_title = task_data.get("title", task_ref)
     task_status = task_data.get("status", "unknown")
@@ -384,13 +382,15 @@ def _build_compact_current_state(
     active = _resolve_active_task(trellis_dir, hook_input)
     if active.task_path:
         task_dir = _resolve_task_dir(trellis_dir, active.task_path)
-        status = "unknown"
+        status = "task_error"
         task_json = task_dir / "task.json"
         if task_json.is_file():
             try:
                 data = json.loads(task_json.read_text(encoding="utf-8"))
                 if isinstance(data, dict):
-                    status = str(data.get("status") or "unknown")
+                    value = data.get("status")
+                    if isinstance(value, str) and value.strip():
+                        status = value
             except (json.JSONDecodeError, OSError):
                 pass  # Optional task metadata; fall back to generic status.
         lines.append(f"Current task: {_repo_relative(repo_root, task_dir)}; status={status}.")
@@ -419,19 +419,19 @@ def _build_compact_current_state(
     return "\n".join(lines)
 
 
-def _extract_range(content: str, start_header: str, end_header: str) -> str:
+def _extract_range(content: str, start_header: tuple[str, ...], end_header: tuple[str, ...]) -> str:
     """Extract lines starting at `## start_header` up to (but excluding) `## end_header`."""
     lines = content.splitlines()
     start: "int | None" = None
     end: int = len(lines)
-    start_match = f"## {start_header}"
-    end_match = f"## {end_header}"
+    start_matches = {f"## {header}" for header in start_header}
+    end_matches = {f"## {header}" for header in end_header}
     for i, line in enumerate(lines):
         stripped = line.strip()
-        if start is None and stripped == start_match:
+        if start is None and stripped in start_matches:
             start = i
             continue
-        if start is not None and stripped == end_match:
+        if start is not None and stripped in end_matches:
             end = i
             break
     if start is None:
@@ -483,7 +483,7 @@ def _build_workflow_toc(workflow_path: Path) -> str:
         "",
     ]
 
-    phases = _extract_range(content, "Phase Index", "Phase 1: Plan")
+    phases = _extract_range(content, ("阶段索引（Phase Index）", "Phase Index"), ("阶段一：规划（Phase 1: Plan）", "Phase 1: Plan"))
     if phases:
         out_lines.append(_strip_breadcrumb_tag_blocks(phases).rstrip())
 
@@ -499,11 +499,15 @@ def main() -> None:
         hook_input = json.loads(sys.stdin.read())
         if not isinstance(hook_input, dict):
             hook_input = {}
-        project_dir = Path(_normalize_windows_shell_path(hook_input.get("cwd", "."))).resolve()
+        raw_cwd = hook_input.get("cwd")
+        project_dir = Path(_normalize_windows_shell_path(raw_cwd if isinstance(raw_cwd, str) and raw_cwd else ".")).resolve()
     except (json.JSONDecodeError, KeyError):
         hook_input = {}
         project_dir = Path(".").resolve()
 
+    project_dir = next((candidate for candidate in (project_dir, *project_dir.parents) if (candidate / ".trellis").is_dir()), None)
+    if project_dir is None or not (project_dir / ".trellis" / "scripts" / "common" / "active_task.py").is_file():
+        return
     configure_project_encoding(project_dir)
 
     trellis_dir = project_dir / ".trellis"