@pennixrv/trellis 0.6.38 → 0.6.40

package/dist/migrations/manifests/0.6.39.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.39",
+  "description": "Restores active-task visibility and adds direct completion guidance for analysis-only tasks.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Fixes:**\n- Projects one unique developer-owned resumable task as read-only workflow context when no session pointer exists.\n- Analysis-only research, audit, and design tasks can complete declared evidence work directly from planning and archive without entering implementation.",
+  "migrations": [],
+  "notes": "No project migration is required. Existing projects can run the normal trellis update flow."
+}

package/dist/migrations/manifests/0.6.40.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.40",
+  "description": "Restores active-task visibility when a session pointer is unavailable.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Fix:**\n- Projects one unique developer-owned resumable task as read-only workflow context when no Trellis session pointer exists.",
+  "migrations": [],
+  "notes": "No project migration is required. Existing projects can run the normal trellis update flow."
+}

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

@@ -24,6 +24,7 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
 
 `get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
 
+- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → complete the PRD's bounded evidence work, verify its acceptance criteria and no-change boundary, then commit task artifacts and archive directly. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
 - `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
 - `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
 - `status=planning` + complex artifacts complete + sub-agent jsonl not curated (empty, or only a legacy `_example` placeholder row) → **1.3**

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

@@ -2,6 +2,8 @@
 
 Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command.
 
+For an eligible `task.json.meta.delivery_mode = "analysis_only"` task, reach this command directly from planning only after its PRD-defined evidence, acceptance criteria, and no-change boundary have been verified and its task artifacts have been committed. Do not run `task.py start`; a protected-target change needs a separate change-bearing task.
+
 ## Step 1: Survey current state
 
 ```bash

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

@@ -36,6 +36,7 @@ Index files list the specific guideline docs to read when you actually start cod
 ## Step 4: Decide next action
 From Step 1 you know the current task and status. Check the task directory:
 
+- **Active task with `task.json.meta.delivery_mode = "analysis_only"`** → keep `planning`, complete the PRD's bounded evidence work, then verify the no-change boundary, commit task artifacts, and archive directly. Do not run `task.py start`; any protected-target change needs a separate change-bearing task.
 - **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
 - **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Load the relevant Phase 1 step detail before `task.py start`.
 - **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:

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

@@ -8,6 +8,12 @@ For every non-trivial task, the user must respond at least once after the initia
 
 While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
 
+## Analysis-Only Exception
+
+When `task.json.meta.delivery_mode = "analysis_only"` exactly and the PRD names a bounded evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems, task-creation consent authorizes that evidence work. Do not require a second planning approval or run `task.py start`: perform the declared research, audit, or design work while status remains `planning`, record the evidence, verify acceptance criteria and the boundary, commit task artifacts, and archive directly. If the evidence recommends a protected-target change, record it and create a separate change-bearing task before doing it.
+
+All other tasks follow the planning and implementation approval gates below.
+
 ## Non-Negotiable Evidence Rule
 
 If a question can be answered by exploring the codebase, explore the codebase instead.

package/dist/templates/opencode/lib/trellis-context.js

@@ -377,6 +377,8 @@ export class TrellisContext {
    *   2. If no context key is available and exactly one session runtime file
    *      exists locally, use it (`_resolveSingleSessionFallback`). Refuses to
    *      guess when 0 or ≥2 files exist so multi-window isolation holds.
+   *   3. If no session file exists, expose one resumable task assigned to the
+   *      current developer as a read-only unbound projection.
    */
   getActiveTask(platformInput = null) {
     const contextKey = this.getContextKey(platformInput)
@@ -399,6 +401,11 @@ export class TrellisContext {
       return fallback
     }
 
+    const unbound = this._resolveUnboundTask()
+    if (unbound) {
+      return unbound
+    }
+
     return { taskPath: null, source: "none", stale: false }
   }
 
@@ -440,6 +447,49 @@ export class TrellisContext {
     }
   }
 
+  _resolveUnboundTask() {
+    const sessionsDir = join(this.directory, ".trellis", ".runtime", "sessions")
+    if (existsSync(sessionsDir)) {
+      let sessionFiles
+      try {
+        sessionFiles = readdirSync(sessionsDir).filter(name => name.endsWith(".json"))
+      } catch {
+        return null
+      }
+      if (sessionFiles.length > 0) return null
+    }
+
+    const developer = (process.env.TRELLIS_DEVELOPER || "").trim() || (() => {
+      try {
+        const content = readFileSync(join(this.directory, ".trellis", ".developer"), "utf-8")
+        return content.split(/\r?\n/).find(line => line.startsWith("name="))?.slice(5).trim() || ""
+      } catch {
+        return ""
+      }
+    })()
+    if (!developer) return null
+
+    const tasksDir = join(this.directory, ".trellis", "tasks")
+    let taskNames
+    try {
+      taskNames = readdirSync(tasksDir).filter(name => name !== "archive")
+    } catch {
+      return null
+    }
+
+    const candidates = taskNames.flatMap(name => {
+      try {
+        const data = JSON.parse(readFileSync(join(tasksDir, name, "task.json"), "utf-8"))
+        if (data.assignee !== developer || !["planning", "in_progress", "review"].includes(data.status)) return []
+        return [`.trellis/tasks/${name}`]
+      } catch {
+        return []
+      }
+    })
+    if (candidates.length !== 1) return null
+    return { taskPath: candidates[0], source: "unbound", stale: false }
+  }
+
   getCurrentTask(platformInput = null) {
     return this.getActiveTask(platformInput).taskPath
   }

package/dist/templates/opencode/plugins/inject-workflow-state.js

@@ -156,6 +156,7 @@ function getActiveTask(ctx, platformInput = null) {
     const status = typeof data.status === "string" ? data.status : ""
     if (!status) return null
     const id = data.id || taskRef.split("/").pop()
+    if (active.source === "unbound") return { id, status: "unbound_task", source: active.source }
     return { id, status, source: active.source }
   } catch {
     return null

package/dist/templates/shared-hooks/inject-workflow-state.py

@@ -192,6 +192,8 @@ def get_active_task(
     status = data.get("status", "")
     if not isinstance(status, str) or not status:
         return task_dir.name, "task_error", active.source
+    if active.source_type == "unbound":
+        return task_id, "unbound_task", active.source
     return task_id, status, active.source
 
 

package/dist/templates/trellis/scripts/common/active_task.py

@@ -678,6 +678,10 @@ def resolve_active_task(
         if fallback is not None:
             return fallback
 
+        unbound = _resolve_unbound_task(repo_root)
+        if unbound is not None:
+            return unbound
+
     return ActiveTask(None, "none", context_key)
 
 
@@ -706,6 +710,31 @@ def _resolve_single_session_fallback(repo_root: Path) -> ActiveTask | None:
     return _active_from_ref(task_ref, repo_root, "session-fallback", fallback_key)
 
 
+def _resolve_unbound_task(repo_root: Path) -> ActiveTask | None:
+    """Expose one developer-owned task when no session pointer exists."""
+    sessions_dir = _runtime_sessions_dir(repo_root)
+    if sessions_dir.is_dir() and any(sessions_dir.glob("*.json")):
+        return None
+
+    from .paths import get_developer, get_tasks_dir
+    from .tasks import iter_active_tasks
+
+    developer = get_developer(repo_root)
+    if not developer:
+        return None
+
+    candidates = [
+        task
+        for task in iter_active_tasks(get_tasks_dir(repo_root))
+        if task.assignee == developer and task.status in {"planning", "in_progress", "review"}
+    ]
+    if len(candidates) != 1:
+        return None
+
+    task_path = candidates[0].directory.relative_to(repo_root).as_posix()
+    return ActiveTask(task_path, "unbound", None)
+
+
 def _utc_now() -> str:
     return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 

package/dist/templates/trellis/scripts/task.py

@@ -308,6 +308,11 @@ def cmd_finish(args: argparse.Namespace) -> int:
         print(colored("No current task set", Colors.YELLOW))
         return 0
 
+    if active.source_type == "unbound":
+        print(colored("Task exists but no direct session is bound; run task.py start first", Colors.YELLOW))
+        print(f"Task: {current}")
+        return 0
+
     try:
         assert_task_mutation_allowed(repo_root, repo_root / current)
     except (OwnershipError, OSError) as exc:

package/dist/templates/trellis/workflow.md

@@ -64,6 +64,7 @@ python3 ./.trellis/scripts/task.py validate <name>
 python3 ./.trellis/scripts/task.py set-branch <name> <branch>
 python3 ./.trellis/scripts/task.py set-base-branch <name> <branch>    # PR target
 python3 ./.trellis/scripts/task.py set-scope <name> <scope>
+python3 ./.trellis/scripts/task.py set-meta <name> delivery_mode analysis_only
 
 # Hierarchy (parent/child)
 python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
@@ -121,6 +122,7 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # detailed
 
   TAG ↔ PHASE scoping:
     [workflow-state:no_task]      → no active task; before Phase 1
+    [workflow-state:unbound_task] → one developer-owned task exists without a session pointer
     [workflow-state:task_error]   → active task record is unreadable; repair it before continuing
     [workflow-state:planning]     → all of Phase 1 (status='planning')
     [workflow-state:planning-inline] → Codex inline variant of Phase 1
@@ -158,6 +160,12 @@ Phase 3: Finish  → verify, update spec, commit, and wrap up
 - Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
 - User approval to create a task is not approval to start implementation. Planning still happens first.
 
+### Analysis-only tasks
+
+An analysis-only task is eligible only when `task.json.meta.delivery_mode = "analysis_only"` exactly and its `prd.md` names the evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems. Task creation consent authorizes that bounded evidence work, not protected-target changes.
+
+Keep an eligible analysis-only task in `planning`: write its research, audit, or design evidence; verify its acceptance criteria and boundary; commit task artifacts; then archive directly. Do not run `task.py start`, configure implementation context, or wait for a second implementation approval. If the evidence recommends a protected-target change, record the recommendation and create a separate change-bearing task before doing it.
+
 ### Planning Artifacts
 
 - `prd.md` — requirements, constraints, and acceptance criteria. Do not put technical design or execution checklists here.
@@ -182,6 +190,12 @@ Simple conversation / small task: ask only whether this turn should create a Tre
 Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
 [/workflow-state:no_task]
 
+<!-- Per-turn breadcrumb: shown when one resumable task exists without a direct session binding. -->
+
+[workflow-state:unbound_task]
+An existing task is assigned to the current developer, but this shell has no direct Trellis session binding. Do not create a duplicate task. Continue reading and working from the existing task artifacts; before any lifecycle write or closure, run the native `task.py start <task>` command once a direct session identity is available. Never edit `.trellis/.runtime/sessions/` manually.
+[/workflow-state:unbound_task]
+
 <!-- Per-turn breadcrumb: shown when the active task record cannot be read. -->
 
 [workflow-state:task_error]
@@ -194,14 +208,15 @@ Preserve existing task fields and artifacts. If the correct status cannot be det
 - 1.0 Create task `[required · once]` (only after task-creation consent)
 - 1.1 Requirement exploration `[required · repeatable]` (`prd.md`; complex tasks also need `design.md` + `implement.md`)
 - 1.2 Research `[optional · repeatable]`
-- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Grok, Kimi Code (sub-agent-dispatch platforms only; inline platforms skip)
-- 1.4 Activate task `[required · once]` (review gate, then `task.py start`; status → in_progress)
+- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Grok, Kimi Code (sub-agent-dispatch platforms only; inline and eligible analysis-only tasks skip)
+- 1.4 Activate task `[required · once]` (change-bearing tasks only: review gate, then `task.py start`; status → in_progress)
 - 1.5 Completion criteria
 
 <!-- Per-turn breadcrumb: shown throughout Phase 1 (status='planning') -->
 
 [workflow-state:planning]
 Load `trellis-brainstorm`; stay in planning.
+If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete the declared evidence work now. Do not wait for a start review or run `task.py start`; when the PRD boundary and acceptance evidence pass, commit task artifacts and archive directly. A protected-target recommendation requires a separate change-bearing task.
 Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
 Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
 Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
@@ -215,6 +230,7 @@ Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research mani
 
 [workflow-state:planning-inline]
 Load `trellis-brainstorm`; stay in planning.
+If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete the declared evidence work now. Do not wait for a start review or run `task.py start`; when the PRD boundary and acceptance evidence pass, commit task artifacts and archive directly. A protected-target recommendation requires a separate change-bearing task.
 Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
 Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
 Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-before-dev`.
@@ -286,6 +302,7 @@ When a user request matches one of these intents inside an active task, route fi
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 
 - Planning or unclear requirements -> `trellis-brainstorm`.
+- Explicit eligible `analysis_only` -> complete evidence in planning, then commit artifacts and archive directly.
 - `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`.
 - Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
 
@@ -294,6 +311,7 @@ When a user request matches one of these intents inside an active task, route fi
 [codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
 
 - Planning or unclear requirements -> `trellis-brainstorm`.
+- Explicit eligible `analysis_only` -> complete evidence in planning, then commit artifacts and archive directly.
 - Before editing -> `trellis-before-dev`; after editing -> `trellis-check`.
 - Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
 
@@ -301,7 +319,8 @@ When a user request matches one of these intents inside an active task, route fi
 
 ### Guardrails
 
-- Task creation approval is not implementation approval; implementation waits for `task.py start` after artifact review.
+- Only an eligible `task.json.meta.delivery_mode = "analysis_only"` task may complete while `planning`; it may write evidence artifacts, but any protected-target change requires a separate change-bearing task.
+- Task creation approval is not implementation approval; change-bearing implementation waits for `task.py start` after artifact review.
 - PRD-only is valid for lightweight tasks; complex tasks need `design.md` + `implement.md`.
 - Planning must be persisted to task artifacts; checks must run before reporting completion.
 
@@ -336,12 +355,16 @@ After this command succeeds, the per-turn breadcrumb auto-switches to `[workflow
 
 Run only `create` here — do not also run `start`. `start` flips status to `in_progress`, which switches the breadcrumb to the implementation phase before planning artifacts are reviewed. Save `start` for step 1.4.
 
+For an evidence-only task, set `task.json.meta.delivery_mode = "analysis_only"` at creation or with `task.py set-meta`. Its PRD must name the evidence deliverable and exclude protected-target changes before the task proceeds.
+
 Skip when `python3 ./.trellis/scripts/task.py current --source` already points to a task.
 
 #### 1.1 Requirement exploration `[required · repeatable]`
 
 Load the `trellis-brainstorm` skill and explore requirements interactively with the user per the skill's guidance.
 
+For an eligible analysis-only task, converge the PRD boundary, then perform the declared research, audit, or design work in this phase. It does not need a start review or `task.py start`; after acceptance evidence is recorded, continue directly to Phase 3.3.
+
 The brainstorm skill will guide you to:
 - Ask one question at a time
 - Prefer researching over asking the user
@@ -391,6 +414,8 @@ Brainstorm and research can interleave freely — pause to research a technical
 
 #### 1.3 Configure context `[required · once]`
 
+Eligible analysis-only tasks skip this step because they never enter Phase 2 or dispatch implementation/check agents.
+
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 
 Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec/research context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
@@ -446,6 +471,8 @@ Skip this step. Context is loaded directly by the `trellis-before-dev` skill in
 
 #### 1.4 Activate task `[required · once]`
 
+This step applies only to change-bearing tasks. An eligible analysis-only task stays in `planning` and, after its evidence work is complete, continues directly to Phase 3.3 without running `task.py start`.
+
 After artifact review, flip the task status to `in_progress`:
 
 ```bash
@@ -463,15 +490,16 @@ If `task.py start` errors with a session-identity message (no context key from h
 | Condition | Required |
 |------|:---:|
 | `prd.md` exists | ✅ |
-| User confirms task should enter implementation | ✅ |
-| `task.py start` has been run (status = in_progress) | ✅ |
+| Change-bearing task: user confirms implementation | ✅ |
+| Change-bearing task: `task.py start` has been run (status = in_progress) | ✅ |
+| Analysis-only task: exact metadata, named evidence deliverable, recorded acceptance evidence, and protected targets unchanged | ✅ |
 | `research/` has artifacts (complex tasks) | recommended |
 | `design.md` exists (complex tasks) | ✅ |
 | `implement.md` exists (complex tasks) | ✅ |
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 
-| `implement.jsonl` and `check.jsonl` each contain at least one real curated entry (seed row does not count) | ✅ |
+| Change-bearing task: `implement.jsonl` and `check.jsonl` each contain at least one real curated entry (seed row does not count) | ✅ |
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 
@@ -579,6 +607,8 @@ If issues are found → fix → re-check, until green.
 
 Goal: ensure code quality, capture lessons, record the work.
 
+**Analysis-only completion route**: after the evidence work in Phase 1, verify the PRD acceptance criteria and no-change boundary, then continue with 3.3 and 3.4 for task artifacts only before `/trellis:finish-work`. Do not run Phase 2 or `task.py start`.
+
 #### 3.2 Debug retrospective `[on demand]`
 
 If this task involved repeated debugging (the same issue was fixed multiple times), load the `trellis-break-loop` skill to:
@@ -671,6 +701,7 @@ All tag blocks live in the `## Phase Index` section above, immediately after eac
 | Scope | Corresponding tag |
 |---|---|
 | No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
+| One developer-owned task without a session binding | `[workflow-state:unbound_task]` (bind before lifecycle writes) |
 | Active task record unreadable | `[workflow-state:task_error]` (repair the existing task before continuing) |
 | All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
 | Codex inline Phase 1 | `[workflow-state:planning-inline]` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennixrv/trellis",
-  "version": "0.6.38",
+  "version": "0.6.40",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "inquirer": "^9.3.7",
     "undici": "^6.21.0",
     "zod": "^4.4.2",
-    "@pennixrv/trellis-core": "0.6.38"
+    "@pennixrv/trellis-core": "0.6.40"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",