@mindfoldhq/trellis 0.5.0-rc.0 → 0.5.0-rc.1

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

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0-rc.1",
+  "description": "Patches rc.0 with two OpenCode fixes: trellis-research subagent gains write permission and persists findings to {TASK_DIR}/research/ (#211); session-start.js extracts named exports to lib/session-utils.js so the OpenCode 1.2.x loader reaches export default (#212). No new migrations.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(opencode): `trellis-research` subagent template grants `write: allow` / `edit: allow` and the prompt body now matches the cursor/claude shape (Core Principle, Workflow Step 1–5 with `mkdir -p {TASK_DIR}/research/`, Scope Limits, File Format, DO/DON'T). The redundant 'Context Self-Loading' section is removed; `inject-subagent-context.js` already pre-loads spec dir context (#211).\n- fix(opencode): extract `buildSessionContext` and `hasInjectedTrellisContext` from `.opencode/plugins/session-start.js` into `lib/session-utils.js` so each plugin file has only `export default`. The OpenCode 1.2.x loader iterates `Object.entries(mod)` and invokes every export as a factory; the named exports caused the loader to abort before reaching the default export (#212).\n\n**Testing:**\n- test(opencode): walk `templates/opencode/plugins/*.js` and assert each file has exactly one top-level export matching `^export\\s+default\\s/` to prevent #212-class regressions.\n- test(opencode): extend the `research agent persists findings to task dir` regression group with an OpenCode-specific case asserting YAML `permission:` frontmatter and body contents, closing the gap that masked #211.",
+  "migrations": [],
+  "notes": "RC install: `npm install -g @mindfoldhq/trellis@rc`. Projects on 0.5 (beta or rc.0) run `trellis update`. Projects upgrading from 0.4.x run `trellis update --migrate`; the 0.5 migration chain begins at 0.5.0-beta.0. rc.1 adds no new migration entries."
+}

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

@@ -1,11 +1,11 @@
 ---
 description: |
-  Code and tech search expert. Pure research, no code modifications. Finds files, patterns, and tech solutions.
+  Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory.
 mode: subagent
 permission:
   read: allow
-  write: deny
-  edit: deny
+  write: allow
+  edit: allow
   bash: allow
   glob: allow
   grep: allow
@@ -16,114 +16,113 @@ permission:
 
 You are the Research Agent in the Trellis workflow.
 
-## Context Self-Loading
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
 
-**If you see "# Research Agent Task" header with pre-loaded context above, skip this section.**
+Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session.
 
-Otherwise, if task-specific research is needed:
+---
 
-1. Run `python3 ./.trellis/scripts/task.py current --source` → get active task directory and source (if set)
-2. For each entry in JSONL (if task dir exists):
-   - If `path` is a file → Read it
-   - If `path` is a directory → Read all `.md` files in it
+## Core Responsibilities
 
-Project spec locations for reference:
-- `.trellis/spec/<package>/<layer>/` - Package-specific standards
-- `.trellis/spec/guides/` - Thinking guides
-- `.trellis/big-question/` - Known issues and pitfalls
+1. **Internal Search** — locate files/components, understand code logic, discover patterns (Glob, Grep, Read)
+2. **External Search** — library docs, API references, best practices (web search)
+3. **Persist** — write each research topic to `{TASK_DIR}/research/<topic>.md`
+4. **Report** — return file paths + one-line summaries to the main agent (not full content)
 
 ---
 
-## Core Principle
+## Workflow
 
-**You do one thing: find and explain information.**
+### Step 1: Resolve Current Task
 
-You are a documenter, not a reviewer. Your job is to help get the information needed.
+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:
 
-## Core Responsibilities
+```bash
+mkdir -p <TASK_DIR>/research
+```
 
-### 1. Internal Search (Project Code)
+### Step 2: Understand Search Request
 
-| Search Type | Goal | Tools |
-|-------------|------|-------|
-| **WHERE** | Locate files/components | Glob, Grep |
-| **HOW** | Understand code logic | Read, Grep |
-| **PATTERN** | Discover existing patterns | Grep, Read |
+Classify: internal / external / mixed. Determine scope (global / specific directory) and expected shape (file list / pattern notes / tech comparison).
 
-### 2. External Search (Tech Solutions)
+### Step 3: Execute Search
 
-Use web search for best practices and code examples.
+Run independent searches in parallel (Glob + Grep + web) for efficiency.
 
----
+### Step 4: Persist Each Topic
 
-## Strict Boundaries
+For each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.
 
-### Only Allowed
+### Step 5: Report to Main Agent
 
-- Describe **what exists**
-- Describe **where it is**
-- Describe **how it works**
-- Describe **how components interact**
+Reply with ONLY:
 
-### Forbidden (unless explicitly asked)
+- List of files written (paths relative to repo root)
+- One-line summary per file
+- Any critical caveats that the main agent needs to know right now
 
-- Suggest improvements
-- Criticize implementation
-- Recommend refactoring
-- Modify any files
-- Execute git commands
+Do NOT paste full research content into the reply. The files are the contract.
 
 ---
 
-## Workflow
-
-### Step 1: Understand Search Request
+## Scope Limits (Strict)
 
-Analyze the query, determine:
+### Write ALLOWED
 
-- Search type (internal/external/mixed)
-- Search scope (global/specific directory)
-- Expected output (file list/code patterns/tech solutions)
+- `{TASK_DIR}/research/*.md` — your own output
+- Creating `{TASK_DIR}/research/` if it doesn't exist (via `mkdir -p`)
 
-### Step 2: Execute Search
+### Write FORBIDDEN
 
-Execute multiple independent searches in parallel for efficiency.
+- Code files (`src/`, `lib/`, …)
+- Spec files (`.trellis/spec/`) — main agent should use `update-spec` skill instead
+- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.claude/`, `.cursor/`, `.opencode/`, etc.)
+- Other task directories
+- Any git operation (commit / push / branch / merge)
 
-### Step 3: Organize Results
-
-Output structured results in report format.
+If the user asks you to edit code, decline and suggest spawning `implement` instead.
 
 ---
 
-## Report Format
+## File Format
+
+Each `{TASK_DIR}/research/<topic>.md` should follow:
 
 ```markdown
-## Search Results
+# Research: <topic>
 
-### Query
+- **Query**: <original query>
+- **Scope**: <internal / external / mixed>
+- **Date**: <YYYY-MM-DD>
 
-{original query}
+## Findings
 
 ### Files Found
 
 | File Path | Description |
-|-----------|-------------|
+|---|---|
 | `src/services/xxx.ts` | Main implementation |
 | `src/types/xxx.ts` | Type definitions |
 
-### Code Pattern Analysis
+### Code Patterns
+
+<describe patterns, cite file:line>
+
+### External References
 
-{Describe discovered patterns, cite specific files and line numbers}
+- [Library X docs](url) — <why relevant, version constraints>
 
-### Related Spec Documents
+### Related Specs
 
-- `.trellis/spec/xxx.md` - {description}
+- `.trellis/spec/xxx.md` — <description>
 
-### Not Found
+## Caveats / Not Found
 
-{If some content was not found, explain}
+<anything incomplete or uncertain>
 ```
 
 ---
@@ -134,12 +133,13 @@ Output structured results in report format.
 
 - Provide specific file paths and line numbers
 - Quote actual code snippets
-- Distinguish "definitely found" and "possibly related"
-- Explain search scope and limitations
+- Persist every topic to its own file
+- Return file paths in your reply, not the full content
+- Mark "not found" explicitly when searches come up empty
 
 ### DON'T
 
+- Don't write code or modify files outside `{TASK_DIR}/research/`
 - Don't guess uncertain info
-- Don't omit important search results
-- Don't add improvement suggestions in report (unless explicitly asked)
-- Don't modify any files
+- Don't paste full research text into the reply (files are the deliverable)
+- Don't propose improvements or critique implementation (that's not your role)

package/dist/templates/opencode/lib/session-utils.js

@@ -0,0 +1,432 @@
+/* global process */
+import { existsSync, readFileSync, readdirSync, statSync } from "fs"
+import { basename, join } from "path"
+import { execFileSync } from "child_process"
+import { platform } from "os"
+import { debugLog } from "./trellis-context.js"
+
+const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
+
+const 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>`
+
+function hasCuratedJsonlEntry(jsonlPath) {
+  try {
+    const content = readFileSync(jsonlPath, "utf-8")
+    for (const rawLine of content.split(/\r?\n/)) {
+      const line = rawLine.trim()
+      if (!line) continue
+      try {
+        const row = JSON.parse(line)
+        if (row && typeof row === "object" && typeof row.file === "string" && row.file) {
+          return true
+        }
+      } catch {
+        // Ignore malformed line
+      }
+    }
+  } catch {
+    return false
+  }
+  return false
+}
+
+function getTaskStatus(ctx, platformInput = null) {
+  const active = ctx.getActiveTask(platformInput)
+  const taskRef = active.taskPath
+  if (!taskRef) {
+    return `Status: NO ACTIVE TASK\nSource: ${active.source}\nNext: Describe what you want to work on`
+  }
+
+  const taskDir = ctx.resolveTaskDir(taskRef)
+
+  if (active.stale || !taskDir || !existsSync(taskDir)) {
+    return `Status: STALE POINTER\nTask: ${taskRef}\nSource: ${active.source}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish`
+  }
+
+  let taskData = {}
+  const taskJsonPath = join(taskDir, "task.json")
+  if (existsSync(taskJsonPath)) {
+    try {
+      taskData = JSON.parse(readFileSync(taskJsonPath, "utf-8"))
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  const taskTitle = taskData.title || taskRef
+  const taskStatus = taskData.status || "unknown"
+
+  if (taskStatus === "completed") {
+    const dirName = basename(taskDir)
+    return `Status: COMPLETED\nTask: ${taskTitle}\nSource: ${active.source}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
+  }
+
+  let hasContext = false
+  for (const jsonlName of ["implement.jsonl", "check.jsonl"]) {
+    const jsonlPath = join(taskDir, jsonlName)
+    if (existsSync(jsonlPath) && hasCuratedJsonlEntry(jsonlPath)) {
+      hasContext = true
+      break
+    }
+  }
+
+  const hasPrd = existsSync(join(taskDir, "prd.md"))
+
+  if (!hasPrd) {
+    return `Status: NOT READY\nTask: ${taskTitle}\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 (!hasContext) {
+    return `Status: NOT READY\nTask: ${taskTitle}\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 (
+    `Status: READY\nTask: ${taskTitle}\n` +
+    `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."
+  )
+}
+
+function loadTrellisConfig(directory, contextKey = null) {
+  const scriptPath = join(directory, ".trellis", "scripts", "get_context.py")
+  if (!existsSync(scriptPath)) {
+    return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
+  }
+  try {
+    const output = execFileSync(PYTHON_CMD, [scriptPath, "--mode", "packages", "--json"], {
+      cwd: directory,
+      timeout: 5000,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        ...(contextKey ? { TRELLIS_CONTEXT_ID: contextKey } : {}),
+      },
+    })
+    const data = JSON.parse(output)
+    if (data.mode !== "monorepo") {
+      return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
+    }
+    const pkgDict = {}
+    for (const pkg of (data.packages || [])) {
+      pkgDict[pkg.name] = pkg
+    }
+    return {
+      isMonorepo: true,
+      packages: pkgDict,
+      specScope: data.specScope || null,
+      activeTaskPackage: data.activeTaskPackage || null,
+      defaultPackage: data.defaultPackage || null,
+    }
+  } catch (e) {
+    debugLog("session", "loadTrellisConfig error:", e.message)
+    return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
+  }
+}
+
+function checkLegacySpec(directory, config) {
+  if (!config.isMonorepo || Object.keys(config.packages).length === 0) {
+    return null
+  }
+
+  const specDir = join(directory, ".trellis", "spec")
+  if (!existsSync(specDir)) return null
+
+  let hasLegacy = false
+  for (const name of ["backend", "frontend"]) {
+    if (existsSync(join(specDir, name, "index.md"))) {
+      hasLegacy = true
+      break
+    }
+  }
+  if (!hasLegacy) return null
+
+  const pkgNames = Object.keys(config.packages).sort()
+  const missing = pkgNames.filter(name => !existsSync(join(specDir, name)))
+
+  if (missing.length === 0) return null
+
+  if (missing.length === pkgNames.length) {
+    return (
+      `[!] Legacy spec structure detected: found \`spec/backend/\` or \`spec/frontend/\` ` +
+      `but no package-scoped \`spec/<package>/\` directories.\n` +
+      `Monorepo packages: ${pkgNames.join(", ")}\n` +
+      `Please reorganize: \`spec/backend/\` -> \`spec/<package>/backend/\``
+    )
+  }
+  return (
+    `[!] Partial spec migration detected: packages ${missing.join(", ")} ` +
+    `still missing \`spec/<pkg>/\` directory.\n` +
+    `Please complete migration for all packages.`
+  )
+}
+
+function resolveSpecScope(config) {
+  if (!config.isMonorepo || Object.keys(config.packages).length === 0) {
+    return null
+  }
+
+  const { specScope, activeTaskPackage, defaultPackage, packages } = config
+  if (specScope == null) return null
+
+  if (specScope === "active_task") {
+    if (activeTaskPackage && activeTaskPackage in packages) return new Set([activeTaskPackage])
+    if (defaultPackage && defaultPackage in packages) return new Set([defaultPackage])
+    return null
+  }
+
+  if (Array.isArray(specScope)) {
+    const valid = new Set()
+    for (const entry of specScope) {
+      if (entry in packages) {
+        valid.add(entry)
+      }
+    }
+    if (valid.size > 0) return valid
+    if (activeTaskPackage && activeTaskPackage in packages) return new Set([activeTaskPackage])
+    if (defaultPackage && defaultPackage in packages) return new Set([defaultPackage])
+    return null
+  }
+
+  return null
+}
+
+export function buildSessionContext(ctx, platformInput = null) {
+  const directory = ctx.directory
+  const trellisDir = join(directory, ".trellis")
+  const contextKey = typeof ctx.getContextKey === "function"
+    ? ctx.getContextKey(platformInput)
+    : null
+
+  const config = loadTrellisConfig(directory, contextKey)
+  const allowedPkgs = resolveSpecScope(config)
+
+  const parts = []
+
+  parts.push(`<trellis-context>
+You are starting a new session in a Trellis-managed project.
+Read and follow all instructions below carefully.
+</trellis-context>`)
+  parts.push(FIRST_REPLY_NOTICE)
+
+  const legacyWarning = checkLegacySpec(directory, config)
+  if (legacyWarning) {
+    parts.push(`<migration-warning>\n${legacyWarning}\n</migration-warning>`)
+  }
+
+  const contextScript = join(trellisDir, "scripts", "get_context.py")
+  if (existsSync(contextScript)) {
+    const output = ctx.runScript(contextScript, undefined, contextKey)
+    if (output) {
+      parts.push("<current-state>")
+      parts.push(output)
+      parts.push("</current-state>")
+    }
+  }
+
+  const workflowContent = ctx.readProjectFile(".trellis/workflow.md")
+  if (workflowContent) {
+    const allLines = workflowContent.split("\n")
+    const overviewLines = [
+      "# Development Workflow — Section Index",
+      "Full guide: .trellis/workflow.md  (read on demand)",
+      "",
+      "## Table of Contents",
+    ]
+    for (const line of allLines) {
+      if (line.startsWith("## ")) overviewLines.push(line)
+    }
+    overviewLines.push("", "---", "")
+
+    let rangeStart = -1
+    let rangeEnd = allLines.length
+    for (let i = 0; i < allLines.length; i++) {
+      const stripped = allLines[i].trim()
+      if (rangeStart === -1 && stripped === "## Phase Index") {
+        rangeStart = i
+      } else if (rangeStart !== -1 && stripped === "## Workflow State Breadcrumbs") {
+        rangeEnd = i
+        break
+      }
+    }
+    if (rangeStart !== -1) {
+      overviewLines.push(...allLines.slice(rangeStart, rangeEnd))
+    }
+
+    parts.push("<workflow>")
+    parts.push(overviewLines.join("\n").trimEnd())
+    parts.push("</workflow>")
+  }
+
+  parts.push("<guidelines>")
+  parts.push(
+    "Project spec indexes are listed by path below. Each index contains a " +
+    "**Pre-Development Checklist** listing the specific guideline files to " +
+    "read before coding.\n\n" +
+    "- 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" +
+    "- For agent-capable platforms, do NOT edit code directly in the main " +
+    "session; dispatch `trellis-implement` and `trellis-check` so JSONL " +
+    "context is loaded by the sub-agents.\n"
+  )
+
+  const specDir = join(directory, ".trellis", "spec")
+
+  const guidesIndex = join(specDir, "guides", "index.md")
+  if (existsSync(guidesIndex)) {
+    const content = ctx.readFile(guidesIndex)
+    if (content) {
+      parts.push(`## guides (inlined — cross-package thinking guides)\n${content}\n`)
+    }
+  }
+
+  const paths = []
+  if (existsSync(specDir)) {
+    try {
+      const subs = readdirSync(specDir).filter(name => {
+        if (name.startsWith(".")) return false
+        try {
+          return statSync(join(specDir, name)).isDirectory()
+        } catch {
+          return false
+        }
+      }).sort()
+
+      for (const sub of subs) {
+        if (sub === "guides") continue
+
+        const indexFile = join(specDir, sub, "index.md")
+        if (existsSync(indexFile)) {
+          paths.push(`.trellis/spec/${sub}/index.md`)
+        } else {
+          if (allowedPkgs !== null && !allowedPkgs.has(sub)) continue
+          try {
+            const nested = readdirSync(join(specDir, sub)).filter(name => {
+              try {
+                return statSync(join(specDir, sub, name)).isDirectory()
+              } catch {
+                return false
+              }
+            }).sort()
+            for (const layer of nested) {
+              const nestedIndex = join(specDir, sub, layer, "index.md")
+              if (existsSync(nestedIndex)) {
+                paths.push(`.trellis/spec/${sub}/${layer}/index.md`)
+              }
+            }
+          } catch {
+            // Ignore directory read errors
+          }
+        }
+      }
+    } catch {
+      // Ignore spec directory read errors
+    }
+  }
+
+  if (paths.length > 0) {
+    parts.push("## Available spec indexes (read on demand)")
+    for (const p of paths) {
+      parts.push(`- ${p}`)
+    }
+    parts.push("")
+  }
+
+  parts.push(
+    "Discover more via: " +
+    "`python3 ./.trellis/scripts/get_context.py --mode packages`"
+  )
+  parts.push("</guidelines>")
+
+  const taskStatus = getTaskStatus(ctx, platformInput)
+  parts.push(`<task-status>\n${taskStatus}\n</task-status>`)
+
+  parts.push(`<ready>
+Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
+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>`)
+
+  return parts.join("\n\n")
+}
+
+function getTrellisMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object") {
+    return {}
+  }
+
+  const trellis = metadata.trellis
+  if (!trellis || typeof trellis !== "object") {
+    return {}
+  }
+
+  return trellis
+}
+
+function markPartAsSessionStart(part) {
+  const metadata = part.metadata && typeof part.metadata === "object"
+    ? part.metadata
+    : {}
+  part.metadata = {
+    ...metadata,
+    trellis: {
+      ...getTrellisMetadata(metadata),
+      sessionStart: true,
+    },
+  }
+}
+
+function hasSessionStartMarker(part) {
+  if (!part || part.type !== "text" || typeof part.text !== "string") {
+    return false
+  }
+
+  return getTrellisMetadata(part.metadata).sessionStart === true
+}
+
+export function hasInjectedTrellisContext(messages) {
+  if (!Array.isArray(messages)) {
+    return false
+  }
+
+  return messages.some(message => {
+    if (!message?.info || message.info.role !== "user" || !Array.isArray(message.parts)) {
+      return false
+    }
+
+    return message.parts.some(hasSessionStartMarker)
+  })
+}
+
+export async function hasPersistedInjectedContext(client, directory, sessionID) {
+  try {
+    const response = await client.session.messages({
+      path: { id: sessionID },
+      query: { directory },
+      throwOnError: true,
+    })
+    return hasInjectedTrellisContext(response.data || [])
+  } catch (error) {
+    debugLog(
+      "session",
+      "Failed to read session history for dedupe:",
+      error instanceof Error ? error.message : String(error),
+    )
+    return false
+  }
+}
+
+export function markContextInjected(part) {
+  markPartAsSessionStart(part)
+}

package/dist/templates/opencode/plugins/session-start.js

@@ -6,476 +6,12 @@
  * Uses OpenCode's chat.message hook directly so the context persists in history.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "fs"
-import { basename, join } from "path"
-import { execFileSync } from "child_process"
-import { platform } from "os"
 import { TrellisContext, contextCollector, debugLog } from "../lib/trellis-context.js"
-
-const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
-
-const 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>`
-
-
-/**
- * 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 `shared-hooks/inject-subagent-context.py`.
- */
-function hasCuratedJsonlEntry(jsonlPath) {
-  try {
-    const content = readFileSync(jsonlPath, "utf-8")
-    for (const rawLine of content.split(/\r?\n/)) {
-      const line = rawLine.trim()
-      if (!line) continue
-      try {
-        const row = JSON.parse(line)
-        if (row && typeof row === "object" && typeof row.file === "string" && row.file) {
-          return true
-        }
-      } catch {
-        // Ignore malformed line — move on.
-      }
-    }
-  } catch {
-    return false
-  }
-  return false
-}
-
-/**
- * Check current task status and return structured status string.
- * JavaScript equivalent of _get_task_status in Claude's session-start.py.
- */
-function getTaskStatus(ctx, platformInput = null) {
-  const active = ctx.getActiveTask(platformInput)
-  const taskRef = active.taskPath
-  if (!taskRef) {
-    return `Status: NO ACTIVE TASK\nSource: ${active.source}\nNext: Describe what you want to work on`
-  }
-
-  const taskDir = ctx.resolveTaskDir(taskRef)
-
-  if (active.stale || !taskDir || !existsSync(taskDir)) {
-    return `Status: STALE POINTER\nTask: ${taskRef}\nSource: ${active.source}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish`
-  }
-
-  let taskData = {}
-  const taskJsonPath = join(taskDir, "task.json")
-  if (existsSync(taskJsonPath)) {
-    try {
-      taskData = JSON.parse(readFileSync(taskJsonPath, "utf-8"))
-    } catch {
-      // Ignore parse errors
-    }
-  }
-
-  const taskTitle = taskData.title || taskRef
-  const taskStatus = taskData.status || "unknown"
-
-  if (taskStatus === "completed") {
-    const dirName = basename(taskDir)
-    return `Status: COMPLETED\nTask: ${taskTitle}\nSource: ${active.source}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
-  }
-
-  let hasContext = false
-  for (const jsonlName of ["implement.jsonl", "check.jsonl"]) {
-    const jsonlPath = join(taskDir, jsonlName)
-    if (existsSync(jsonlPath) && hasCuratedJsonlEntry(jsonlPath)) {
-      hasContext = true
-      break
-    }
-  }
-
-  const hasPrd = existsSync(join(taskDir, "prd.md"))
-
-  if (!hasPrd) {
-    return `Status: NOT READY\nTask: ${taskTitle}\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 (!hasContext) {
-    return `Status: NOT READY\nTask: ${taskTitle}\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 (
-    `Status: READY\nTask: ${taskTitle}\n` +
-    `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."
-  )
-}
-
-/**
- * Load Trellis config for session-start decisions.
- * Calls get_context.py --mode packages --json for reliable config data.
- */
-function loadTrellisConfig(directory, contextKey = null) {
-  const scriptPath = join(directory, ".trellis", "scripts", "get_context.py")
-  if (!existsSync(scriptPath)) {
-    return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
-  }
-  try {
-    const output = execFileSync(PYTHON_CMD, [scriptPath, "--mode", "packages", "--json"], {
-      cwd: directory,
-      timeout: 5000,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      env: {
-        ...process.env,
-        ...(contextKey ? { TRELLIS_CONTEXT_ID: contextKey } : {}),
-      },
-    })
-    const data = JSON.parse(output)
-    if (data.mode !== "monorepo") {
-      return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
-    }
-    const pkgDict = {}
-    for (const pkg of (data.packages || [])) {
-      pkgDict[pkg.name] = pkg
-    }
-    return {
-      isMonorepo: true,
-      packages: pkgDict,
-      specScope: data.specScope || null,
-      activeTaskPackage: data.activeTaskPackage || null,
-      defaultPackage: data.defaultPackage || null,
-    }
-  } catch (e) {
-    debugLog("session", "loadTrellisConfig error:", e.message)
-    return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
-  }
-}
-
-
-/**
- * Check for legacy spec directory structure in monorepo.
- */
-function checkLegacySpec(directory, config) {
-  if (!config.isMonorepo || Object.keys(config.packages).length === 0) {
-    return null
-  }
-
-  const specDir = join(directory, ".trellis", "spec")
-  if (!existsSync(specDir)) return null
-
-  let hasLegacy = false
-  for (const name of ["backend", "frontend"]) {
-    if (existsSync(join(specDir, name, "index.md"))) {
-      hasLegacy = true
-      break
-    }
-  }
-  if (!hasLegacy) return null
-
-  const pkgNames = Object.keys(config.packages).sort()
-  const missing = pkgNames.filter(name => !existsSync(join(specDir, name)))
-
-  if (missing.length === 0) return null
-
-  if (missing.length === pkgNames.length) {
-    return (
-      `[!] Legacy spec structure detected: found \`spec/backend/\` or \`spec/frontend/\` ` +
-      `but no package-scoped \`spec/<package>/\` directories.\n` +
-      `Monorepo packages: ${pkgNames.join(", ")}\n` +
-      `Please reorganize: \`spec/backend/\` -> \`spec/<package>/backend/\``
-    )
-  }
-  return (
-    `[!] Partial spec migration detected: packages ${missing.join(", ")} ` +
-    `still missing \`spec/<pkg>/\` directory.\n` +
-    `Please complete migration for all packages.`
-  )
-}
-
-
-/**
- * Resolve which packages should have their specs injected.
- * Returns a Set of allowed package names, or null for full scan.
- */
-function resolveSpecScope(config) {
-  if (!config.isMonorepo || Object.keys(config.packages).length === 0) {
-    return null
-  }
-
-  const { specScope, activeTaskPackage, defaultPackage, packages } = config
-  if (specScope == null) return null
-
-  if (specScope === "active_task") {
-    if (activeTaskPackage && activeTaskPackage in packages) return new Set([activeTaskPackage])
-    if (defaultPackage && defaultPackage in packages) return new Set([defaultPackage])
-    return null
-  }
-
-  if (Array.isArray(specScope)) {
-    const valid = new Set()
-    for (const entry of specScope) {
-      if (entry in packages) {
-        valid.add(entry)
-      }
-    }
-    if (valid.size > 0) return valid
-    if (activeTaskPackage && activeTaskPackage in packages) return new Set([activeTaskPackage])
-    if (defaultPackage && defaultPackage in packages) return new Set([defaultPackage])
-    return null
-  }
-
-  return null
-}
-
-
-/**
- * Build session context for injection
- */
-export function buildSessionContext(ctx, platformInput = null) {
-  const directory = ctx.directory
-  const trellisDir = join(directory, ".trellis")
-  const contextKey = typeof ctx.getContextKey === "function"
-    ? ctx.getContextKey(platformInput)
-    : null
-
-  const config = loadTrellisConfig(directory, contextKey)
-  const allowedPkgs = resolveSpecScope(config)
-
-  const parts = []
-
-  // 1. Header
-  parts.push(`<trellis-context>
-You are starting a new session in a Trellis-managed project.
-Read and follow all instructions below carefully.
-</trellis-context>`)
-  parts.push(FIRST_REPLY_NOTICE)
-
-  // Legacy migration warning
-  const legacyWarning = checkLegacySpec(directory, config)
-  if (legacyWarning) {
-    parts.push(`<migration-warning>\n${legacyWarning}\n</migration-warning>`)
-  }
-
-  // 2. Current Context (dynamic)
-  const contextScript = join(trellisDir, "scripts", "get_context.py")
-  if (existsSync(contextScript)) {
-    const output = ctx.runScript(contextScript, undefined, contextKey)
-    if (output) {
-      parts.push("<current-state>")
-      parts.push(output)
-      parts.push("</current-state>")
-    }
-  }
-
-  // 3. Workflow Guide — TOC + Phase Index + Phase 1/2/3 step details.
-  //    Meta sections (Core Principles / Trellis System / Breadcrumbs) are NOT
-  //    injected: Core Principles is short prose; Trellis System duplicates
-  //    commands in step bodies; Breadcrumbs are consumed by UserPromptSubmit hook.
-  const workflowContent = ctx.readProjectFile(".trellis/workflow.md")
-  if (workflowContent) {
-    const allLines = workflowContent.split("\n")
-    const overviewLines = [
-      "# Development Workflow — Section Index",
-      "Full guide: .trellis/workflow.md  (read on demand)",
-      "",
-      "## Table of Contents",
-    ]
-    for (const line of allLines) {
-      if (line.startsWith("## ")) overviewLines.push(line)
-    }
-    overviewLines.push("", "---", "")
-
-    // Extract range from "## Phase Index" up to (but excluding)
-    // "## Workflow State Breadcrumbs". Captures Phase Index + Phase 1/2/3.
-    let rangeStart = -1
-    let rangeEnd = allLines.length
-    for (let i = 0; i < allLines.length; i++) {
-      const stripped = allLines[i].trim()
-      if (rangeStart === -1 && stripped === "## Phase Index") {
-        rangeStart = i
-      } else if (rangeStart !== -1 && stripped === "## Workflow State Breadcrumbs") {
-        rangeEnd = i
-        break
-      }
-    }
-    if (rangeStart !== -1) {
-      overviewLines.push(...allLines.slice(rangeStart, rangeEnd))
-    }
-
-    parts.push("<workflow>")
-    parts.push(overviewLines.join("\n").trimEnd())
-    parts.push("</workflow>")
-  }
-
-  // 4. Guidelines — paths-only for most indexes; guides/ inlined (cross-package,
-  //    broadly useful). Sub-agents get their specific specs via jsonl injection.
-  parts.push("<guidelines>")
-  parts.push(
-    "Project spec indexes are listed by path below. Each index contains a " +
-    "**Pre-Development Checklist** listing the specific guideline files to " +
-    "read before coding.\n\n" +
-    "- 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" +
-    "- For agent-capable platforms, do NOT edit code directly in the main " +
-    "session; dispatch `trellis-implement` and `trellis-check` so JSONL " +
-    "context is loaded by the sub-agents.\n"
-  )
-
-  const specDir = join(directory, ".trellis", "spec")
-
-  // guides/ inlined
-  const guidesIndex = join(specDir, "guides", "index.md")
-  if (existsSync(guidesIndex)) {
-    const content = ctx.readFile(guidesIndex)
-    if (content) {
-      parts.push(`## guides (inlined — cross-package thinking guides)\n${content}\n`)
-    }
-  }
-
-  // Other indexes — paths only
-  const paths = []
-  if (existsSync(specDir)) {
-    try {
-      const subs = readdirSync(specDir).filter(name => {
-        if (name.startsWith(".")) return false
-        try {
-          return statSync(join(specDir, name)).isDirectory()
-        } catch {
-          return false
-        }
-      }).sort()
-
-      for (const sub of subs) {
-        if (sub === "guides") continue  // already inlined above
-
-        const indexFile = join(specDir, sub, "index.md")
-        if (existsSync(indexFile)) {
-          paths.push(`.trellis/spec/${sub}/index.md`)
-        } else {
-          if (allowedPkgs !== null && !allowedPkgs.has(sub)) continue
-          try {
-            const nested = readdirSync(join(specDir, sub)).filter(name => {
-              try {
-                return statSync(join(specDir, sub, name)).isDirectory()
-              } catch {
-                return false
-              }
-            }).sort()
-            for (const layer of nested) {
-              const nestedIndex = join(specDir, sub, layer, "index.md")
-              if (existsSync(nestedIndex)) {
-                paths.push(`.trellis/spec/${sub}/${layer}/index.md`)
-              }
-            }
-          } catch {
-            // Ignore directory read errors
-          }
-        }
-      }
-    } catch {
-      // Ignore spec directory read errors
-    }
-  }
-
-  if (paths.length > 0) {
-    parts.push("## Available spec indexes (read on demand)")
-    for (const p of paths) {
-      parts.push(`- ${p}`)
-    }
-    parts.push("")
-  }
-
-  parts.push(
-    "Discover more via: " +
-    "`python3 ./.trellis/scripts/get_context.py --mode packages`"
-  )
-  parts.push("</guidelines>")
-
-  // 6. Task status
-  const taskStatus = getTaskStatus(ctx, platformInput)
-  parts.push(`<task-status>\n${taskStatus}\n</task-status>`)
-
-  // 7. Final directive
-  parts.push(`<ready>
-Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
-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>`)
-
-  return parts.join("\n\n")
-}
-
-function getTrellisMetadata(metadata) {
-  if (!metadata || typeof metadata !== "object") {
-    return {}
-  }
-
-  const trellis = metadata.trellis
-  if (!trellis || typeof trellis !== "object") {
-    return {}
-  }
-
-  return trellis
-}
-
-function markPartAsSessionStart(part) {
-  const metadata = part.metadata && typeof part.metadata === "object"
-    ? part.metadata
-    : {}
-  part.metadata = {
-    ...metadata,
-    trellis: {
-      ...getTrellisMetadata(metadata),
-      sessionStart: true,
-    },
-  }
-}
-
-function hasSessionStartMarker(part) {
-  if (!part || part.type !== "text" || typeof part.text !== "string") {
-    return false
-  }
-
-  return getTrellisMetadata(part.metadata).sessionStart === true
-}
-
-export function hasInjectedTrellisContext(messages) {
-  if (!Array.isArray(messages)) {
-    return false
-  }
-
-  return messages.some(message => {
-    if (!message?.info || message.info.role !== "user" || !Array.isArray(message.parts)) {
-      return false
-    }
-
-    return message.parts.some(hasSessionStartMarker)
-  })
-}
-
-async function hasPersistedInjectedContext(client, directory, sessionID) {
-  try {
-    const response = await client.session.messages({
-      path: { id: sessionID },
-      query: { directory },
-      throwOnError: true,
-    })
-    return hasInjectedTrellisContext(response.data || [])
-  } catch (error) {
-    debugLog(
-      "session",
-      "Failed to read session history for dedupe:",
-      error instanceof Error ? error.message : String(error),
-    )
-    return false
-  }
-}
+import {
+  buildSessionContext,
+  hasPersistedInjectedContext,
+  markContextInjected,
+} from "../lib/session-utils.js"
 
 // OpenCode 1.2.x expects plugins to be factory functions (see inject-subagent-context.js comment).
 export default async ({ directory, client }) => {
@@ -483,77 +19,70 @@ export default async ({ directory, client }) => {
   debugLog("session", "Plugin loaded, directory:", directory)
 
   return {
-      // Clear in-memory dedupe after compaction so context can be re-injected.
-      event: ({ event }) => {
-        try {
-          if (event?.type === "session.compacted" && event?.properties?.sessionID) {
-            const sessionID = event.properties.sessionID
-            contextCollector.clear(sessionID)
-            debugLog("session", "Cleared processed flag after compaction for session:", sessionID)
-          }
-        } catch (error) {
-          debugLog(
-            "session",
-            "Error in event hook:",
-            error instanceof Error ? error.message : String(error),
-          )
+    event: ({ event }) => {
+      try {
+        if (event?.type === "session.compacted" && event?.properties?.sessionID) {
+          const sessionID = event.properties.sessionID
+          contextCollector.clear(sessionID)
+          debugLog("session", "Cleared processed flag after compaction for session:", sessionID)
         }
-      },
-
-      // chat.message - triggered when user sends a message.
-      // Modify the message in-place so the context is persisted with updateMessage/updatePart.
-      "chat.message": async (input, output) => {
-        try {
-          const sessionID = input.sessionID
-          const agent = input.agent || "unknown"
-          debugLog("session", "chat.message called, sessionID:", sessionID, "agent:", agent)
-
-          // Skip in non-interactive mode
-          if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
-            debugLog("session", "Skipping - non-interactive mode")
-            return
-          }
+      } catch (error) {
+        debugLog(
+          "session",
+          "Error in event hook:",
+          error instanceof Error ? error.message : String(error),
+        )
+      }
+    },
 
-          // Only inject on first message
-          if (contextCollector.isProcessed(sessionID)) {
-            debugLog("session", "Skipping - session already processed")
-            return
-          }
+    // chat.message - triggered when user sends a message.
+    // Modify the message in-place so the context is persisted with updateMessage/updatePart.
+    "chat.message": async (input, output) => {
+      try {
+        const sessionID = input.sessionID
+        const agent = input.agent || "unknown"
+        debugLog("session", "chat.message called, sessionID:", sessionID, "agent:", agent)
 
-          if (await hasPersistedInjectedContext(client, ctx.directory, sessionID)) {
-            contextCollector.markProcessed(sessionID)
-            debugLog("session", "Skipping - session already contains persisted Trellis context")
-            return
-          }
+        if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
+          debugLog("session", "Skipping - non-interactive mode")
+          return
+        }
 
-          // Build context
-          const context = buildSessionContext(ctx, input)
-          debugLog("session", "Built context, length:", context.length)
+        if (contextCollector.isProcessed(sessionID)) {
+          debugLog("session", "Skipping - session already processed")
+          return
+        }
 
-          // Inject context directly into output.parts so it gets persisted by updatePart
-          const parts = output?.parts || []
-          const textPartIndex = parts.findIndex(
-            p => p.type === "text" && p.text !== undefined
-          )
+        if (await hasPersistedInjectedContext(client, ctx.directory, sessionID)) {
+          contextCollector.markProcessed(sessionID)
+          debugLog("session", "Skipping - session already contains persisted Trellis context")
+          return
+        }
 
-          if (textPartIndex !== -1) {
-            const originalText = parts[textPartIndex].text || ""
-            parts[textPartIndex].text = `${context}\n\n---\n\n${originalText}`
-            markPartAsSessionStart(parts[textPartIndex])
-            debugLog("session", "Injected context into chat.message text part, length:", context.length)
-          } else {
-            // No existing text part: prepend a new one
-            const injectedPart = { type: "text", text: context }
-            markPartAsSessionStart(injectedPart)
-            parts.unshift(injectedPart)
-            debugLog("session", "Prepended new text part with context, length:", context.length)
-          }
+        const context = buildSessionContext(ctx, input)
+        debugLog("session", "Built context, length:", context.length)
 
-          contextCollector.markProcessed(sessionID)
+        const parts = output?.parts || []
+        const textPartIndex = parts.findIndex(
+          p => p.type === "text" && p.text !== undefined
+        )
 
-        } catch (error) {
-          debugLog("session", "Error in chat.message:", error.message, error.stack)
+        if (textPartIndex !== -1) {
+          const originalText = parts[textPartIndex].text || ""
+          parts[textPartIndex].text = `${context}\n\n---\n\n${originalText}`
+          markContextInjected(parts[textPartIndex])
+          debugLog("session", "Injected context into chat.message text part, length:", context.length)
+        } else {
+          const injectedPart = { type: "text", text: context }
+          markContextInjected(injectedPart)
+          parts.unshift(injectedPart)
+          debugLog("session", "Prepended new text part with context, length:", context.length)
         }
+
+        contextCollector.markProcessed(sessionID)
+      } catch (error) {
+        debugLog("session", "Error in chat.message:", error.message, error.stack)
       }
+    },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.5.0-rc.0",
+  "version": "0.5.0-rc.1",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",