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

package/dist/templates/common/bundled-skills/trellis-channel/references/progress-debugging.md

@@ -127,11 +127,15 @@ wait command starts, capture a barrier before that operation and pass it back:
 ```bash
 BARRIER="$(trellis channel barrier T)"
 # spawn or trigger work that may emit a terminal event
-trellis channel wait T --as main --from check --kind done,error \
+trellis channel wait T --workers check \
   --after-seq "$BARRIER" --timeout 15m
 ```
 
-It wakes on:
+Worker mode waits for a lifecycle transition to terminal, including
+supervisor-authored killed/error events. Ordinary adapter errors and peer turn
+completion remain nonterminal. Use `--workers check,check-cx --all` for a group.
+
+The separate event-filter mode wakes on:
 
 - `message`
 - `done`
@@ -142,10 +146,10 @@ It wakes on:
 Useful filters:
 
 ```bash
-trellis channel wait T --as main --from check --kind done --timeout 15m
-trellis channel wait T --as main --from check,check-cx --kind done --all --timeout 15m
+trellis channel wait T --from check --kind done --timeout 15m
+trellis channel wait T --from check,check-cx --kind done --all --timeout 15m
 trellis channel wait T --as worker --kind message --timeout 1h
-trellis channel wait T --as main --thread release-note --action status --timeout 10m
+trellis channel wait T --thread release-note --action status --timeout 10m
 ```
 
 Exit codes: `0` matched, `124` timeout, `1`/`2` errors. On `wait --all`

package/dist/templates/common/bundled-skills/trellis-channel/references/subnode-work.md

@@ -10,6 +10,13 @@ lifecycle, and the final result. A subnode owns one evidence report and its own
 append-only worklog. This is a behavioral contract; do not add `--sandbox` or
 claim that path restrictions enforce it.
 
+Keep credentials out of briefs, reports, worklogs and Channel messages. The artifact
+validator rejects known private-key/token, Bearer and explicit credential-assignment
+syntax; it does not recognize arbitrary secret values. Channel protocol messages keep
+their original bytes for delivery in private local storage. Operator message views,
+error/progress persistence and logs redact known credential syntax or omit raw worker
+content; this is not general-purpose secret detection or private-path anonymization.
+
 ## Artifact Setup
 
 Before spawning, the coordinator must use an active task (`planning` or
@@ -20,7 +27,26 @@ dependencies, stop conditions, deadline, and `channel_ref`. Set `retry_of`
 only for an explicit manual retry and `counter_of` only for intentional
 counterwork. A retry names an existing, different subnode in the same task and
 `work_id`; counterwork may be initialized independently. The helper supplies
-the immutable task identity and report path.
+the immutable task identity and report path. New units also require `unit_plan`:
+
+```json
+{
+  "unit_plan": {
+    "plan_ref": ".trellis/tasks/09-07-example/design.md#evidence-units",
+    "sizing_rationale": "One bounded dependency inspection with a separately reviewable result."
+  }
+}
+```
+
+The reference must identify an existing regular Markdown document inside this
+task. For multiple scope items, add `grouping_rationale` explaining why every
+item is quick/simple, obviously related, and uses shared context while retaining
+separate conclusions. Record the actual scope mapping and evidence in the task
+plan before initializing briefs; owner domains and slot counts do not determine
+unit counts. Complex or lengthy points need separate units or further splitting.
+The helper checks structure, not the truth of the sizing judgment. Historical
+brief/report readers remain compatible; new init and queue admission require
+the unit plan.
 
 ```bash
 TASK=.trellis/tasks/09-07-example
@@ -50,12 +76,15 @@ and its status; the Codex supervisor projects that reply into the durable
 Channel message and `done` events. The durable JSON file carries the
 reviewable result.
 
-The subnode copies identity, scope, and lens from `brief.json`. The minimal
+The subnode copies identity, scope, and lens from `brief.json`. Schema version 2
+requires one `scope_assessment` entry for every brief scope item, structured
+findings with evidence references, and typed uncertainties or corrections when
+present. Schema version 1 is retired and the validator rejects it. The minimal
 complete report is:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "task_id": "task-id-from-brief",
   "work_id": "work-id-from-brief",
   "subnode_id": "subnode-id-from-brief",
@@ -63,6 +92,14 @@ complete report is:
   "status": "complete",
   "scope": ["exact scope copied from brief"],
   "lens": "exact lens copied from brief",
+  "scope_assessment": [
+    {
+      "scope": "exact scope item from brief",
+      "status": "covered",
+      "conclusion": "What this scope establishes.",
+      "evidence_ids": ["stable-evidence-id"]
+    }
+  ],
   "evidence": [
     {
       "id": "stable-evidence-id",
@@ -70,37 +107,60 @@ complete report is:
       "summary": "What this independently reviewable evidence establishes."
     }
   ],
-  "findings": ["Bounded conclusion."],
+  "findings": [
+    {
+      "id": "finding-id",
+      "conclusion": "Bounded conclusion.",
+      "evidence_ids": ["stable-evidence-id"]
+    }
+  ],
   "uncertainties": [],
   "corrections": []
 }
 ```
 
+Append a checkpoint marker to `worklog.md` when a material unit is complete or
+blocked. It is a bounded recovery projection, not coordinator acceptance:
+
+```text
+<!-- trellis-checkpoint: {"id":"checkpoint-1","covered_scope":["exact scope item"],"evidence_ids":["stable-evidence-id"],"conclusion_or_blocker":"Current conclusion or blocker.","unknowns":[],"safe_resume_point":"Next safe action."} -->
+```
+
+The validator returns `review_concern` for missing or incomplete checkpoint
+coverage and for inconclusive scope assessments so the coordinator can inspect
+them. Identity, schema, path, and malformed-structure failures remain hard
+errors. A concern is never automatic acceptance or rejection.
+
 For `blocked`, `incomplete`, or `error`, include the same base fields plus a
 `completed_scope` list (empty when no assigned scope started) and a non-empty
 `blocker` string. Never use
 `accepted`, `rejected`, or `deferred` as a report status.
 
+## Dispatch Approval
+
+A request for research authorizes main-session evidence work; it does not by itself approve a subnode dispatch plan that has not yet been presented. Before any subnode `spawn` or `send`, persist and present the frozen plan in the active task. It must identify the research question, exact evidence-unit-to-scope mapping and grouping rationale, each brief's evidence range/sources, stop condition and report destination, concurrency/slot strategy, initial fill and FIFO refill/acceptance rules, and material dependencies. Record the user's explicit approval in that artifact. Approval is limited to the listed evidence work and grants no implementation authority. A material change to units, scope, method, owner, risk, or acceptance requires a newly frozen plan and approval before further affected dispatch. The main session may continue its own evidence work while awaiting dispatch approval.
+
 ## Dispatch And Wait
 
-Inspect the installed role first, then capture a durable event barrier before
-the worker can emit a terminal event. The CLI waits once and replays matching
-events committed after that barrier:
+After the frozen plan is approved, inspect the installed role first, then capture a durable event barrier before
+the worker can emit a terminal event. The CLI waits once for a worker lifecycle
+transition after that barrier, including supervisor-authored terminal events:
 
 ```bash
-trellis channel create subnode-example --by main --cwd "$PWD"
+trellis channel create subnode-example
 BARRIER="$(trellis channel barrier subnode-example)"
-trellis channel spawn subnode-example --agent subnode --provider codex \
-  --as "$SUBNODE_ID" --cwd "$PWD"
+trellis channel spawn subnode-example --agent subnode --as "$SUBNODE_ID"
 
 printf '%s\n' "Read $TASK/subnodes/$WORK_ID/$SUBNODE_ID/brief.json and perform only that bounded work." \
-  | trellis channel send subnode-example --as main --to "$SUBNODE_ID" \
+  | trellis channel send subnode-example --to "$SUBNODE_ID" \
       --stdin --delivery-mode requireRunningWorker
 
-trellis channel wait subnode-example --as main --from "$SUBNODE_ID" \
-  --kind done,error,killed --after-seq "$BARRIER" --timeout 30m
+trellis channel wait subnode-example --workers "$SUBNODE_ID" \
+  --after-seq "$BARRIER" --timeout 30m
 ```
 
+When selecting a configured model profile, use `--profile <id>` in place of `--agent subnode`; it implies the subnode role and reads its Codex provider from role frontmatter. Keep the unique worker `--as` for dispatch identity. Omit author `--as` on `send` and `wait` to use `TRELLIS_CHANNEL_AS` or `main`.
+
 `channel.subnode` in `.trellis/config.yaml` supplies the role defaults for
 `max_live_workers` (generated default `8`), `idle_timeout`, `timeout`, and
 `warn_before`. Change that section before a dispatch group when its resource
@@ -108,8 +168,18 @@ or lifetime needs differ; pass the corresponding `spawn` flag only for a
 one-off override. The generic `channel.worker_guard` remains the fallback for
 ordinary workers and for a subnode key omitted from the project config.
 
+For rolling FIFO dispatch, follow `references/multi-target-dispatch.md`: initially
+fill available native capacity, wait for the first terminal worker, review and
+accept it, then refill while other workers continue. Do not use `--all` as an
+ordinary refill prerequisite. Use `--workers a,b --all` only when the intent
+requires draining all already dispatched workers, with the barrier captured
+before dispatch.
+Worker mode emits one terminal worker projection per satisfied target. Ordinary
+adapter errors and peer turn completion do not end the wait. `--from` remains
+an exact event-author filter; it is not a worker lifecycle selector.
+
 Where the host exposes a live wait continuation, capture the same barrier,
-establish one event waiter before triggering the worker, and continue that same
+establish one worker waiter before triggering the worker, and continue that same
 waiter until terminal state. Until it resolves, times out, or errors, the next
 host operation is only that continuation: do not create another waiter or run
 shell/CLI diagnostics, including `channel messages`, worker inspection, or

package/dist/templates/common/bundled-skills/trellis-channel/references/workers.md

@@ -44,9 +44,9 @@ relative sibling file automatically for the provider child. Use this for
 stable role settings so every spawn of that role gets the same environment.
 The file contains plain `KEY=VALUE` lines only; it is not shell code and does
 not perform expansion or interpolation. Do not put credentials in a bundled
-role file. The bundled `subnode` role uses this mechanism to disable
-OpenViking's automatic recall, capture, and fixed background injection in the
-evidence worker process.
+role file. The coordinator may pass explicitly reviewed, task-minimal context
+to the child. Parent settings are merged with role settings, then runtime
+settings; later values take precedence.
 
 The success event `spawned` records `pid`, `provider`, `agent`, the injected
 `files`, and the resolved `manifests` so later spectators can audit context.
@@ -58,8 +58,7 @@ match `[A-Za-z0-9._-]+`. The default Trellis install ships three cards:
 
 - `.trellis/agents/check.md` — code-quality reviewer.
 - `.trellis/agents/implement.md` — coding worker for implementation runs.
-- `.trellis/agents/subnode.md` — bounded independent-evidence worker; its
-  `subnode.env` sibling is loaded automatically.
+- `.trellis/agents/subnode.md` — bounded independent-evidence worker.
 
 ```yaml
 ---
@@ -107,8 +106,7 @@ trellis channel spawn cr-example --agent check --provider codex --as check-cx \
   --file "$TASK/prd.md" \
   --file "$TASK/design.md" \
   --file "$TASK/implement.md" \
-  --jsonl "$TASK/check.jsonl" \
-  --cwd "$PWD" --timeout 30m
+  --jsonl "$TASK/check.jsonl" --timeout 30m
 ```
 
 The `spawned` event records both the literal `files` array and any `manifests`
@@ -129,7 +127,7 @@ channel:
 trellis channel spawn cr-feature --agent check --as check-claude
 trellis channel spawn cr-feature --agent check --provider codex --as check-cx
 
-trellis channel wait cr-feature --as main \
+trellis channel wait cr-feature \
   --from check-claude,check-cx --kind done --all --timeout 15m
 ```
 
@@ -152,7 +150,7 @@ echo "Stop refactoring the parser — switch to fixing the failing test in src/f
 
 Flags:
 
-- `--as <agent>` **(required)** — caller identity.
+- `--as <agent>` — caller identity; defaults to `TRELLIS_CHANNEL_AS` or `main`.
 - `--to <agent>` **(required)** — target worker.
 - `--scope <project|global>` — channel scope.
 - `--stdin` / `--text-file <path>` / `[text]` — replacement instruction body.
@@ -256,13 +254,13 @@ running peer.
 Inbox-relevant subcommands:
 
 - `send <channel> [text]` — append a `message` event.
-  - `--as <agent>` **(required)** — author.
+  - `--as <agent>` — author; defaults to `TRELLIS_CHANNEL_AS` or `main`.
   - `--to <agents>` — CSV; one → string, many → array; broadcast if omitted.
   - `--stdin` / `--text-file <path>` / `[text]` — body source.
   - `--delivery-mode <appendOnly|requireKnownWorker|requireRunningWorker>`.
 - `interrupt <channel> [text]` — soft-interrupt redirect (see above).
 - `wait <channel>` — block until matching events arrive.
-  - `--as <agent>` **(required)** — `self` for filter context.
+  - `--as <agent>` — filter identity; defaults to `TRELLIS_CHANNEL_AS` or `main`.
   - `--from <agents>` — CSV authors.
   - `--kind <kind[,kind...]>` — CSV (OR semantics); supports `interrupt`,
     `done`, `progress`, etc.

package/dist/templates/common/bundled-skills/trellis-channel/references/workflows.md

@@ -3,13 +3,20 @@
 Use these patterns by intent. Prefer durable channels for multi-round work and
 `channel run` for one-shot questions.
 
+The selected project workflow owns the dispatch and evidence contract. Under
+`codex-subnode-channel`, the main session implements/checks inline and explicitly
+approved independent evidence uses the subnode brief/report/acceptance path in
+`subnode-work.md`. The generic agent examples below do not override that path.
+Codex Channel workers disable their own native multi-agent features to prevent
+recursion; main-session inline mode does not disable explicit Channel evidence.
+
 ## Pattern A: Multi-round Brainstorm
 
 Use when the user says "和 codex/claude 讨论一下", "brainstorm", or "拉一个 agent
 进来一起看".
 
 ```bash
-trellis channel create brainstorm-storage-layer --by main \
+trellis channel create brainstorm-storage-layer \
   --task .trellis/tasks/05-XX-storage-adapter
 BARRIER="$(trellis channel barrier brainstorm-storage-layer)"
 
@@ -20,10 +27,10 @@ trellis channel spawn brainstorm-storage-layer \
   --as cx-arch --timeout 30m
 
 trellis channel send brainstorm-storage-layer \
-  --as main --to cx-arch --text-file /tmp/brainstorm-r1.md
+  --to cx-arch --text-file /tmp/brainstorm-r1.md
 
 trellis channel wait brainstorm-storage-layer \
-  --as main --kind done --from cx-arch --after-seq "$BARRIER" --timeout 10m
+  --kind done --from cx-arch --after-seq "$BARRIER" --timeout 10m
 ```
 
 Do not stop after one answer. Read the answer, identify vague areas, send a
@@ -49,11 +56,14 @@ needed.
 
 ## Pattern B: Implement / Check Agent
 
-Use when the user asks to dispatch implementation or review work.
+Use only when the selected workflow permits Channel implement/check dispatch
+and the task authorizes it, such as a Channel-driven workflow. Under
+`codex-subnode-channel`, use an approved independent-evidence subnode instead;
+ordinary implementation/checking stays in the main session.
 
 ```bash
 TASK=.trellis/tasks/05-12-foo
-trellis channel create cr-foo --task "$TASK" --by main
+trellis channel create cr-foo --task "$TASK"
 BARRIER="$(trellis channel barrier cr-foo)"
 
 trellis channel spawn cr-foo \
@@ -61,11 +71,10 @@ trellis channel spawn cr-foo \
   --jsonl "$TASK/check.jsonl" \
   --file "$TASK/prd.md" \
   --file "$TASK/design.md" \
-  --file "$TASK/implement.md" \
-  --cwd "$PWD" --timeout 15m
+  --file "$TASK/implement.md" --timeout 15m
 
-trellis channel send cr-foo --as main --to check --text-file /tmp/cr-brief.md
-trellis channel wait cr-foo --as main --kind done --from check --after-seq "$BARRIER" --timeout 15m
+trellis channel send cr-foo --to check --text-file /tmp/cr-brief.md
+trellis channel wait cr-foo --kind done --from check --after-seq "$BARRIER" --timeout 15m
 trellis channel messages cr-foo --kind message --from check --tag final_answer
 ```
 
@@ -75,10 +84,12 @@ already run.
 
 ## Pattern C: Parallel Reviewers
 
-Use one channel and distinct worker names.
+Use one channel and distinct worker names only under the same permitted
+dispatch contract as Pattern B. These generic check workers are not the default
+review path for `codex-subnode-channel`.
 
 ```bash
-trellis channel create cr-feature --by main --ephemeral
+trellis channel create cr-feature --ephemeral
 BARRIER="$(trellis channel barrier cr-feature)"
 
 trellis channel spawn cr-feature --agent check \
@@ -89,9 +100,9 @@ trellis channel spawn cr-feature --agent check --provider codex --as check-cx \
   --jsonl "$TASK/check.jsonl" --file "$TASK/prd.md" --file "$TASK/design.md" \
   --timeout 15m
 
-trellis channel send cr-feature --as main --to check --text-file /tmp/cr-brief.md
-trellis channel send cr-feature --as main --to check-cx --text-file /tmp/cr-brief.md
-trellis channel wait cr-feature --as main --kind done --from check,check-cx --all --after-seq "$BARRIER" --timeout 15m
+trellis channel send cr-feature --to check --text-file /tmp/cr-brief.md
+trellis channel send cr-feature --to check-cx --text-file /tmp/cr-brief.md
+trellis channel wait cr-feature --kind done --from check,check-cx --all --after-seq "$BARRIER" --timeout 15m
 ```
 
 `--all` means every listed worker must emit a matching event.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-skills-or-commands.md

@@ -4,10 +4,11 @@ When the user wants to change AI entry points, auto-trigger rules, or explicit c
 
 Before editing, classify the skill you are about to touch:
 
-- **Bundled upstream skill** — `trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`. Source of truth lives in the Trellis CLI repo under `packages/cli/src/templates/common/bundled-skills/<name>/`; auto-dispatched to every platform's skill root by `getBundledSkillTemplates()` on `trellis init` / `trellis update`. Local edits here are tracked by `.trellis/.template-hashes.json` and will be flagged on the next update.
-- **Project-local skill** — anything else under `.{platform}/skills/`. Owned by the user; not refreshed by `trellis update`.
+- **Bundled multi-file skill** — `trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`, `trellis-research-record`. Source lives under `packages/cli/src/templates/common/bundled-skills/<name>/`; `getBundledSkillTemplates()` distributes it to each platform skill root on init/update.
+- **Other Trellis-managed entry** — single-file skills such as `trellis-check` and `trellis-before-dev`, command-backed skills such as `trellis-finish-work`, and platform-specific entries. Their sources live under `common/skills/`, `common/commands/` or the relevant platform template directory. Configurators generate them and update tracks their template hashes too.
+- **Project-local entry** — content created by the project outside the managed template set, owned by the user and not refreshed by `trellis update`. Its directory or absence from a short bundled-name list does not establish ownership.
 
-The remainder of this file uses "skill" for the local file; the override and conflict rules differ between the two cases.
+The remainder uses "skill" for the local file. Confirm its actual source and generated-file ownership before choosing the edit path.
 
 ## Read These Files First
 
@@ -15,7 +16,7 @@ The remainder of this file uses "skill" for the local file; the override and con
 2. Target platform skill/command/prompt/workflow directory
 3. Related agent or hook files
 4. Whether project rules already exist in `.trellis/spec/`
-5. `.trellis/.template-hashes.json` — confirms whether the skill you are about to edit is upstream-owned (entry present) or project-local (entry absent)
+5. `.trellis/.template-hashes.json` and the relevant template/configurator — a hash entry confirms management; a missing entry alone does not prove project ownership.
 
 ## Which Entry Type To Choose
 
@@ -25,7 +26,7 @@ The remainder of this file uses "skill" for the local file; the override and con
 | User wants to trigger manually with a command | Add or modify a command/prompt/workflow. |
 | Team project conventions | Prefer `.trellis/spec/` or a project-local skill — never a bundled skill directory. |
 | Tweak a bundled skill (`trellis-meta` et al.) for the user's own project | Create a project-local sibling skill (different name) that overrides intent, or edit `.trellis/spec/`. Edits inside the bundled skill directory survive only until the next `trellis update` and will need a "keep" choice each time. |
-| Contribute the change back upstream | Edit `packages/cli/src/templates/common/bundled-skills/<name>/` in the Trellis CLI repo, not the deployed copy. |
+| Contribute the change back upstream | Edit its actual bundled, common skill/command or platform template source in the Trellis CLI repo, not the deployed copy. |
 | Change Trellis flow semantics | Synchronize `.trellis/workflow.md`. |
 
 ## Modify A Skill
@@ -50,12 +51,12 @@ Do not write vague descriptions such as "helpful project skill"; they can trigge
 
 ### Bundled vs. Project-Local
 
-The same directory shape is used by two very different ownership models:
+The same directory shape can contain different ownership models:
 
-| Aspect | Bundled (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) | Project-local |
+| Aspect | Trellis-managed entry | Project-local |
 | --- | --- | --- |
-| Source of truth | `packages/cli/src/templates/common/bundled-skills/<name>/` in Trellis CLI repo | Inside the user project itself |
-| Dispatch | Auto-dispatched to every platform skill root by `getBundledSkillTemplates()` (`packages/cli/src/templates/common/index.ts`) on `trellis init` / `trellis update` | Created by the user (or another skill) and never moved |
+| Source of truth | Actual bundled, common skill/command or platform template in the Trellis CLI repo | Inside the user project itself |
+| Generation | Bundled files use `getBundledSkillTemplates()`; other entries use the platform configurator on init/update | Created by the user (or another skill) |
 | Hash tracking | Every file recorded in `.trellis/.template-hashes.json`; conflict prompt on update | Not tracked |
 | Editing locally | Allowed but will be marked "modified by user" on next update | Free editing |
 | The right way to customize | Add a *new* project-local skill with a *different* name that supplements (or supersedes) the bundled one | Edit the file directly |
@@ -92,7 +93,7 @@ If a command only repeats workflow rules, prefer making it reference/read `.trel
 | ZCode | `.zcode/skills/`, `.zcode/commands/` |
 | Kilo / Antigravity / Devin | workflows + skills |
 
-Every directory above is a deploy target for the four bundled skills. Each platform receives a full copy on `trellis init` and refresh on `trellis update`; nothing has to be wired by hand.
+The bundled multi-file skills are distributed to each supported platform skill root on init/update; other managed entries follow that platform's configurator. Read the actual template set rather than inferring it from a fixed count.
 
 ## Add A Project-Local Skill
 
@@ -111,8 +112,9 @@ Pick a name that does **not** collide with the bundled set:
 - `trellis-spec-bootstrap`
 - `trellis-session-insight`
 - `trellis-channel`
+- `trellis-research-record`
 
-A reused name causes `getBundledSkillTemplates()` to overwrite the project-local copy on the next update. A common convention is to prefix the project name: `acme-trellis-deploy`, `acme-trellis-onboarding`.
+Also avoid names of generated single-file or platform entries. A collision becomes managed template content or an update conflict; it is not a durable override. A common convention is to prefix the project name: `acme-trellis-deploy`, `acme-trellis-onboarding`.
 
 ## Notes
 

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-task-lifecycle.md

@@ -10,6 +10,7 @@ Task lifecycle includes creation, start, context configuration, finish, archive,
 4. `.trellis/scripts/common/task_store.py`
 5. `.trellis/scripts/common/task_utils.py`
 6. The current task's `.trellis/tasks/<task>/task.json`
+7. `.trellis/scripts/common/task_planning.py` for material revisions and start admission
 
 ## Common Needs And Edit Points
 
@@ -17,11 +18,14 @@ Task lifecycle includes creation, start, context configuration, finish, archive,
 | --- | --- |
 | Automatically sync an external system after task creation | `hooks.after_create` in `.trellis/config.yaml`. |
 | Automatically update status after task start | `hooks.after_start` in `.trellis/config.yaml`. |
+| Return an in-progress task to planning | `hooks.after_replan` in `.trellis/config.yaml`. |
 | Run a script after task finish | `hooks.after_finish` in `.trellis/config.yaml`. |
 | Clean external resources after archive | `hooks.after_archive` in `.trellis/config.yaml`. |
 | Change default task fields | `.trellis/scripts/common/task_store.py`. |
 | Change task parsing/search | `.trellis/scripts/common/task_utils.py`. |
 | Change active task behavior | `.trellis/scripts/common/active_task.py`. |
+| Select context without starting | Native `task.py select`; preserve phase/branch and drain live Channel work first. |
+| Seal and record later approval of a material plan | Native `task.py plan seal/approve`; reserved `meta.planning`, owned by `common/task_planning.py`. |
 
 ## lifecycle hooks
 
@@ -43,7 +47,7 @@ Hook commands receive the `TASK_JSON_PATH` environment variable, pointing to the
 
 ## Change Task Fields
 
-If the user wants to add project-local fields, prefer putting them under `meta` in `task.json` to avoid breaking existing scripts' assumptions about standard fields.
+If the user wants to add project-local fields, prefer putting them under `meta` in `task.json` to avoid breaking existing scripts' assumptions about standard fields. `meta.planning` is reserved for native seal/approve; do not prefill or overwrite it through generic metadata. Classification uses `execution_class=direct|planned` and `delivery_mode=change_bearing|analysis_only`.
 
 Example:
 
@@ -69,7 +73,8 @@ Active task is session-level state stored in `.trellis/.runtime/sessions/`. Do n
 `cmd_create` in `.trellis/scripts/common/task_store.py` calls `set_active_task` best-effort right after writing the new task directory. The behavior:
 
 - When the calling shell carries session identity (`TRELLIS_CONTEXT_ID` env var, or any platform-specific session env that `resolve_context_key` recognizes — see `active_task.py:_ENV_SESSION_KEYS`), the per-session pointer at `.trellis/.runtime/sessions/<context_key>.json` is rewritten to point at the new task. The task's `status=planning` and `[workflow-state:planning]` fires on the very next `UserPromptSubmit`.
-- When session identity is unavailable (raw CLI invocation outside an AI session, or a platform that doesn't propagate identity to shell), the task directory is still created and `status=planning` is still written, but the active pointer is left untouched. The user can attach the task later with `task.py start <dir>` once they're back in an AI session.
+- When session identity is unavailable (raw CLI invocation outside an AI session, or a platform that doesn't propagate identity to shell), the task directory is still created and `status=planning` is still written, but the active pointer is left untouched. Attach planning context later with `task.py select <dir>` once identity is available; start requires its own phase/approval gates.
+- `create --no-start` deliberately preserves the prior pointer; use select to switch context after saving the checkpoint and draining already dispatched Channel work. Selecting does not change phase/branch, run after_start, or grant implementation authority.
 
 This makes `[workflow-state:planning]` the live breadcrumb during the brainstorm and JSONL curation work that follows `task.py create`. The pre-R7 behavior left the breadcrumb stuck on `no_task` until `task.py start`, so the planning block was effectively dead text.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/task-system.md

@@ -43,6 +43,8 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
 | `children` / `parent` | Parent/child task relationships. |
 | `commit` / `pr_url` | Commit and PR information after completion. |
 | `meta` | Extension fields. |
+| `meta.execution_class` / `meta.delivery_mode` | Explicit task classification; planned/change-bearing start needs current material-plan approval. |
+| `meta.planning` | Reserved native material revision, seal, and later approval; use plan seal/approve, never generic metadata. |
 
 ## Parent / Child Task Trees
 
@@ -81,7 +83,7 @@ The user sees a "current task," but Trellis stores active task state per session
 .trellis/.runtime/sessions/<context-key>.json
 ```
 
-`task.py start` writes the task path into the runtime session file for the current session. `task.py current --source` shows the current task and where it came from. Different AI windows can point to different tasks without overwriting each other.
+`task.py select` writes only the current session's task context; status/branch and implementation authority are unchanged. `task.py start` also enters execution after its admission gates. `task.py current --source` shows the current task and where it came from. Different AI windows can point to different tasks without overwriting each other. Before switching with live Channel work, pause refills and drain already dispatched units/reservations while preserving pending work and the old phase.
 
 If the platform or shell environment has no stable session identity, `task.py start` may be unable to set the active task. The AI should read the error, inspect the platform hook/session environment, and not fall back to a shared global pointer.
 
@@ -107,6 +109,9 @@ Rules:
 
 ```bash
 python3 ./.trellis/scripts/task.py create "<title>" --description "<one-line summary>" --slug <slug>
+python3 ./.trellis/scripts/task.py select <task>
+python3 ./.trellis/scripts/task.py plan seal <task>
+python3 ./.trellis/scripts/task.py plan approve <task> --revision <n> --basis "<actual later approval>"
 python3 ./.trellis/scripts/task.py start <task>
 python3 ./.trellis/scripts/task.py current --source
 python3 ./.trellis/scripts/task.py add-context <task> implement <file> <reason>

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/workflow.md

@@ -22,10 +22,12 @@ Each phase contains numbered steps, such as `1.3 Configure context`. These numbe
 
 ## Skill Routing
 
-`workflow.md` separates routing by platform capability:
+Read the selected `workflow.md` and current task phase to determine routing;
+platform capability alone does not select the implementation/check path:
 
-- Platforms with sub-agent support: dispatch `trellis-implement` by default for implementation and `trellis-check` for checking.
-- Platforms without sub-agent support: the main session reads skills such as `trellis-before-dev`, then executes directly.
+- A workflow that selects native sub-agent dispatch uses its platform-supported `trellis-implement` / `trellis-check` path.
+- An inline workflow has the main session read `trellis-before-dev`, implement and check directly. Explicit Channel independent evidence remains subject to that workflow's authorization and acceptance contract.
+- A Channel-driven workflow is a separate selected variant; generic Channel examples do not override an inline workflow.
 
 When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
 
@@ -59,7 +61,7 @@ Common changes:
 | 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 the wrap-up flow | Update Phase 3 and `finish-work` descriptions together. Follow the selected workflow's commit/push authorization; finish-work checks acceptance and classifies task-related versus unrelated dirty paths before archive and journal recording. |
 | 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/dist/templates/common/bundled-skills/trellis-session-insight/SKILL.md

@@ -5,7 +5,7 @@ description: "Reach into past AI conversation history through the `trellis mem`
 
 # Trellis Session Insight
 
-This skill teaches an AI **how to call `trellis mem`** — the project's cross-session memory feedstock — and **when reaching for it is the right move**.
+This skill teaches an AI **how to call `trellis mem`** for local conversation history and **when reaching for it is the right move**.
 
 It is intentionally a **capability skill, not a workflow**. There is no fixed output file, no required write-back step, no "always run after finish-work" rule. What to do with what `mem` returns is a judgement call made in the moment of the conversation. The skill exists so the AI knows the capability is there and can decide.
 
@@ -15,6 +15,14 @@ A local CLI that indexes the user's past Claude Code, Codex, Devin CLI, Grok, Op
 
 Nothing in `mem` is uploaded. All reads are local.
 
+`mem` returns historical discussion, not a curated knowledge base or an automatic
+preference/summary writer. Current source, task artifacts, `AGENTS.md`, and specs
+own current facts. If the user asks for maintained knowledge or reusable notes,
+use that environment's configured native knowledge tool instead. Select the
+source by intent and add a targeted second lookup only for a specific evidence
+gap; there is no required sequence through all sources. A knowledge tool's
+absence or failure does not block Trellis tasks, local recall, or handoff.
+
 ## When to reach for it
 
 The bar is "would a senior teammate ask 'didn't we already talk about this?'" — those are the moments. Some concrete patterns:
@@ -40,13 +48,44 @@ If none of these apply, don't call `mem`. It is a tool, not a ceremony.
 Treat the output as **raw material**, not a deliverable. Once you have it, decide based on the live conversation:
 
 - **Quote inline in your reply** if a specific past exchange answers the user's current question — and cite the session-id / phase so the user can verify.
-- **Update `<task>/prd.md` or `<task>/design.md`** if `mem` surfaced a load-bearing decision that should have been written down but wasn't. Surface the proposed edit to the user first.
+- **Update `<task>/prd.md` or `<task>/design.md`** if `mem` surfaced a load-bearing decision that should have been written down but wasn't. Verify against current facts and follow the active task's authorization; material changes return to its planning gate.
 - **Append to a task-local notes file** (e.g. `<task>/notes.md` or extending an existing one) if the finding belongs to the current task's record but doesn't fit the PRD.
 - **Update `.trellis/spec/`** if the finding is a project-wide convention or gotcha that would help future tasks. Run the `trellis-update-spec` skill for that — `session-insight` ends at the discovery.
 - **Just absorb it** for the next few turns and answer better, without writing anything. This is often the right move for one-off recall.
 
 Trellis does not prescribe a single destination. Forcing every recall into a fixed file makes the file grow into noise. Let the situation decide.
 
+Reusable experience can be proposed for a user-maintained knowledge tool;
+executable project contracts go through `trellis-update-spec`, stable methods
+through the source Skill owner, and cross-project rules require an explicit
+common scope. External knowledge writes or new promotions require concrete user
+intent, including any minimal source-note status/version/target-link update.
+Existing authorized task/spec duties do not acquire an extra confirmation gate.
+Verify each target independently; do not introduce automatic synchronization.
+
+## Bulk history and resource boundaries
+
+For bulk or remote history research, first define the project path, platform,
+date range, question and required session types. Start with metadata and a small
+sample to verify the stored structure; filter before extracting bodies. Confirm
+main-session versus child-session scope from actual metadata, not file counts.
+
+Choose the processing location and authorized destination before reading a
+large corpus. Process one bounded unit at a time, retain only needed results,
+and transfer only the requested material. Test the intended bulk path on small
+or synthetic data and observe memory/output before scaling. On resource
+pressure, stop the affected work, preserve its checkpoint and reduce the unit;
+do not continue a remote scan or increase concurrency blindly.
+
+`--limit` limits displayed rows, not scan work or a process memory budget.
+Codex small-output `search`/`context` avoid accumulating all dialogue bodies,
+but per-record parsing, fingerprints/index metadata and output still cost
+memory. Full `extract`/phase results and the other platform adapters may retain
+complete dialogue arrays. Do not promise constant memory or infer an earlier
+OOM's cause from these limits alone. Preserve the source logs; raw dialogue,
+credentials and runtime data do not belong in Git. Historical findings still
+require current-source verification and do not authorize automatic write-back.
+
 ## How to call it
 
 Full CLI reference is in `references/cli-quick-reference.md`. The 80% case is one of:
@@ -68,7 +107,7 @@ trellis mem list --cwd <project-path>
 trellis mem projects   # → list active project cwds, then narrow
 ```
 
-Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
+Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create`/`replan` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
 
 ## Triggering patterns
 

package/dist/templates/common/bundled-skills/trellis-session-insight/references/cli-quick-reference.md

@@ -23,7 +23,7 @@ Full flag reference for the five subcommands. Pin this as the authoritative sour
 | `--cwd <path>`                                | list / search     | Force a specific project cwd instead of inferring from where you are.                                                                                      |
 | `--limit N`                                   | list / search     | Cap output rows. Default `50`.                                                                                                                             |
 | `--grep KW`                                   | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated.                                                                                        |
-| `--phase brainstorm\|implement\|all`          | extract           | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
+| `--phase brainstorm\|implement\|all`          | extract           | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create/replan, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
 | `--turns N`                                   | context           | Number of hit turns to return. Default `3`.                                                                                                                |
 | `--around N`                                  | context           | Surrounding turns to include per hit. Default `1`.                                                                                                         |
 | `--max-chars N`                               | context           | Total character budget. Default `6000` (~1500 tokens).                                                                                                     |