@mindfoldhq/trellis 0.5.0-beta.9 → 0.5.0-rc.0

package/dist/migrations/manifests/0.5.0-beta.17.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0-beta.17",
+  "description": "Beta.17 installs trellis-meta as a bundled built-in skill, hardens Pi subagent launch/configuration, removes promotional init completion output, and improves subagent context wiring. No migration actions are required.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(cli): Install `trellis-meta` as a bundled multi-file built-in skill under every platform skill root. The shared template pipeline now supports `packages/cli/src/templates/common/bundled-skills/<skill>/` through `getBundledSkillTemplates()`, `resolveBundledSkills()`, `collectSkillTemplates()`, and `writeSkills()`.\n- feat(pi): Harden the Trellis Pi `subagent` launcher. The generated extension resolves `@mariozechner/pi-coding-agent/dist/cli.js` when possible, runs child Pi with `--mode text -p --no-session`, sends delegated prompts through stdin, bounds stdout/stderr buffers, forwards `TRELLIS_CONTEXT_ID`, and wires `AbortSignal` cancellation.\n- feat(pi): Add Pi subagent model/thinking configuration. `.pi/agents/*.md` frontmatter may provide `model`, `thinking`, and `fallbackModels`, while the `subagent` tool accepts per-call `model` and `thinking` overrides and maps them to `--model <model[:thinking]>` or `--thinking <level>`.\n- docs(workflow): Clarify that `task.py create --slug <auto>` receives a slug without a date prefix because the script adds the `MM-DD-` directory prefix automatically.\n\n**Behavior Changes:**\n- chore(init): Remove promotional completion output from `trellis init`; completion output now stays focused on generated files and next actions.\n\n**Bug Fixes:**\n- fix(trellis): Improve subagent context wiring across local platform files. Cursor native custom-agent payloads are parsed from `Task`/`Subagent` tool input, workflow-state breadcrumbs require exact `trellis-implement` / `trellis-check` / `trellis-research` agent names, and Claude/Cursor/Codex hook paths preserve session identity for later shell or subagent context loading.",
+  "migrations": [],
+  "notes": "Run `trellis update` to receive the bundled `trellis-meta` skill, Pi subagent launcher/config updates, init output cleanup, and subagent context wiring fixes. No `--migrate` flag is required."
+}

package/dist/migrations/manifests/0.5.0-beta.18.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0-beta.18",
+  "description": "Beta.18 redesigns the Phase 3 workflow: Phase 3.4 adds an AI-driven batched commit step, and `/trellis:finish-work` becomes a 4-step survey + archive + journal flow that refuses to run on a dirty working tree. Also fixes parent-task progress regression on child archive, hash-tracks AGENTS.md during update, and supports OpenCode PowerShell context injection on Windows. No migration actions are required.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(workflow): Add `Phase 3.4 Commit changes` to `workflow.md`. The AI inspects `git status --porcelain`, learns commit-message style from `git log --oneline -5`, classifies dirty files into AI-edited-this-session vs unrecognized groups, drafts a batched commit plan, and commits per batch only after one-shot user confirmation. Rejecting the plan exits to manual mode without a flag. Wrap-up reminder renumbers from 3.4 to 3.5. The `[workflow-state:completed]` breadcrumb (and the four hook fallbacks in `inject-workflow-state.py`/`.js`) now direct users at `/trellis:finish-work` instead of the legacy `task.py finish` + `task.py archive` sequence.\n- feat(skills): Rewrite `/trellis:finish-work` as a 4-step survey + archive + journal flow. Step 1 runs `get_context.py --mode record` to print active tasks, git status, and recent commits — when other completed-but-unarchived tasks surface, the AI prompts once for one-shot batch cleanup. Step 2 runs `git status --porcelain` (excluding `.trellis/workspace/` and `.trellis/tasks/`) and bails out if anything else is dirty. Step 3 archives the active task plus any cleanup tasks the user confirmed in Step 1. Step 4 records the session journal using hashes from Step 1's recent-commits output. Code commits belong in Phase 3.4, not here. The common skill template uses `{{CMD_REF:finish-work}}` so `cmdRefPrefix` resolves correctly per platform (`/trellis:` for Claude/OpenCode, `$` for Codex, `/trellis-` for Cursor).\n\n**Bug Fixes:**\n- fix(scripts): Stop pruning archived children from a parent task's `children` list. `cmd_archive` previously removed the child name on archive, which made `children_progress` shrink both numerator and denominator (e.g. `[1/6 done]` → `[0/5 done]`, hiding completed work). The list now stays intact; `children_progress` treats children missing from active statuses as completed (cmd_archive sets `status=completed` before moving the dir).\n- fix(update): Hash-track `AGENTS.md` during `trellis update`. Pre-0.5.0-beta.18 projects wrote `AGENTS.md` without recording its template hash, which would surface as a false \"modified by you\" conflict on update. The new `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` managed-block replacement plus a legacy pristine-hash allowlist (`LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES`) lets old untouched projects update cleanly while still preserving any user customizations outside the block.\n- fix(opencode): Support PowerShell context injection in OpenCode on Windows. `inject-subagent-context.js` now emits `$env:TRELLIS_CONTEXT_ID = '...'; ` instead of the POSIX `export` form when the host platform is `win32`, and the explicit-assignment dedup detector matches both POSIX and PowerShell forms.\n\n**Internal:**\n- test: Add `test/setup.ts` registered via `setupFiles` in `vitest.config.ts`. It deletes `process.env.TRELLIS_CONTEXT_ID` and `process.env.OPENCODE_RUN_ID` at vitest process start so the OpenCode resolver tests no longer pick up a Claude/OpenCode host-session env that would hijack the platform-input-derived contextKey.\n- docs(spec): Document the parent-child `children` list invariant in `script-conventions.md` and the host-shell env-leak isolation pattern in `unit-test/conventions.md`.",
+  "migrations": [],
+  "notes": "Run `trellis update` to receive the Phase 3.4 commit step, the rewritten `/trellis:finish-work` skill, the parent-child progress fix, AGENTS.md hash tracking, and OpenCode PowerShell support. No `--migrate` flag is required."
+}

package/dist/migrations/manifests/0.5.0-beta.19.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0-beta.19",
+  "description": "Beta.19 hot-fixes a regression introduced in beta.18: when an AGENTS.md exists without `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` markers (pre-beta.18 projects, or hand-authored files), `trellis update` was clobbering the user's content with the bare Trellis template. The managed block now appends to the existing file instead of overwriting it. No migration actions are required.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(update): Preserve user content in `AGENTS.md` when the file has no `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` markers. Beta.18's managed-block replacement returned the bare template as a fallback when no markers were found, which silently replaced the user's hand-written `AGENTS.md` content during `trellis update`. The fallback now appends the canonical managed block to the existing content instead, so user-authored sections are preserved verbatim. Existing tests cover the legacy-pristine and modified-managed-block cases; the new `#4d preserves user AGENTS.md without TRELLIS markers by appending the managed block` case covers the hand-authored-without-markers path.",
+  "migrations": [],
+  "notes": "Run `trellis update` to receive the AGENTS.md preservation fix. No `--migrate` flag is required. If beta.18 already overwrote your `AGENTS.md`, restore the file from git history and re-run `trellis update` on beta.19 to merge in the managed block while keeping your content."
+}

package/dist/migrations/manifests/0.5.0-beta.5.json

@@ -4,6 +4,8 @@
   "breaking": true,
   "recommendMigrate": true,
   "changelog": "**Breaking Changes:**\n- rename(agents): `implement` / `check` / `research` sub-agents are now `trellis-implement` / `trellis-check` / `trellis-research` across all 10 platforms (claude, cursor, opencode, codex, kiro, gemini, qoder, codebuddy, copilot, droid). Generic names were colliding with user-defined agents and being matched by the main agent's description heuristics on some platforms. Prefixing with `trellis-` makes them unambiguously Trellis sub-agents. `workflow.md`, copilot start prompt, `shared-hooks/inject-subagent-context.py`, and configurator detection all updated to use the new names.\n\n**Bug Fixes:**\n- fix(agents): drop `model: opus` from all 18 markdown agent frontmatters + the example `Task()` calls in `copilot/prompts/start.prompt.md`. On Claude Code this merely hardcoded Opus for all sub-agent runs (ignoring user preference); on Cursor it actively mapped to Claude Opus billing at ~5x Sonnet cost and surprised users; on Gemini/Droid/Codebuddy/Qoder `opus` isn't even a valid model identifier. Agents now inherit whatever model the user configured for their platform.",
+  "migrationGuide": "## Sub-Agent Rename: `implement` / `check` / `research` → `trellis-*`\n\nbeta.5 renames the three core sub-agents to add a `trellis-` prefix across all 10 agent-capable platforms (Claude, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid). The generic names (`implement`, `check`, `research`) were colliding with user-defined agents in some setups.\n\n### What changes\n\n| Old name | New name |\n|---|---|\n| `implement` | `trellis-implement` |\n| `check` | `trellis-check` |\n| `research` | `trellis-research` |\n\nPaths per platform:\n\n- **Claude / OpenCode / Cursor / etc.**: `.<platform>/agents/implement.md` → `.<platform>/agents/trellis-implement.md`\n- **Codex**: `.codex/agents/implement.toml` → `.codex/agents/trellis-implement.toml`\n- **Kiro**: `.kiro/agents/implement.json` → `.kiro/agents/trellis-implement.json`\n\n### Side-effect: removed `model: opus` from agent templates\n\nAgent YAML frontmatter no longer hardcodes a model. Falls back to whatever the platform default is. If you pinned opus explicitly for a reason (budget, performance), re-add `model: opus` to your local agent files after migrate.\n\n### How to upgrade\n\n```bash\ntrellis update --migrate\n```\n\n30 rename entries run. Unmodified agent files are renamed silently; customized ones (e.g. you tweaked the agent prompt) land on the standard `Modified by you` confirm prompt — pressing Enter (backup-rename) is safe.\n\n### What to check after migrate\n\n1. **Any code that spawns agents by name** — shell scripts, CI jobs, or other automation calling `Task(subagent_type=\"implement\")` must update to `Task(subagent_type=\"trellis-implement\")`.\n2. **Aliases / hot keys** — if you had a keyboard shortcut or prompt alias that referenced `implement` / `check` / `research`, update it.\n3. **Model pin** — if you customized `model: opus` in agent frontmatter, re-add it. Trellis no longer pins a model by default.",
+  "aiInstructions": "When helping a user migrate to 0.5.0-beta.5:\n\n1. **Grep for bare agent names in user code**: look for `Task(subagent_type=\"implement\"|\"check\"|\"research\")` in any .md / .ts / .py / shell files. Rename each to the `trellis-` prefixed version.\n\n2. **Check agent customizations**: diff the user's `.<platform>/agents/{implement,check,research}.*` against the new `trellis-*` templates. If they had custom content, help merge it into the new file.\n\n3. **Model pinning**: if their agent frontmatter had `model: opus` and they still want it pinned, re-add it after migrate. beta.5 removes the default pin in favor of platform-default.\n\n4. **Run migrate**: `trellis update --migrate`. Hash-verified renames — pristine files renamed silently, customized files land on the confirm prompt (Enter = backup-rename is safe).\n\n5. **Verify clean second run**: after migrate, running `trellis update` again should report \"Already up to date!\". Any diff indicates a rename that didn't complete (user chose skip on a modified file).",
   "migrations": [
     {
       "type": "rename",

package/dist/migrations/manifests/0.5.0-rc.0.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0-rc.0",
+  "description": "First 0.5.0 release candidate. Stabilizes the beta.19 line with non-interactive init recovery fixes, workflow breadcrumbs that read from workflow.md, automatic updates for [workflow-state:*] blocks, and refreshed trellis-meta references. rc.0 adds no new migration actions; projects upgrading from 0.4.x still inherit the 0.5 migration chain from beta.0.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(workflow-state): Per-turn workflow breadcrumbs now read from `.trellis/workflow.md` `[workflow-state:STATUS]` blocks. Python and OpenCode JS fallback dictionaries were removed so workflow forks have one file to edit. The planning breadcrumb now calls out Phase 1.3 `implement.jsonl` / `check.jsonl` curation, and the in-progress breadcrumb includes Phase 3.4 commit before `/trellis:finish-work`.\n- feat(update): `trellis update` now refreshes `.trellis/workflow.md` breadcrumb blocks per status: replace existing `[workflow-state:*]` bodies from the CLI template, append missing blocks, preserve content outside the blocks, and warn when customized prompt text inside the blocks is replaced.\n- feat(task): `task.py create` best-effort sets the session active-task pointer, making the planning breadcrumb reachable immediately after task creation. `trellis continue` routes by `task.json.status` and required artifacts instead of PRD existence alone.\n- docs(meta): Refresh bundled `trellis-meta` references to explain how workflow-state reads `workflow.md`.\n\n**Bug Fixes:**\n- fix(init): `trellis init --yes` is fully non-interactive. `--yes` now maps conflicts to skip mode, and `writeFile()` falls back to skip in non-TTY `ask` mode to avoid prompts or `ERR_USE_AFTER_CLOSE` in scripted runs.\n- fix(init): Recover aborted first init runs where `.trellis/` exists but `tasks/` is empty. The second `trellis init -u <name> --codex --yes` now creates `00-bootstrap-guidelines` instead of mis-routing to joiner onboarding.\n\n**Testing:**\n- test(init): Add integration coverage for empty-`tasks/` recovery with and without `--force`, plus non-TTY file-writer conflict behavior.\n- test(workflow-state): Add regression coverage for workflow.md tag parsing, fallback removal, Phase 1.3 / Phase 3.4 breadcrumb invariants, session-start tag stripping, and workflow.md breadcrumb block updates.",
+  "migrations": [],
+  "notes": "RC install: `npm install -g @mindfoldhq/trellis@rc`. Projects already on 0.5 beta can run `trellis update`. Projects upgrading from 0.4.x should run `trellis update --migrate` because the 0.5 migration chain begins at 0.5.0-beta.0. rc.0 itself adds no new migration entries."
+}

package/dist/templates/claude/agents/trellis-research.md

@@ -29,7 +29,7 @@ Conversations get compacted; files don't. Every research output MUST end up as a
 
 ### Step 1: Resolve Current Task
 
-Read `.trellis/.current-task` → task directory (e.g. `.trellis/tasks/04-17-foo/`). If empty or missing, ask the user where to write output; do NOT guess.
+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.
 
 Ensure `{TASK_DIR}/research/` exists:
 

package/dist/templates/claude/settings.json

@@ -2,10 +2,6 @@
   "env": {
     "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
   },
-  "statusLine": {
-    "type": "command",
-    "command": "{{PYTHON_CMD}} .claude/hooks/statusline.py"
-  },
   "hooks": {
     "SessionStart": [
       {

package/dist/templates/codebuddy/agents/trellis-research.md

@@ -29,7 +29,7 @@ Conversations get compacted; files don't. Every research output MUST end up as a
 
 ### Step 1: Resolve Current Task
 
-Read `.trellis/.current-task` → task directory (e.g. `.trellis/tasks/04-17-foo/`). If empty or missing, ask the user where to write output; do NOT guess.
+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.
 
 Ensure `{TASK_DIR}/research/` exists:
 

package/dist/templates/codex/agents/trellis-research.toml

@@ -13,8 +13,9 @@ through the chat reply is a failure.
 
 ## Workflow
 
-1. Read `.trellis/.current-task` to get the task directory. If empty,
-   ask the user where to write output; do not guess.
+1. Run `python3 ./.trellis/scripts/task.py current --source` to get the
+   active task path and source. If no active task is set, ask the user
+   where to write output; do not guess.
 2. Run `mkdir -p <TASK_DIR>/research` to ensure the directory exists.
 3. Read `.trellis/workflow.md`, relevant `.trellis/spec/` files, and
    target code before forming an opinion.

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

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import subprocess
 import sys
 import warnings
@@ -19,11 +20,54 @@ from pathlib import Path
 
 warnings.filterwarnings("ignore")
 
+FIRST_REPLY_NOTICE = """<first-reply-notice>
+On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
+Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
+Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+</first-reply-notice>"""
+
 
 def should_skip_injection() -> bool:
     return os.environ.get("CODEX_NON_INTERACTIVE") == "1"
 
 
+def configure_project_encoding(project_dir: Path) -> None:
+    """Reuse Trellis' shared Windows stdio encoding helper before JSON output."""
+    scripts_dir = project_dir / ".trellis" / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        from common import configure_encoding  # type: ignore[import-not-found]
+
+        configure_encoding()
+    except Exception:
+        pass
+
+
+def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
+    """Return True iff jsonl has at least one row with a ``file`` field.
+
+    A freshly seeded jsonl only contains a ``{"_example": ...}`` row (no
+    ``file`` key) — that is NOT "ready". Readiness requires at least one
+    curated entry. Matches the contract used by ``inject-subagent-context.py``.
+    """
+    try:
+        for line in jsonl_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(row, dict) and row.get("file"):
+                return True
+    except (OSError, UnicodeDecodeError):
+        return False
+    return False
+
+
 def read_file(path: Path, fallback: str = "") -> str:
     try:
         return path.read_text(encoding="utf-8")
@@ -31,10 +75,32 @@ def read_file(path: Path, fallback: str = "") -> str:
         return fallback
 
 
-def run_script(script_path: Path) -> str:
+def _resolve_context_key(project_dir: Path, hook_input: dict) -> str | None:
+    scripts_dir = project_dir / ".trellis" / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from common.active_task import resolve_context_key  # type: ignore[import-not-found]
+    except Exception:
+        return None
+    return resolve_context_key(hook_input, platform="codex")
+
+
+def _resolve_active_task(trellis_dir: Path, hook_input: dict):
+    scripts_dir = trellis_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    from common.active_task import resolve_active_task  # type: ignore[import-not-found]
+
+    return resolve_active_task(trellis_dir.parent, hook_input, platform="codex")
+
+
+def run_script(script_path: Path, context_key: str | None = None) -> str:
     try:
         env = os.environ.copy()
         env["PYTHONIOENCODING"] = "utf-8"
+        if context_key:
+            env["TRELLIS_CONTEXT_ID"] = context_key
         cmd = [sys.executable, "-W", "ignore", str(script_path)]
         result = subprocess.run(
             cmd,
@@ -80,18 +146,15 @@ def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path:
     return trellis_dir / "tasks" / path_obj
 
 
-def _get_task_status(trellis_dir: Path) -> str:
-    current_task_file = trellis_dir / ".current-task"
-    if not current_task_file.is_file():
-        return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
-
-    task_ref = _normalize_task_ref(current_task_file.read_text(encoding="utf-8").strip())
-    if not task_ref:
-        return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
+def _get_task_status(trellis_dir: Path, hook_input: dict) -> str:
+    active = _resolve_active_task(trellis_dir, hook_input)
+    if not active.task_path:
+        return f"Status: NO ACTIVE TASK\nSource: {active.source}\nNext: Describe what you want to work on"
 
+    task_ref = active.task_path
     task_dir = _resolve_task_dir(trellis_dir, task_ref)
-    if not task_dir.is_dir():
-        return f"Status: STALE POINTER\nTask: {task_ref}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish"
+    if active.stale or not task_dir.is_dir():
+        return f"Status: STALE POINTER\nTask: {task_ref}\nSource: {active.source}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish"
 
     task_json_path = task_dir / "task.json"
     task_data: dict = {}
@@ -105,24 +168,34 @@ def _get_task_status(trellis_dir: Path) -> str:
     task_status = task_data.get("status", "unknown")
 
     if task_status == "completed":
-        return f"Status: COMPLETED\nTask: {task_title}\nNext: Archive with `python3 ./.trellis/scripts/task.py archive {task_dir.name}` or start a new task"
+        return f"Status: COMPLETED\nTask: {task_title}\nSource: {active.source}\nNext: Archive with `python3 ./.trellis/scripts/task.py archive {task_dir.name}` or start a new task"
 
     has_context = False
     for jsonl_name in ("implement.jsonl", "check.jsonl", "spec.jsonl"):
         jsonl_path = task_dir / jsonl_name
-        if jsonl_path.is_file() and jsonl_path.stat().st_size > 0:
+        if jsonl_path.is_file() and _has_curated_jsonl_entry(jsonl_path):
             has_context = True
             break
 
     has_prd = (task_dir / "prd.md").is_file()
 
     if not has_prd:
-        return f"Status: NOT READY\nTask: {task_title}\nMissing: prd.md not created\nNext: Write PRD, then research → init-context → start"
+        return f"Status: NOT READY\nTask: {task_title}\nSource: {active.source}\nMissing: prd.md not created\nNext: Write PRD (see workflow.md Phase 1.1) then curate implement.jsonl per Phase 1.3"
 
     if not has_context:
-        return f"Status: NOT READY\nTask: {task_title}\nMissing: Context not configured (no jsonl files)\nNext: Complete Phase 2 (research → init-context → start) before implementing"
-
-    return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
+        return f"Status: NOT READY\nTask: {task_title}\nSource: {active.source}\nMissing: implement.jsonl / check.jsonl missing or empty\nNext: Curate entries per workflow.md Phase 1.3 (spec + research files only), then `task.py start`"
+
+    return (
+        f"Status: READY\nTask: {task_title}\n"
+        f"Source: {active.source}\n"
+        "Next required action: dispatch `trellis-implement` per Phase 2.1. "
+        "For agent-capable platforms, the default is to NOT edit code in the main session. "
+        "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.\n"
+        "User override (per-turn escape hatch): if the user's CURRENT message explicitly tells the "
+        "main session to handle it directly (\"你直接改\" / \"别派 sub-agent\" / \"main session 写就行\" / "
+        "\"do it inline\" / \"不用 sub-agent\"), honor it for this turn and edit code directly. "
+        "Per-turn only; do NOT invent an override the user did not say."
+    )
 
 
 def _extract_range(content: str, start_header: str, end_header: str) -> str:
@@ -145,8 +218,24 @@ def _extract_range(content: str, start_header: str, end_header: str) -> str:
     return "\n".join(lines[start:end]).rstrip()
 
 
+_BREADCRUMB_TAG_RE = re.compile(
+    r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n.*?\n\s*\[/workflow-state:\1\]",
+    re.DOTALL,
+)
+
+
+def _strip_breadcrumb_tag_blocks(content: str) -> str:
+    return _BREADCRUMB_TAG_RE.sub("", content)
+
+
 def _build_workflow_toc(workflow_path: Path) -> str:
-    """Inject workflow guide: TOC + Phase Index + Phase 1/2/3 step details."""
+    """Inject workflow guide: TOC + Phase Index + Phase 1/2/3 step details.
+
+    Since v0.5.0-rc.0 the [workflow-state:STATUS] breadcrumb tag blocks
+    live inside ## Phase Index. They're consumed by inject-workflow-state.py
+    on each UserPromptSubmit, so strip them from the session-start payload
+    to avoid duplicating context.
+    """
     content = read_file(workflow_path)
     if not content:
         return "No workflow.md found"
@@ -162,9 +251,9 @@ def _build_workflow_toc(workflow_path: Path) -> str:
             out_lines.append(line)
     out_lines += ["", "---", ""]
 
-    phases = _extract_range(content, "Phase Index", "Workflow State Breadcrumbs")
+    phases = _extract_range(content, "Phase Index", "Customizing Trellis (for forks)")
     if phases:
-        out_lines.append(phases)
+        out_lines.append(_strip_breadcrumb_tag_blocks(phases).rstrip())
 
     return "\n".join(out_lines).rstrip()
 
@@ -176,11 +265,17 @@ def main() -> None:
     # Read hook input from stdin
     try:
         hook_input = json.loads(sys.stdin.read())
+        if not isinstance(hook_input, dict):
+            hook_input = {}
         project_dir = Path(hook_input.get("cwd", ".")).resolve()
     except (json.JSONDecodeError, KeyError):
+        hook_input = {}
         project_dir = Path(".").resolve()
 
+    configure_project_encoding(project_dir)
+
     trellis_dir = project_dir / ".trellis"
+    context_key = _resolve_context_key(project_dir, hook_input)
 
     output = StringIO()
 
@@ -190,10 +285,12 @@ Read and follow all instructions below carefully.
 </session-context>
 
 """)
+    output.write(FIRST_REPLY_NOTICE)
+    output.write("\n\n")
 
     output.write("<current-state>\n")
     context_script = trellis_dir / "scripts" / "get_context.py"
-    output.write(run_script(context_script))
+    output.write(run_script(context_script, context_key))
     output.write("\n</current-state>\n\n")
 
     output.write("<workflow>\n")
@@ -208,8 +305,11 @@ Read and follow all instructions below carefully.
         "- If you're spawning an implement/check sub-agent, context is injected "
         "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT "
         "need to read these indexes yourself.\n"
-        "- If you're editing code directly in the main session, Read the relevant "
-        "index(es) on-demand and follow their Pre-Dev Checklist.\n\n"
+        "- For agent-capable platforms, the default is to dispatch "
+        "`trellis-implement` and `trellis-check` (so JSONL context is loaded by "
+        "the sub-agents) rather than editing code in the main session. "
+        "Honor a per-turn user override only if the user's current message "
+        "explicitly opts out (see <task-status> below for override phrases).\n\n"
     )
 
     # guides/ inlined (cross-package thinking, broadly useful)
@@ -253,13 +353,13 @@ Read and follow all instructions below carefully.
     )
     output.write("</guidelines>\n\n")
 
-    task_status = _get_task_status(trellis_dir)
+    task_status = _get_task_status(trellis_dir, hook_input)
     output.write(f"<task-status>\n{task_status}\n</task-status>\n\n")
 
     output.write("""<ready>
 Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
-Wait for the user's first message, then handle it following the workflow guide.
-If there is an active task, ask whether to continue it.
+When the user sends the first message, follow <task-status> and the workflow guide.
+If a task is READY, execute its Next required action without asking whether to continue.
 </ready>""")
 
     context = output.getvalue()

package/dist/templates/codex/skills/finish-work/SKILL.md

@@ -1,148 +1,80 @@
 ---
 name: finish-work
-description: "Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit."
+description: "Wrap up an active Trellis task: archive it (and any other completed-but-unarchived tasks the user wants to clean up) and record a session journal. Refuses to run if the working tree has uncommitted code changes (those belong in workflow Phase 3.4 first). Use when the user asks to finish / wrap up / call it a day, or invokes $finish-work."
 ---
 
-# Finish Work - Pre-Commit Checklist
+# Finish Work
 
-Before submitting or committing, use this checklist to ensure work completeness.
+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 skill.
 
-**Timing**: After code is written and tested, before commit
-
----
-
-## Checklist
-
-### 1. Code Quality
+## Step 1: Survey current state
 
 ```bash
-# Must pass
-pnpm lint
-pnpm type-check
-pnpm test
+python3 ./.trellis/scripts/get_context.py --mode record
 ```
 
-- [ ] `pnpm lint` passes with 0 errors?
-- [ ] `pnpm type-check` passes with no type errors?
-- [ ] Tests pass?
-- [ ] No `console.log` statements (use logger)?
-- [ ] No non-null assertions (the `x!` operator)?
-- [ ] No `any` types?
-
-### 2. Code-Spec Sync
-
-**Code-Spec Docs**:
-- [ ] Does `.trellis/spec/backend/` need updates?
-  - New patterns, new modules, new conventions
-- [ ] Does `.trellis/spec/frontend/` need updates?
-  - New components, new hooks, new patterns
-- [ ] Does `.trellis/spec/guides/` need updates?
-  - New cross-layer flows, lessons from bugs
-
-**Key Question**: 
-> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?"
+This prints:
 
-If YES -> Update the relevant code-spec doc.
+- **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`.
 
-### 2.5. Code-Spec Hard Block (Infra/Cross-Layer)
+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 this change touches infra or cross-layer contracts, this is a blocking checklist:
+## Step 2: Sanity check — working tree must be clean
 
-- [ ] Spec content is executable (real signatures/contracts), not principle-only text
-- [ ] Includes file path + command/API name + payload field names
-- [ ] Includes validation and error matrix
-- [ ] Includes Good/Base/Bad cases
-- [ ] Includes required tests and assertion points
+Run:
 
-**Block Rule**:
-If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `$update-spec` manually first.
-
-### 3. API Changes
-
-If you modified API endpoints:
-
-- [ ] Input schema updated?
-- [ ] Output schema updated?
-- [ ] API documentation updated?
-- [ ] Client code updated to match?
-
-### 4. Database Changes
+```bash
+git status --porcelain
+```
 
-If you modified database schema:
+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.
 
-- [ ] Migration file created?
-- [ ] Schema file updated?
-- [ ] Related queries updated?
-- [ ] Seed data updated (if applicable)?
+If anything else is dirty (any path outside those two prefixes), **stop and bail out** with:
 
-### 5. Cross-Layer Verification
+> "Working tree has uncommitted code changes. Return to workflow Phase 3.4 to commit them before running `$finish-work`."
 
-If the change spans multiple layers:
+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.
 
-- [ ] Data flows correctly through all layers?
-- [ ] Error handling works at each boundary?
-- [ ] Types are consistent across layers?
-- [ ] Loading states handled?
+## Step 3: Archive task(s)
 
-### 6. Manual Testing
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
 
-- [ ] Feature works in browser/app?
-- [ ] Edge cases tested?
-- [ ] Error states tested?
-- [ ] Works after page refresh?
+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 there is no active task and the user did not confirm any cleanup archives, skip this step.
 
-## Quick Check Flow
+## Step 4: Record session journal
 
 ```bash
-# 1. Code checks
-pnpm lint && pnpm type-check
-
-# 2. View changes
-git status
-git diff --name-only
-
-# 3. Based on changed files, check relevant items above
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary"
 ```
 
----
-
-## Common Oversights
+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.
 
-| Oversight | Consequence | Check |
-|-----------|-------------|-------|
-| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ |
-| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests |
-| Migration not created | Schema out of sync | Check db/migrations/ |
-| Types not synced | Runtime errors | Check shared types |
-| Tests not updated | False confidence | Run full test suite |
-| Console.log left in | Noisy production logs | Search for console.log |
+Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
 
 ---
 
-## Relationship to Other Commands
+## Relationship to Other Skills
 
 ```
 Development Flow:
-  Write code -> Test -> $finish-work -> git commit -> $record-session
-                          |                              |
-                   Ensure completeness              Record progress
-                   
+  Phase 3.4 (workflow.md) -> AI drafts batched commits -> user confirms -> git commit
+                                                                              |
+                                                                              v
+                                                                    $finish-work
+                                                                    (survey + archive + journal)
+
 Debug Flow:
   Hit bug -> Fix -> $break-loop -> Knowledge capture
-                       |
-                  Deep analysis
 ```
 
-- `$finish-work` - Check work completeness (this skill)
-- `$record-session` - Record session and commits
-- `$break-loop` - Deep analysis after debugging
-
----
-
-## Core Principle
-
-> **Delivery includes not just code, but also documentation, verification, and knowledge capture.**
-
-Complete work = Code + Docs + Tests + Verification
+- `$finish-work` — this skill, survey + archive + record session
+- `$break-loop` — deep analysis after debugging

package/dist/templates/codex/skills/start/SKILL.md

@@ -244,17 +244,21 @@ Use this output format:
 
 **Step 6: Configure Context** `[AI]`
 
-Initialize default context:
+`implement.jsonl` and `check.jsonl` were seeded on `task.py create` with a single self-describing `_example` line. Curate real entries now (see workflow.md Phase 1.3 for the full rule):
+
+- Put **spec files** (`.trellis/spec/<package>/<layer>/*.md`) and **research files** (`{TASK_DIR}/research/*.md`) only.
+- Do NOT put code files (`src/**`, `packages/**`) — those are read during implementation, not pre-registered here.
+- Split: `implement.jsonl` = specs the implement sub-agent needs; `check.jsonl` = specs the check sub-agent needs.
+
+Discover available specs:
 
 ```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
-# type: backend | frontend | fullstack
+python3 ./.trellis/scripts/get_context.py --mode packages
 ```
 
-Add specs found in your research pass:
+Append entries (either edit the jsonl file directly, or):
 
 ```bash
-# For each relevant spec and code pattern:
 python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
 python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
 ```
@@ -265,7 +269,7 @@ python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reas
 python3 ./.trellis/scripts/task.py start "$TASK_DIR"
 ```
 
-This sets `.current-task` so hooks can inject context.
+This sets the active task through Trellis' session resolver so hooks can inject context for this AI session. If the command fails because no session identity is available, rerun it from an IDE/session that exposes session identity or set `TRELLIS_CONTEXT_ID`.
 
 ---
 
@@ -325,9 +329,8 @@ If yes, resume from the appropriate step (usually Step 7 or 8).
 | Script | Purpose |
 |--------|---------|
 | `python3 ./.trellis/scripts/get_context.py` | Get session context |
-| `python3 ./.trellis/scripts/task.py create` | Create task directory |
-| `python3 ./.trellis/scripts/task.py init-context` | Initialize jsonl files |
-| `python3 ./.trellis/scripts/task.py add-context` | Add spec to jsonl |
+| `python3 ./.trellis/scripts/task.py create` | Create task directory (seeds jsonl on sub-agent platforms) |
+| `python3 ./.trellis/scripts/task.py add-context` | Append spec/research entry to jsonl |
 | `python3 ./.trellis/scripts/task.py start` | Set current task |
 | `python3 ./.trellis/scripts/task.py finish` | Clear current task |
 | `python3 ./.trellis/scripts/task.py archive` | Archive completed task |