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

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

@@ -0,0 +1,116 @@
+{
+  "version": "0.5.0-beta.15",
+  "description": "Task runtime and platform compatibility update. `task.py start/current/finish` now use `.trellis/.runtime/sessions/<context-key>.json`; `.trellis/.current-task` is no longer the active-task fallback. `workflow.md` and hook breadcrumbs now allow trivial turns and explicit current-turn overrides to skip Trellis task creation or sub-agent dispatch. Claude Code, Codex, Cursor, OpenCode, and Pi handle shell session identity for `task.py`: Codex uses native `CODEX_SESSION_ID` / `CODEX_THREAD_ID`, while the other hosts propagate `TRELLIS_CONTEXT_ID` through host-specific bridges. Cursor matches `Task|Subagent` and parses native custom-agent payloads. Pi resolves context keys from session manager, environment, transcript path, or process fallback. Template registry downloads support private Git-backed registries through local Git credentials. Claude Code statusLine is no longer installed by default for new projects, while existing Claude Code statusLine files and settings are preserved on update. The manifest also includes 10 hash-verified `safe-file-delete` entries for orphan shared hooks.",
+  "breaking": true,
+  "recommendMigrate": false,
+  "changelog": "**Behavior Changes:**\n- feat(task): `task.py start/current/finish` read and write `.trellis/.runtime/sessions/<context-key>.json`. `.trellis/.current-task` is no longer used as the active-task fallback. `task.py start` exits with a clear error when no session identity is available. `task.py finish` deletes the resolved session file. `task.py archive` deletes session files that still point at the archived task before moving it.\n- feat(init): bootstrap and joiner onboarding tasks no longer write `.trellis/.current-task`; generated PRDs tell the AI to start the task from a session that provides Trellis session identity.\n- feat(workflow): `workflow.md` and hook fallback breadcrumbs now treat no-task trigger words as task-creation signals instead of mandatory creation. Task creation is not required for trivial turns when all three hold: zero file writes, one-reply answer, and no research beyond reading 1-2 repo files. Explicit current-turn phrases such as `skip trellis`, `no task`, `just do it`, `跳过 trellis`, `别走流程`, and `先别建任务` skip task creation for that turn.\n- feat(workflow): `in_progress` breadcrumbs keep `trellis-implement` / `trellis-check` as the default, but explicit current-turn requests such as `do it inline`, `main session 写就行`, and `不用 sub-agent` allow main-session implementation.\n\n**Platform Integration:**\n- feat(hooks): Claude Code writes `TRELLIS_CONTEXT_ID` through `CLAUDE_ENV_FILE`; Codex command environments are supported through `CODEX_SESSION_ID` / Codex Desktop `CODEX_THREAD_ID`; Cursor adds `beforeShellExecution` tickets under `.trellis/.runtime/cursor-shell/`; OpenCode prefixes Bash commands with `TRELLIS_CONTEXT_ID`; Pi injects the same value into Bash and nested `pi --mode json` runs.\n- docs(platforms): GitHub Copilot uses a platform-specific SessionStart hook; Gemini/Qoder/CodeBuddy/Droid/Kiro use shared hook input or platform env; Kilo/Antigravity/Windsurf have no hook integration; `.agents/skills` consumers rely on host-provided prelude/env. All groups share `.trellis/.runtime/sessions/`, while beta.15 adds shell-command handling for Claude Code, Codex, Cursor, OpenCode, and Pi.\n- feat(cursor): Cursor `hooks.json` matches `Task|Subagent`. `inject-subagent-context.py` parses native custom-agent payloads including `{ custom: { name } }` and `{ type: { case: \"custom\", value: { name } } }`.\n- feat(pi): Pi Agent resolves context keys from `TRELLIS_CONTEXT_ID`, `sessionManager.getSessionId()`, `PI_SESSION_ID` / `PI_SESSIONID`, transcript path, or process fallback, then reads active tasks from `.trellis/.runtime/sessions/`.\n- feat(workflow): `workflow-state` breadcrumbs use exact agent names (`trellis-implement`, `trellis-check`, `trellis-research`) and document explicit per-turn override phrases.\n\n**Bug Fixes:**\n- fix(registry): Template registry downloads support private Git-backed registries through local Git credentials. Self-hosted GitLab / GitHub Enterprise and SSH registry sources use Git to read `index.json` and copy template directories, and classify auth, missing-ref, missing-path, invalid-json, and network failures separately instead of falling through to direct-download mode.\n- fix(opencode): OpenCode recognizes `OPENCODE_RUN_ID` and strips the `trellis-` prefix before matching sub-agent names, preserving `implement.jsonl` / `check.jsonl` injection for renamed agents.\n- fix(claude): Claude Code statusLine is no longer installed by default for new projects. Existing `.claude/hooks/statusline.py` files are preserved on update, and an existing `.claude/settings.json` `statusLine` entry is carried forward instead of being forced out.\n- fix(cli): `writeSharedHooks` and `collectSharedHooks` use `SHARED_HOOKS_BY_PLATFORM`. The manifest removes 10 orphan shared-hook files through hash-verified `safe-file-delete` entries; locally modified files are preserved.\n\n**Docs:**\n- docs(beta): docs-site beta pages and `v0.5.0-beta.15` changelog document session-scoped task state, workflow policy relaxation, per-platform session identity behavior, Pi Agent, Cursor hook behavior, native Git worktrees, private Git-backed template registries, Claude Code statusLine defaults, existing statusLine preservation, and the current `continue` / `finish-work` command flow.",
+  "migrations": [
+    {
+      "type": "safe-file-delete",
+      "from": ".cursor/hooks/statusline.py",
+      "description": "Removed: Cursor has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".codex/hooks/statusline.py",
+      "description": "Removed: Codex has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".gemini/hooks/statusline.py",
+      "description": "Removed: Gemini CLI has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".qoder/hooks/statusline.py",
+      "description": "Removed: Qoder has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".github/copilot/hooks/statusline.py",
+      "description": "Removed: GitHub Copilot has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".codebuddy/hooks/statusline.py",
+      "description": "Removed: CodeBuddy has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".factory/hooks/statusline.py",
+      "description": "Removed: Factory Droid has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".kiro/hooks/statusline.py",
+      "description": "Removed: Kiro has no statusLine event; shared-hooks/statusline.py was never invoked.",
+      "allowed_hashes": [
+        "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+        "c92c0020a0c60308437b66f024a244303e708519c97089cf654ceddc144f7435",
+        "b9b0a39a486643f2b78ecb3c757459182a6326ea070ba34a49887e23adc40bbb"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".kiro/hooks/session-start.py",
+      "description": "Removed: Kiro supports only `agentSpawn`; there is no SessionStart event to trigger this script.",
+      "allowed_hashes": [
+        "26b52ad72259316aa5adc8068d0df2a002273d5eda659ac3c71f3f5ecd9ebd08",
+        "ddd59c6fc5e6fa8c8535d6ac375ecaad60f15b87abc6dfc279007e610c636dd8",
+        "597409062bed8f9977750fa6262bb997facce7d8377d3482d4bcb2054e19c491",
+        "6cf36cffba3cf4a3caff99606d9fc9dde07fa4f74b7227aeb08d3de00ced7ca2",
+        "373f2f41c5506982cef1049f0203ca9e442c8074f54880aa021f037c0b9300b0",
+        "bc2026f6b1c195432e1126e1388d11fccec2df7a72010d0daa9fb6af76f683dd",
+        "cf355e44ace5e9b7c7d9a416462d4057a6cff9d5905b8db1839e6e4c892cfd13",
+        "a1b0db7c264da8e7abeb378a16ba8132b99b9918c9546627137d69427108f4b6",
+        "a0256292a2ade20728d71d2ea9a7ce866f6955efe034934eaecbf820244e9ad8"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".kiro/hooks/inject-workflow-state.py",
+      "description": "Removed: Kiro supports only `agentSpawn`; there is no UserPromptSubmit event to trigger this script.",
+      "allowed_hashes": [
+        "281939a51a62467a5dd73947fdec7143d0e936b4b64b5224ce0484186eb5b018",
+        "4231e4e0d52c9b05d66a215c870db30a876201a51350e5191953418ca4ec4637",
+        "50bd086d40654b9fe8cb902d2f321ce06e39b6d4020a6e9aa49154cc371bdb16"
+      ]
+    }
+  ],
+  "notes": "Behavior change: `.trellis/.current-task` is preserved but ignored by active-task resolution. Existing task directories and jsonl files remain valid. `task.py start` now requires session identity from the host or `TRELLIS_CONTEXT_ID`. Run `trellis update` to refresh hooks and templates. The 10 shared-hook cleanup migrations are hash-verified; locally modified hook files are preserved with a warning. Claude Code statusLine is not installed by default for new projects, and existing Claude Code statusLine files/settings are preserved on update."
+}

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

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0-beta.16",
+  "description": "Compatibility patch for template hash portability, task archive inputs, and Claude Code statusLine upgrades. Template hashes now use POSIX keys and LF-normalized content, `task.py archive` accepts the same task directory inputs as the other task commands, and existing Claude Code statusLine installs are preserved during `trellis update`. No migration actions are required.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(cli): Normalize `.trellis/.template-hashes.json` keys to POSIX paths and compute template hashes from LF-normalized content. The hash file now uses a `{ \"__version\": 2, \"hashes\": { ... } }` envelope; legacy flat-format hash files are discarded and regenerated from installed templates.\n- fix(scripts): Align `task.py archive` with other task-directory subcommands. `archive` now accepts a bare task name, `.trellis/tasks/<slug>` relative path, or absolute task path.\n- fix(claude): Preserve existing Claude Code statusLine installs during update. `trellis update` no longer safe-deletes `.claude/hooks/statusline.py`, and if `.claude/settings.json` already has a top-level `statusLine` entry, the updated settings template carries that entry forward.\n\n**Behavior:**\n- New Trellis installs still do not create `.claude/hooks/statusline.py` and do not add `statusLine` to `.claude/settings.json`.\n- Non-Claude orphan `statusline.py` files remain hash-verified safe-delete cleanup targets because those platforms have no `statusLine` event.\n- No `--migrate` gate is required for this patch; the hash file is derived state and is regenerated by normal init/update hashing.",
+  "migrations": [],
+  "notes": "Run `trellis update` to receive the compatibility fixes. Legacy `.trellis/.template-hashes.json` files are regenerated under schema v2, `task.py archive` accepts task names or task paths, and existing Claude Code statusLine files/settings are preserved. No manual migration is required."
+}

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-beta.9.json

@@ -0,0 +1,48 @@
+{
+  "version": "0.5.0-beta.9",
+  "description": "Five coordinated improvements accumulated since beta.8: (1) task.json schema unified across all writers + phase.py/create_bootstrap.py orphan cleanup, (2) workflow tightening — task-creation triggers + research sub-agent delegation, (3) Qoder session-boundary commands split out of the skill matcher into native /trellis-{continue,finish-work}, (4) polyrepo layout detection via sibling .git scan, (5) joiner onboarding task auto-generated for new developers on existing Trellis projects + both bootstrap / joiner PRDs rewritten as AI-facing instructions.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Internal cleanup (no user-facing behavior change):**\n- chore(schema): `task.json` shape unified across all three writers. `packages/cli/src/utils/task-json.ts` introduces a shared `TaskJson` type + `emptyTaskJson(overrides)` factory mirroring the 24-field canonical shape produced by `.trellis/scripts/common/task_store.py cmd_create`. `init.ts getBootstrapTaskJson` and `update.ts` migration-task block now route through the factory. Follows the `quality-guidelines.md` spec lesson 'Schema Deprecation: Audit ALL Writers, Not Just the Creator' captured in 0.5.0-beta.0 — `cmd_create` was cleaned up at the time, but the two TS writers were missed.\n- chore(schema): migration tasks no longer write legacy `current_phase: 0` / `next_action: [...]` fields. These reference the removed Multi-Agent Pipeline and no active reader consumes them in 0.5.\n- chore(bootstrap): bootstrap task's project-type checklist moves from structured `subtasks: [{name, status}]` in task.json to markdown `- [ ]` items in prd.md. Task.json `subtasks` is now canonical `string[]` (child task dir names) across all tasks.\n- chore(cleanup): `.trellis/scripts/common/phase.py` removed. Orphan code (no importers in 0.5); was kept around from the Multi-Agent Pipeline era and not captured by 0.5.0-beta.0's 138-entry safe-file-delete (which only targeted `multi_agent/*`). Hash-verified delete — pristine copies auto-removed, locally modified copies preserved with a warning.\n- chore(cleanup): `.trellis/scripts/create_bootstrap.py` removed. Legacy 4th task.json writer with its own 13-field divergent shape; replaced by `init.ts getBootstrapTaskJson` in 0.4 but the Python file was never deleted. Never invoked by any command. Same hash-verified delete mechanism; three historical hashes included to cover 0.3+ users.\n- chore(cleanup): `TaskData` TypedDict (`common/types.py`) no longer declares `current_phase: int` / `next_action: list[dict]` — dead schema fields.\n- docs: spec directory-trees in `script-conventions.md` (template + local) drop `phase.py` / `create_bootstrap.py` / the full `multi_agent/` block (which was actually removed in 0.5.0-beta.0 but kept appearing in shipped spec docs).\n- chore(pkg): remove 5 orphan `.md` files from `packages/cli/src/templates/markdown/spec/` (`spec/backend/{index,directory-structure,script-conventions}.md` + `spec/guides/{code-reuse,cross-platform}-thinking-guide.md`). These were accidentally added in early 0.1.x releases alongside the proper `.md.txt` stub templates but never imported by `markdown/index.ts` — they shipped in dist/ as dead weight (~35 KB) but never landed on user disks, so no migration entry is needed. Fixes a ~2-year-old duplication bug.\n\n**Workflow tightening (all platforms):**\n- feat(workflow): `workflow.md [workflow-state:no_task]` block + `shared-hooks/inject-workflow-state.py` + OpenCode plugin now enumerate explicit trigger words (`重构` / `抽成` / `独立` / `分发` / `拆出来` / `搞一个` / `做成` / `接入` / `集成` / `refactor` / `rewrite` / `extract` / `productize` / `publish` / `build X` / `design Y`) that REQUIRE task creation, plus a strict three-condition exemption rule (zero file writes + one-reply answer + no external research). Default stance: when in doubt, create a task.\n- feat(workflow): `common/skills/brainstorm.md` gains a 'Delegate to trellis-research sub-agent' section with explicit anti-pattern guidance — 10+ inline WebFetch/WebSearch calls in the main conversation burn tokens and leak raw tool output into context. Correct pattern: spawn trellis-research via Task tool; the sub-agent persists findings to `{TASK_DIR}/research/<topic>.md` and returns only path + one-line summary.\n- feat(workflow): `workflow.md [workflow-state:in_progress]` flow names the actual agent types (`trellis-implement → trellis-check → trellis-update-spec → finish`) instead of generic verbs.\n\n**Qoder UX fix:**\n- feat(qoder): deliver session-boundary commands as native Qoder Custom Commands (`.qoder/commands/trellis-{finish-work,continue}.md`) with YAML frontmatter (`name` + `description`), per docs.qoder.com/en/cli/user-guide/command. Previously these were buried in the skill matcher alongside the 5 auto-trigger workflows, so users had no deterministic way to invoke them — they had to hope their chat wording matched the skill's description. Now they type `/trellis-finish-work` or `/trellis-continue` explicitly.\n- chore(qoder): the 5 auto-trigger workflows (brainstorm, before-dev, check, update-spec, break-loop) stay as `.qoder/skills/trellis-{name}/SKILL.md`. `start` is filtered out because Qoder is agent-capable and its SessionStart hook already injects the workflow overview (same rule that applies to every other agent-capable platform).\n- chore(shared): new `wrapWithCommandFrontmatter` + `COMMAND_DESCRIPTIONS` registry in `configurators/shared.ts` — short, human-facing, imperative one-liners for the `/` palette, distinct from the long auto-trigger prose in `SKILL_DESCRIPTIONS` (written for the skill matcher, not a command list).\n- chore(migration): upgraders have their old `.qoder/skills/trellis-{finish-work,continue}/SKILL.md` hash-verified and auto-deleted on `trellis update` (pristine copies removed silently, locally-modified copies land on the standard confirm prompt).\n\n**New features:**\n- feat(cli): polyrepo detection via sibling `.git` scan. `detectMonorepo()` now has a 7th parser that scans up to 2 levels deep for sibling `.git` directories or worktree gitlinks, firing only when all 6 workspace parsers miss and no submodules are declared (workspace configs always win). `DetectedPackage` gains `isGitRepo` (mutually exclusive with `isSubmodule`); `writeMonorepoConfig` emits `git: true` to bridge to the runtime schema already consumed by `get_git_packages()` in `config.py`. `--monorepo` failure now prints a 7-marker checklist and a manual `config.yaml` example. Init confirm prompt labels polyrepo packages with `(git repo)`.\n- feat(cli): joiner onboarding task auto-generated when a new developer runs `trellis init` on an existing Trellis project (fresh clone / new machine). Three-branch dispatch on `.trellis/` × `.trellis/.developer`: no `.trellis/` = creator bootstrap (unchanged), `.trellis/` + no `.developer` = **joiner** (`00-join-<slug>`), both = no-op. The `.developer` file is gitignored, so it's a clean per-checkout signal; `workspace/<name>/` cannot be used because it's committed. Wired in both the main dispatch AND `handleReinit`'s `doAddDeveloper` branch (the latter is the default path for `trellis init --user <name>` on existing checkouts). Failures surface as `console.warn` instead of being silently swallowed.\n- feat(cli): `trellis init` bootstrap + joiner PRDs rewritten as AI-facing instructions. Previously framed as user-facing docs (`Welcome, do X, ask AI Y`); now framed as instructions TO the AI agent that runs the onboarding task (`You (the AI) are running this task; here's how to onboard them`). Includes runtime-mechanics explainer (SessionStart hook, workflow-state tag, implement/check sub-agents, jsonl manifests) and a suggested opening line. Same content reach, much better first-session UX.",
+  "migrations": [
+    {
+      "type": "safe-file-delete",
+      "from": ".trellis/scripts/common/phase.py",
+      "description": "Remove orphan phase.py — no importers; legacy from Multi-Agent Pipeline",
+      "allowed_hashes": [
+        "412b7096ef0e48b8a95a79060121a586e0d9d44f1b350d6ed818c6f84330bb01"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".trellis/scripts/create_bootstrap.py",
+      "description": "Remove dead create_bootstrap.py — replaced by TS init.ts getBootstrapTaskJson in 0.4; never invoked by any command",
+      "allowed_hashes": [
+        "33b40df671ba7828fd8d3ba8c019823a8b03e938797b1cae218c55d6c7ebe57a",
+        "ce1503c052dadf2470ddb1cade42f331c0fd70d34e895d8d07044ba27548e17e",
+        "aa5dd1f39a77b2f4bb827fd14ce7a83fb51870e77f556fe508afce3f8eac0b4e"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".qoder/skills/trellis-finish-work/SKILL.md",
+      "description": "Qoder session-boundary skill → moved to .qoder/commands/trellis-finish-work.md",
+      "reason": "In 0.5.0-beta.9, Qoder session-boundary commands move out of the skill matcher into native Custom Commands so users can invoke them deterministically as `/trellis-finish-work`.",
+      "allowed_hashes": [
+        "c0f3ffa74e1e9990f93e5d44d03bd088c8698da1db4750b74d3eee4809a84aea",
+        "2027d8ea610e0a929a7ce147b29045406db8a8c9c2a767f98d779e5d53162f0c"
+      ]
+    },
+    {
+      "type": "safe-file-delete",
+      "from": ".qoder/skills/trellis-continue/SKILL.md",
+      "description": "Qoder session-boundary skill → moved to .qoder/commands/trellis-continue.md",
+      "reason": "In 0.5.0-beta.9, Qoder session-boundary commands move out of the skill matcher into native Custom Commands so users can invoke them deterministically as `/trellis-continue`.",
+      "allowed_hashes": [
+        "914545dab290e508a4c6b84d0a9f8debe68bcf9117cebe0fa85be0ef709d8fc1",
+        "3d2c83ad710b3b667851e28a473fb259a1330475e6b7417c769432f4a55a76f9"
+      ]
+    }
+  ],
+  "notes": "Code cleanup + additive features; no user task.json mutations. Python readers (`task.py`, `get_context.py`) treat missing canonical fields as null, so legacy tasks keep working. Newly-created bootstrap / migration tasks from this version onward produce the canonical shape. Qoder users who had the two session-boundary skills installed will see them auto-removed (pristine) or prompted for confirm (modified); the new `.qoder/commands/*.md` are written by the standard configure step on `trellis update`."
+}

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()