@mindfoldhq/trellis 0.6.0-beta.4 → 0.6.0-beta.5

package/dist/templates/pi/extensions/trellis/index.ts.txt

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { delimiter, dirname, join, resolve } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 
 type JsonObject = Record<string, unknown>;
 type TextContent = { type: "text"; text: string };
@@ -632,6 +632,166 @@ function buildTrellisContext(
   ].join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// Workflow-state breadcrumb (TypeScript port of the shared workflow-state
+// hook used by class-1 platforms).
+//
+// Pi is extension-backed and MUST NOT receive Python hook scripts under .pi/.
+// We therefore parse `.trellis/workflow.md` `[workflow-state:STATUS]...
+// [/workflow-state:STATUS]` blocks directly in TypeScript and emit the
+// per-turn `<workflow-state>` breadcrumb in `before_agent_start` and `input`.
+// Tag regex mirrors the shared parser so the breadcrumb body stays
+// byte-identical with hook-driven platforms.
+// ---------------------------------------------------------------------------
+
+const WORKFLOW_STATE_TAG_RE =
+  /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workflow-state:\1\]/g;
+
+function loadWorkflowBreadcrumbs(projectRoot: string): Record<string, string> {
+  const workflow = readText(join(projectRoot, ".trellis", "workflow.md"));
+  if (!workflow) return {};
+  const result: Record<string, string> = {};
+  for (const match of workflow.matchAll(WORKFLOW_STATE_TAG_RE)) {
+    const status = match[1] ?? "";
+    const body = (match[2] ?? "").trim();
+    if (status && body) result[status] = body;
+  }
+  return result;
+}
+
+function readActiveTaskStatus(
+  projectRoot: string,
+  taskDir: string,
+): { taskId: string; status: string } | null {
+  try {
+    const data = JSON.parse(
+      readText(join(taskDir, "task.json")),
+    ) as JsonObject;
+    const status = stringValue(data.status);
+    if (!status) return null;
+    const id = stringValue(data.id) ?? taskDir.split(/[\\/]/).pop() ?? "";
+    return { taskId: id, status };
+  } catch {
+    return null;
+  }
+}
+
+function buildWorkflowStateBreadcrumb(
+  projectRoot: string,
+  contextKey: string | null,
+): string {
+  const templates = loadWorkflowBreadcrumbs(projectRoot);
+  const taskDir = readCurrentTask(
+    projectRoot,
+    undefined,
+    undefined,
+    contextKey,
+  );
+  let header: string;
+  let lookupKey: string;
+  if (!taskDir) {
+    header = "Status: no_task\nSource: session";
+    lookupKey = "no_task";
+  } else {
+    const info = readActiveTaskStatus(projectRoot, taskDir);
+    if (!info) {
+      header = "Status: no_task\nSource: session";
+      lookupKey = "no_task";
+    } else {
+      header = `Task: ${info.taskId} (${info.status})\nSource: session`;
+      lookupKey = info.status;
+    }
+  }
+  const body = templates[lookupKey] ?? "Refer to workflow.md for current step.";
+  return `<workflow-state>\n${header}\n${body}\n</workflow-state>`;
+}
+
+// ---------------------------------------------------------------------------
+// Session overview (developer / git branch / active tasks)
+//
+// Spawns `python3 .trellis/scripts/get_context.py` (the same script other
+// platform session-start hooks invoke) to keep developer/git/active-task
+// summary byte-identical with class-1 platforms. Failure is non-fatal — we
+// emit an empty overview rather than block the conversation.
+// ---------------------------------------------------------------------------
+
+const SESSION_OVERVIEW_TIMEOUT_MS = 5000;
+
+function pythonExecutable(): string {
+  const override = stringValue(process.env.TRELLIS_PYTHON);
+  if (override) return override;
+  return process.platform === "win32" ? "python" : "python3";
+}
+
+function buildSessionOverview(
+  projectRoot: string,
+  contextKey: string | null,
+): string {
+  const script = join(projectRoot, ".trellis", "scripts", "get_context.py");
+  if (!isExistingFile(script)) return "";
+  try {
+    const result = spawnSync(pythonExecutable(), [script], {
+      cwd: projectRoot,
+      env: contextKey
+        ? { ...process.env, TRELLIS_CONTEXT_ID: contextKey }
+        : process.env,
+      encoding: "utf-8",
+      timeout: SESSION_OVERVIEW_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    if (result.status !== 0) return "";
+    const stdout = (result.stdout ?? "").trim();
+    if (!stdout) return "";
+    return `<session-overview>\n${stdout}\n</session-overview>`;
+  } catch {
+    return "";
+  }
+}
+
+// Per-turn cache so input + before_agent_start in the same turn don't double-spawn.
+class TurnContextCache {
+  private key: string | null = null;
+  private timestamp = 0;
+  private workflowState = "";
+  private sessionOverview = "";
+  // Refresh window: per-turn injections that fire close together share a
+  // single python3 spawn; anything older than this re-runs the resolver.
+  private static readonly TTL_MS = 1500;
+
+  get(
+    projectRoot: string,
+    contextKey: string | null,
+  ): { workflowState: string; sessionOverview: string } {
+    const now = Date.now();
+    if (this.key === contextKey && now - this.timestamp < TurnContextCache.TTL_MS) {
+      return {
+        workflowState: this.workflowState,
+        sessionOverview: this.sessionOverview,
+      };
+    }
+    this.workflowState = buildWorkflowStateBreadcrumb(projectRoot, contextKey);
+    this.sessionOverview = buildSessionOverview(projectRoot, contextKey);
+    this.key = contextKey;
+    this.timestamp = now;
+    return {
+      workflowState: this.workflowState,
+      sessionOverview: this.sessionOverview,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sub-agent dispatch protocol snippet (registered with the `subagent` tool).
+// Mirrors the [workflow-state:in_progress] dispatch protocol text in
+// trellis/workflow.md so the AI sees the same `Active task: <path>` rule
+// whether it reads workflow.md, the per-turn breadcrumb, or the tool prompt.
+// ---------------------------------------------------------------------------
+
+const SUBAGENT_DISPATCH_PROTOCOL = `Sub-agent dispatch protocol (Trellis): your dispatch prompt MUST start with one line "Active task: <task path from \`task.py current\`>" before any other instructions. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) and on Pi, the line is the canonical fallback when hook/extension injection misses. trellis-research uses the line to know which {task_dir}/research/ to write into.
+
+Wrong: prompt: "implement the new feature"
+Correct: prompt: "Active task: .trellis/tasks/05-09-pi-workflow-state-injection\\n\\nImplement the new feature ..."`;
+
 function normalizeAgentName(agent: string): string {
   return agent.startsWith("trellis-") ? agent : `trellis-${agent}`;
 }
@@ -886,6 +1046,15 @@ export default function trellisExtension(pi: {
   const projectRoot = findProjectRoot(pi.cwd ?? process.cwd());
   const processContextKey = createProcessContextKey(projectRoot);
   let currentContextKey: string | null = null;
+  const turnContextCache = new TurnContextCache();
+
+  const buildPerTurnInjection = (contextKey: string | null): string => {
+    const { workflowState, sessionOverview } = turnContextCache.get(
+      projectRoot,
+      contextKey,
+    );
+    return [workflowState, sessionOverview].filter(Boolean).join("\n\n");
+  };
 
   const getContextKey = (input?: unknown, ctx?: PiExtensionContext): string => {
     const resolvedContextKey = resolveContextKey(
@@ -904,6 +1073,8 @@ export default function trellisExtension(pi: {
     name: "subagent",
     label: "Subagent",
     description: "Run a Trellis project sub-agent with active task context.",
+    promptSnippet: SUBAGENT_DISPATCH_PROTOCOL,
+    promptGuidelines: SUBAGENT_DISPATCH_PROTOCOL,
     parameters: {
       type: "object",
       properties: {
@@ -976,8 +1147,9 @@ export default function trellisExtension(pi: {
       ctx,
       contextKey,
     );
+    const perTurn = buildPerTurnInjection(contextKey);
     return {
-      systemPrompt: [current, context].filter(Boolean).join("\n\n"),
+      systemPrompt: [current, context, perTurn].filter(Boolean).join("\n\n"),
     };
   });
   pi.on?.("context", (event, ctx) => {
@@ -986,8 +1158,11 @@ export default function trellisExtension(pi: {
     return Array.isArray(messages) ? { messages } : undefined;
   });
   pi.on?.("input", (event, ctx) => {
-    getContextKey(event, ctx);
-    return { action: "continue" };
+    const contextKey = getContextKey(event, ctx);
+    const additionalContext = buildPerTurnInjection(contextKey);
+    return additionalContext
+      ? { action: "continue", additionalContext, systemPrompt: additionalContext }
+      : { action: "continue" };
   });
   pi.on?.("tool_call", (event, ctx) => {
     const contextKey = getContextKey(event, ctx);

package/dist/templates/pi/settings.json

@@ -8,5 +8,14 @@
   ],
   "prompts": [
     "./prompts"
+  ],
+  "packages": [
+    {
+      "source": "npm:pi-subagents",
+      "extensions": [],
+      "skills": [],
+      "prompts": [],
+      "themes": []
+    }
   ]
 }

package/dist/templates/trellis/index.d.ts

@@ -36,6 +36,7 @@ export declare const commonSessionContext: string;
 export declare const commonPackagesContext: string;
 export declare const commonWorkflowPhase: string;
 export declare const commonTrellisConfig: string;
+export declare const commonSafeCommit: string;
 export declare const getDeveloperScript: string;
 export declare const initDeveloperScript: string;
 export declare const taskScript: string;

package/dist/templates/trellis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH,eAAO,MAAM,WAAW,QAAsC,CAAC;AAG/D,eAAO,MAAM,UAAU,QAA6C,CAAC;AACrE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,eAAe,QAA8C,CAAC;AAC3E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,YAAY,QAA2C,CAAC;AACrE,eAAO,MAAM,QAAQ,QAAuC,CAAC;AAC7D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAChF,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AACF,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AAGF,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAC3E,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAC7E,eAAO,MAAM,UAAU,QAAkC,CAAC;AAC1D,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AAGvE,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAgC,CAAC;AAE/D;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoCnD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH,eAAO,MAAM,WAAW,QAAsC,CAAC;AAG/D,eAAO,MAAM,UAAU,QAA6C,CAAC;AACrE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,eAAe,QAA8C,CAAC;AAC3E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,YAAY,QAA2C,CAAC;AACrE,eAAO,MAAM,QAAQ,QAAuC,CAAC;AAC7D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAChF,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AACF,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAG9E,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAC3E,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAC7E,eAAO,MAAM,UAAU,QAAkC,CAAC;AAC1D,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AAGvE,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAgC,CAAC;AAE/D;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqCnD"}

package/dist/templates/trellis/index.js

@@ -46,6 +46,7 @@ export const commonSessionContext = readTemplate("scripts/common/session_context
 export const commonPackagesContext = readTemplate("scripts/common/packages_context.py");
 export const commonWorkflowPhase = readTemplate("scripts/common/workflow_phase.py");
 export const commonTrellisConfig = readTemplate("scripts/common/trellis_config.py");
+export const commonSafeCommit = readTemplate("scripts/common/safe_commit.py");
 // Python scripts - main
 export const getDeveloperScript = readTemplate("scripts/get_developer.py");
 export const initDeveloperScript = readTemplate("scripts/init_developer.py");
@@ -84,6 +85,7 @@ export function getAllScripts() {
     scripts.set("common/packages_context.py", commonPackagesContext);
     scripts.set("common/workflow_phase.py", commonWorkflowPhase);
     scripts.set("common/trellis_config.py", commonTrellisConfig);
+    scripts.set("common/safe_commit.py", commonSafeCommit);
     // Main
     scripts.set("get_developer.py", getDeveloperScript);
     scripts.set("init_developer.py", initDeveloperScript);

package/dist/templates/trellis/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,gCAAgC;AAChC,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAC;AAE/D,0BAA0B;AAC1B,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC,4BAA4B,CAAC,CAAC;AACrE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,yBAAyB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,6BAA6B,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,8BAA8B,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,8BAA8B,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,0BAA0B,CAAC,CAAC;AACrE,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC,sBAAsB,CAAC,CAAC;AAC7D,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC,uBAAuB,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC,uBAAuB,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,yBAAyB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,yBAAyB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC,gCAAgC,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,8BAA8B,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAC9C,mCAAmC,CACpC,CAAC;AACF,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAC/C,oCAAoC,CACrC,CAAC;AACF,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAC7C,kCAAkC,CACnC,CAAC;AACF,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAC7C,kCAAkC,CACnC,CAAC;AAEF,wBAAwB;AACxB,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC,0BAA0B,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC,2BAA2B,CAAC,CAAC;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC,iBAAiB,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,wBAAwB,CAAC,CAAC;AACvE,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,wBAAwB,CAAC,CAAC;AAEvE,sBAAsB;AACtB,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,eAAe;IACf,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAExC,SAAS;IACT,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,eAAe,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,eAAe,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACtC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,iBAAiB,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,eAAe,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,oBAAoB,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,qBAAqB,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,mBAAmB,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,mBAAmB,CAAC,CAAC;IAE7D,OAAO;IACP,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;IAEhD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,gCAAgC;AAChC,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAC;AAE/D,0BAA0B;AAC1B,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC,4BAA4B,CAAC,CAAC;AACrE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,yBAAyB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,6BAA6B,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,8BAA8B,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,8BAA8B,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,0BAA0B,CAAC,CAAC;AACrE,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC,sBAAsB,CAAC,CAAC;AAC7D,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC,uBAAuB,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC,uBAAuB,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,yBAAyB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC,yBAAyB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC,gCAAgC,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC,8BAA8B,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAC9C,mCAAmC,CACpC,CAAC;AACF,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAC/C,oCAAoC,CACrC,CAAC;AACF,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAC7C,kCAAkC,CACnC,CAAC;AACF,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAC7C,kCAAkC,CACnC,CAAC;AACF,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;AAE9E,wBAAwB;AACxB,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC,0BAA0B,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC,2BAA2B,CAAC,CAAC;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC,iBAAiB,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,wBAAwB,CAAC,CAAC;AACvE,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,wBAAwB,CAAC,CAAC;AAEvE,sBAAsB;AACtB,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,eAAe;IACf,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAExC,SAAS;IACT,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,eAAe,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,eAAe,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACtC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,iBAAiB,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,eAAe,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,oBAAoB,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,qBAAqB,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,mBAAmB,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,mBAAmB,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;IAEvD,OAAO;IACP,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;IAEhD,OAAO,OAAO,CAAC;AACjB,CAAC"}

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

@@ -23,7 +23,6 @@ from __future__ import annotations
 
 import argparse
 import re
-import subprocess
 import sys
 from datetime import datetime
 from pathlib import Path
@@ -37,6 +36,11 @@ from common.paths import (
 )
 from common.developer import ensure_developer
 from common.git import run_git
+from common.safe_commit import (
+    print_gitignore_warning,
+    safe_git_add,
+    safe_trellis_paths_to_add,
+)
 from common.tasks import load_task
 from common.config import (
     get_packages,
@@ -314,36 +318,52 @@ def update_index(
 # =============================================================================
 
 def _auto_commit_workspace(repo_root: Path) -> None:
-    """Stage .trellis/workspace and .trellis/tasks, then commit with a configured message."""
+    """Stage Trellis-owned workspace + task paths and commit.
+
+    Path scope is restricted to specific products (journal files, index.md,
+    active task dirs, the archive subtree). We never `git add` the whole
+    `.trellis/` tree, and if `.gitignore` blocks the specific paths we retry
+    with `git add -f <those-specific-paths>` — never `-f .trellis/`.
+    """
     commit_msg = get_session_commit_message(repo_root)
-    add_result = subprocess.run(
-        ["git", "add", "-A", ".trellis/workspace", ".trellis/tasks"],
-        cwd=repo_root,
-        capture_output=True,
-        text=True,
-    )
-    if add_result.returncode != 0:
-        print(f"[WARN] git add failed (exit {add_result.returncode}): {add_result.stderr.strip()}", file=sys.stderr)
-        print("[WARN] Please commit .trellis/ changes manually: git add .trellis && git commit", file=sys.stderr)
+    paths = safe_trellis_paths_to_add(repo_root)
+    if not paths:
+        print("[OK] No workspace changes to commit.", file=sys.stderr)
+        return
+
+    success, used_force, err = safe_git_add(paths, repo_root)
+    if not success:
+        if err and "ignored by" in err.lower():
+            print_gitignore_warning(paths)
+        else:
+            print(
+                f"[WARN] git add failed: {err.strip() if err else 'unknown error'}",
+                file=sys.stderr,
+            )
         return
-    # Check if there are staged changes
-    result = subprocess.run(
-        ["git", "diff", "--cached", "--quiet", "--", ".trellis/workspace", ".trellis/tasks"],
-        cwd=repo_root,
+
+    if used_force:
+        print(
+            "[OK] Staged Trellis-owned paths with -f (specific paths, not .trellis/).",
+            file=sys.stderr,
+        )
+
+    # Check if there are staged changes for the paths we just staged.
+    rc, _, _ = run_git(
+        ["diff", "--cached", "--quiet", "--", *paths], cwd=repo_root
     )
-    if result.returncode == 0:
+    if rc == 0:
         print("[OK] No workspace changes to commit.", file=sys.stderr)
         return
-    commit_result = subprocess.run(
-        ["git", "commit", "-m", commit_msg],
-        cwd=repo_root,
-        capture_output=True,
-        text=True,
-    )
-    if commit_result.returncode == 0:
+
+    rc, _, commit_err = run_git(["commit", "-m", commit_msg], cwd=repo_root)
+    if rc == 0:
         print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
     else:
-        print(f"[WARN] Auto-commit failed: {commit_result.stderr.strip()}", file=sys.stderr)
+        print(
+            f"[WARN] Auto-commit failed: {commit_err.strip()}",
+            file=sys.stderr,
+        )
 
 
 def add_session(

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

@@ -0,0 +1,229 @@
+"""
+Safe git-add helpers for Trellis-owned paths.
+
+Why this module exists
+----------------------
+A real user incident: a project's `.gitignore` listed `.trellis/` (company-wide
+template / personal habit). When `add_session.py` and `task.py archive` ran
+their auto-commit and `git add` failed with `ignored by .gitignore`, the AI
+agent driving the workflow "fixed" it by retrying with
+`git add -f .trellis/` — which fan-out-included every ignored subtree
+(`.trellis/.backup-*/`, `.trellis/worktrees/`, `.trellis/.template-hashes.json`,
+`.trellis/.runtime/`), committing 548 files / 83474 lines of caches/backups.
+
+Design
+------
+- Scripts only stage SPECIFIC product paths (journal files, index.md, the
+  current task dir, the archive dir). Never the whole `.trellis/` tree.
+- If plain `git add <specific>` fails with "ignored by", retry with
+  `git add -f <specific>` — forcing only the paths the script knows it owns.
+  This is safe because the paths are narrow; it is NOT equivalent to
+  `git add -f .trellis/` (which would fan out to backups/worktrees/runtime).
+- If the -f retry also fails, print an explicit warning that includes a
+  negative example: ``Do NOT use `git add -f .trellis/` ...``
+
+The wider-grain forbidden command stays forbidden.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from .git import run_git
+from .paths import (
+    DIR_ARCHIVE,
+    DIR_TASKS,
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    FILE_JOURNAL_PREFIX,
+    get_developer,
+)
+
+
+# Paths under .trellis/ that must NEVER be auto-staged. Listed here so the
+# warning to the user can show concrete subpaths to ignore individually
+# instead of ignoring the whole `.trellis/` tree.
+TRELLIS_IGNORED_SUBPATHS = (
+    ".trellis/.backup-*",
+    ".trellis/worktrees/",
+    ".trellis/.template-hashes.json",
+    ".trellis/.runtime/",
+    ".trellis/.cache/",
+)
+
+
+def safe_trellis_paths_to_add(repo_root: Path) -> list[str]:
+    """Return the list of repo-relative paths the auto-commit should stage.
+
+    Only includes paths that exist on disk so callers don't pass non-existent
+    arguments to git. The caller is responsible for `git diff --cached`
+    checking afterwards.
+
+    Included:
+      - .trellis/workspace/<developer>/journal-*.md
+      - .trellis/workspace/<developer>/index.md
+      - .trellis/tasks/<task-dir>/   (every active task directory)
+      - .trellis/tasks/archive/      (whole archive subtree, if present)
+
+    Excluded (intentionally — these must not be staged):
+      - .trellis/.backup-*, .trellis/worktrees/,
+        .trellis/.template-hashes.json, .trellis/.runtime/, .trellis/.cache/
+    """
+    paths: list[str] = []
+
+    # Workspace journal files + index.md
+    developer = get_developer(repo_root)
+    if developer:
+        ws = repo_root / DIR_WORKFLOW / DIR_WORKSPACE / developer
+        if ws.is_dir():
+            for f in sorted(ws.glob(f"{FILE_JOURNAL_PREFIX}*.md")):
+                if f.is_file():
+                    paths.append(
+                        f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{f.name}"
+                    )
+            index_md = ws / "index.md"
+            if index_md.is_file():
+                paths.append(
+                    f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/index.md"
+                )
+
+    # Active tasks: each direct child of tasks/ that is a directory and not
+    # the archive root. The archive subtree is added as a single path below.
+    tasks_dir = repo_root / DIR_WORKFLOW / DIR_TASKS
+    if tasks_dir.is_dir():
+        for child in sorted(tasks_dir.iterdir()):
+            if not child.is_dir():
+                continue
+            if child.name == DIR_ARCHIVE:
+                continue
+            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child.name}")
+
+        archive_dir = tasks_dir / DIR_ARCHIVE
+        if archive_dir.is_dir():
+            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}")
+
+    return paths
+
+
+def safe_archive_paths_to_add(repo_root: Path) -> list[str]:
+    """Return paths to stage after `task.py archive`.
+
+    Limited to the archive subtree (where the freshly-moved task lives) plus
+    the source task directory's parent area to capture the deletion in the
+    same commit. We pass the whole `.trellis/tasks/` path so deletions of the
+    pre-move path are tracked, but only as a SPECIFIC subpath — not the whole
+    `.trellis/` tree.
+    """
+    paths: list[str] = []
+    tasks_dir = repo_root / DIR_WORKFLOW / DIR_TASKS
+    if tasks_dir.is_dir():
+        # The archive copy.
+        archive_dir = tasks_dir / DIR_ARCHIVE
+        if archive_dir.is_dir():
+            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}")
+        # Active tasks (some may have been re-touched, e.g. parent's
+        # children list). This captures the source-path deletion too because
+        # `git add` on a directory records removals.
+        for child in sorted(tasks_dir.iterdir()):
+            if not child.is_dir():
+                continue
+            if child.name == DIR_ARCHIVE:
+                continue
+            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child.name}")
+    return paths
+
+
+def _stderr_indicates_ignored(stderr: str) -> bool:
+    """git add error indicates the path is excluded by .gitignore."""
+    if not stderr:
+        return False
+    lowered = stderr.lower()
+    return "ignored by" in lowered
+
+
+def safe_git_add(
+    paths: list[str], repo_root: Path
+) -> tuple[bool, bool, str]:
+    """Run `git add` on specific paths, retrying with -f if .gitignore blocks.
+
+    Returns (success, used_force, stderr). On success, callers should still
+    `git diff --cached` to detect whether anything was actually staged.
+
+    Behavior:
+      - No paths passed → success, no force, empty stderr.
+      - Plain `git add <paths>` succeeds → return.
+      - Plain fails with "ignored by" → retry with `git add -f <paths>`.
+      - Retry succeeds → return success with used_force=True.
+      - Retry fails → return failure; caller should print the gitignore
+        warning (see :func:`print_gitignore_warning`).
+      - Plain fails with a non-ignored error → return failure; do NOT retry
+        with -f (we only force when ignore is the cause).
+    """
+    if not paths:
+        return True, False, ""
+
+    rc, _, err = run_git(["add", "--", *paths], cwd=repo_root)
+    if rc == 0:
+        return True, False, ""
+
+    if not _stderr_indicates_ignored(err):
+        return False, False, err
+
+    rc2, _, err2 = run_git(["add", "-f", "--", *paths], cwd=repo_root)
+    if rc2 == 0:
+        return True, True, err2 or err
+    return False, True, err2 or err
+
+
+def print_gitignore_warning(paths: list[str]) -> None:
+    """Explain to the user (and any AI reading the log) what to do.
+
+    CRITICAL: includes the negative example
+    ``Do NOT use `git add -f .trellis/``` — agents reading the warning are
+    known to invent that command, which fans out to ignored caches/backups.
+    """
+    print(
+        "[WARN] git add failed because .trellis/ paths are ignored by your .gitignore.",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN] Trellis manages these specific paths and they should be tracked:",
+        file=sys.stderr,
+    )
+    if paths:
+        for p in paths:
+            print(f"[WARN]   {p}", file=sys.stderr)
+    else:
+        print(
+            "[WARN]   .trellis/workspace/<developer>/{journal-*.md,index.md}",
+            file=sys.stderr,
+        )
+        print(
+            "[WARN]   .trellis/tasks/<task-dir>/",
+            file=sys.stderr,
+        )
+        print(
+            "[WARN]   .trellis/tasks/archive/",
+            file=sys.stderr,
+        )
+    print("[WARN]", file=sys.stderr)
+    print(
+        "[WARN] Recommended: change your .gitignore from `.trellis/` to specific",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN] subpaths that should remain ignored, e.g.:",
+        file=sys.stderr,
+    )
+    for sub in TRELLIS_IGNORED_SUBPATHS:
+        print(f"[WARN]   {sub}", file=sys.stderr)
+    print("[WARN]", file=sys.stderr)
+    print(
+        "[WARN] Do NOT use `git add -f .trellis/` — it pulls in backups, worktrees,",
+        file=sys.stderr,
+    )
+    print(
+        "[WARN] and runtime caches that should never be committed.",
+        file=sys.stderr,
+    )