sidecar-cli 0.1.5-rc.1 → 0.1.6-beta.2

package/dist/tasks/task-repository.js

@@ -1,12 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { getSidecarPaths } from '../lib/paths.js';
+import { nowIso, stringifyJson } from '../lib/format.js';
 import { SidecarError } from '../lib/errors.js';
-import { stringifyJson } from '../lib/format.js';
+import { getSidecarPaths } from '../lib/paths.js';
 import { taskPacketSchema } from './task-packet.js';
-function taskFilePath(tasksPath, taskId) {
-    return path.join(tasksPath, `${taskId}.json`);
-}
+const TASK_STATUS_FOLDERS = {
+    active: 'active',
+    blocked: 'blocked',
+    done: 'done',
+};
 function parseTaskIdOrdinal(taskId) {
     const match = /^T-(\d+)$/.exec(taskId);
     return match ? Number.parseInt(match[1], 10) : 0;
@@ -19,36 +21,77 @@ export class TaskPacketRepository {
     get tasksPath() {
         return getSidecarPaths(this.rootPath).tasksPath;
     }
+    statusPath(status) {
+        return path.join(this.tasksPath, TASK_STATUS_FOLDERS[status]);
+    }
     ensureStorage() {
         fs.mkdirSync(this.tasksPath, { recursive: true });
+        fs.mkdirSync(this.statusPath('active'), { recursive: true });
+        fs.mkdirSync(this.statusPath('blocked'), { recursive: true });
+        fs.mkdirSync(this.statusPath('done'), { recursive: true });
     }
-    generateNextTaskId() {
+    allTaskFiles() {
         this.ensureStorage();
-        const files = fs.readdirSync(this.tasksPath, { withFileTypes: true });
-        let max = 0;
-        for (const file of files) {
-            if (!file.isFile() || !file.name.endsWith('.json'))
+        const files = [];
+        const roots = [this.tasksPath, this.statusPath('active'), this.statusPath('blocked'), this.statusPath('done')];
+        for (const root of roots) {
+            if (!fs.existsSync(root))
                 continue;
-            const id = file.name.slice(0, -'.json'.length);
+            const entries = fs.readdirSync(root, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith('.json'))
+                    continue;
+                files.push(path.join(root, entry.name));
+            }
+        }
+        return Array.from(new Set(files)).sort();
+    }
+    generateNextTaskId() {
+        const files = this.allTaskFiles();
+        let max = 0;
+        for (const filePath of files) {
+            const name = path.basename(filePath);
+            const id = name.slice(0, -'.json'.length);
             max = Math.max(max, parseTaskIdOrdinal(id));
         }
         return `T-${String(max + 1).padStart(3, '0')}`;
     }
+    findTaskFile(taskId) {
+        const candidateName = `${taskId}.json`;
+        for (const filePath of this.allTaskFiles()) {
+            if (path.basename(filePath) === candidateName)
+                return filePath;
+        }
+        return null;
+    }
     save(packet) {
         this.ensureStorage();
         const validated = taskPacketSchema.parse(packet);
-        const filePath = taskFilePath(this.tasksPath, validated.task_id);
-        fs.writeFileSync(filePath, `${stringifyJson(validated)}\n`, 'utf8');
-        return filePath;
+        const now = nowIso();
+        const withUpdatedAt = taskPacketSchema.parse({
+            ...validated,
+            created_at: validated.created_at || now,
+            updated_at: now,
+        });
+        const destination = path.join(this.statusPath(withUpdatedAt.status), `${withUpdatedAt.task_id}.json`);
+        const existing = this.findTaskFile(withUpdatedAt.task_id);
+        if (existing && existing !== destination && fs.existsSync(existing)) {
+            fs.unlinkSync(existing);
+        }
+        fs.writeFileSync(destination, `${stringifyJson(withUpdatedAt)}\n`, 'utf8');
+        return destination;
     }
     get(taskId) {
-        const filePath = taskFilePath(this.tasksPath, taskId);
-        if (!fs.existsSync(filePath)) {
+        const filePath = this.findTaskFile(taskId);
+        if (!filePath)
             throw new SidecarError(`Task not found: ${taskId}`);
-        }
         try {
             const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-            return taskPacketSchema.parse(raw);
+            const parsed = taskPacketSchema.parse(raw);
+            if (parsed.status === 'active' && filePath.startsWith(this.statusPath('blocked'))) {
+                parsed.status = 'blocked';
+            }
+            return parsed;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -56,17 +99,12 @@ export class TaskPacketRepository {
         }
     }
     list() {
-        this.ensureStorage();
-        const files = fs
-            .readdirSync(this.tasksPath, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
-            .map((entry) => path.join(this.tasksPath, entry.name))
-            .sort();
         const packets = [];
-        for (const filePath of files) {
+        for (const filePath of this.allTaskFiles()) {
             try {
                 const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-                packets.push(taskPacketSchema.parse(raw));
+                const parsed = taskPacketSchema.parse(raw);
+                packets.push(parsed);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);

package/dist/tasks/task-service.js

@@ -1,51 +1,21 @@
 import { TaskPacketRepository } from './task-repository.js';
 import { createTaskPacket, } from './task-packet.js';
-import { normalizeValidationStep } from '../runs/capture.js';
 export function createTaskPacketRecord(rootPath, input) {
     const repo = new TaskPacketRepository(rootPath);
     const taskId = repo.generateNextTaskId();
     const packetInput = {
         title: input.title,
         summary: input.summary,
-        goal: input.goal,
-        type: input.type,
-        status: input.status,
         priority: input.priority,
-        scope: {
-            in_scope: input.scope_in_scope ?? [],
-            out_of_scope: input.scope_out_of_scope ?? [],
-        },
-        context: {
-            related_decisions: input.related_decisions ?? [],
-            related_notes: input.related_notes ?? [],
-        },
-        implementation: {
-            files_to_read: input.files_to_read ?? [],
-            files_to_avoid: input.files_to_avoid ?? [],
-        },
-        constraints: {
-            technical: input.technical_constraints ?? [],
-            design: input.design_constraints ?? [],
-        },
-        execution: {
-            commands: {
-                validation: (input.validation_commands ?? [])
-                    .map((v) => normalizeValidationStep(v))
-                    .filter((v) => v !== null),
-            },
-        },
-        dependencies: input.dependencies ?? [],
-        tags: input.tags ?? [],
-        target_areas: input.target_areas ?? [],
-        definition_of_done: input.definition_of_done ?? [],
-        tracking: {
-            branch: input.branch ?? '',
-            worktree: input.worktree ?? '',
-            assigned_agent_role: null,
-            assigned_runner: null,
-            assignment_reason: '',
-            assigned_at: null,
+        status: input.status,
+        trigger: {
+            condition: input.trigger_condition,
+            ...(input.trigger_check_command ? { check_command: input.trigger_check_command } : {}),
+            depends_on: (input.trigger_depends_on ?? []).map((v) => v.toUpperCase()),
         },
+        entry_points: input.entry_points,
+        done_condition: input.done_condition,
+        validation_command: input.validation_command,
     };
     const packet = createTaskPacket(taskId, packetInput);
     const filePath = repo.save(packet);
@@ -54,13 +24,9 @@ export function createTaskPacketRecord(rootPath, input) {
 export function listTaskPackets(rootPath) {
     const repo = new TaskPacketRepository(rootPath);
     const order = {
-        draft: 0,
-        ready: 1,
-        queued: 2,
-        running: 3,
-        review: 4,
-        blocked: 5,
-        done: 6,
+        active: 0,
+        blocked: 1,
+        done: 2,
     };
     return repo
         .list()
@@ -69,7 +35,7 @@ export function listTaskPackets(rootPath) {
         const byStatus = order[a.status] - order[b.status];
         if (byStatus !== 0)
             return byStatus;
-        return a.task_id.localeCompare(b.task_id, undefined, { numeric: true });
+        return a.created_at.localeCompare(b.created_at) || a.task_id.localeCompare(b.task_id, undefined, { numeric: true });
     });
 }
 export function getTaskPacket(rootPath, taskId) {

package/dist/templates/agents.js

@@ -1,68 +1,134 @@
 function renderSharedGuide(projectName, heading) {
-    return `# Sidecar Agent Guide
+    return `# Sidecar
 
 ${heading}
 
-Sidecar is the local project memory tool for this repository.
+Sidecar is this repo's decision log and worklog. Git already records
+what changed; Sidecar exists to record why — and only when "why" is
+non-obvious from the code or the diff.
 
-## MUST before final response
+If invoked without a specific instruction ("do the next thing", loop mode,
+or autonomous mode), go straight to **Picking up the next task** below and
+follow those rules exactly.
 
-If you changed code, you MUST run these commands in order:
+## Read before you write
 
-1. \`sidecar context --format markdown\`
-2. \`sidecar worklog record --done "<what changed>" --files <paths> --by agent\`
-3. if behavior/design/architecture changed: \`sidecar decision record --title "<decision>" --summary "<why>" --by agent\`
-4. if follow-up exists: \`sidecar task add "<follow-up>" --priority medium --by agent\`
-5. \`sidecar summary refresh\`
+Before any non-trivial change — infra, schema, moderation rules, queue
+config, routing, anything that touches a past architectural choice —
+check the decisions log:
+
+\`sidecar context --format markdown\`
+
+If a recent decision constrains your change, follow it or surface it to
+the user before overriding it. Do not silently re-litigate prior choices.
+
+If your change reverses a prior decision, record a new decision that
+references the old one. Do not edit history.
+
+## Record a decision when…
+
+A decision is worth recording when a future agent reading the same code
+would plausibly make a different call without this context.
+
+Record:
+- Trade-offs with a clear loser ("X over Y because Z")
+- Deliberate non-actions ("did NOT add apex→www at the LB because…")
+- Choices that look wrong at first glance
+- Constraints imposed by external systems (cert SANs, RDS VPC, etc.)
+
+Don't record:
+- Style or naming
+- Anything obvious from reading the touched file
+- Restatement of the diff
+- "Added X" — that's a worklog, not a decision
+
+## Record a worklog when…
+
+A worklog is worth recording for multi-step or cross-cutting work where
+the shape of the change isn't obvious from any single commit.
+
+One-line fixes, typo corrections, and dependency bumps usually don't need
+a worklog in general. But for this repo policy: if files changed, record
+a worklog.
+
+## Tasks
 
-## Required workflow
+Create a task only when all of these are explicit:
+- Trigger
+- Entry points (1-3 files)
+- Done condition
+- Validation command
 
-For any code change, run these in order before final response:
+Otherwise: surface the follow-up inline and let it die, or record it as a
+decision if the call is "we're not doing this."
 
+On task completion: write the worklog and decision entries the task
+produced, then move the file to \`tasks/done/\`. No manual archival step.
+
+## Picking up the next task
+
+When an agent is invoked without a specific instruction ("do the next
+thing", "/loop", autonomous mode), follow this precedence exactly:
+
+1. List \`tasks/active/\`.
+2. For each task, verify the trigger is satisfied against current
+   state (run the query, check the dependency, read the threshold). Do
+   not assume — a trigger written months ago may have already fired or
+   may have been invalidated.
+3. Filter to tasks whose trigger is satisfied right now.
+4. From that filtered set, pick the highest \`priority\`. Ties broken by
+   oldest \`created_at\` (FIFO — prevents agents from re-prioritizing the
+   queue each run).
+5. Execute that one task. Do not batch multiple tasks per invocation
+   unless explicitly told to.
+
+## When nothing is ready, ask — do not invent work
+
+If step 3 above returns an empty set:
+
+- Ask the user. Surface the active task list with each task's
+  trigger and why it's not satisfied. Let the user pick, override a
+  trigger, or send you elsewhere.
+- Do not pick the "closest" task and start anyway.
+- Do not pick a task whose trigger is almost satisfied and satisfy it
+  yourself as a side quest.
+- Do not create a new task on the spot to give yourself something to
+  do. Task creation requires the same trigger + entry points + done
+  condition + validation command bar as everything else; you cannot
+  bypass it by self-assigning.
+- Do not start unsolicited refactoring, "cleanup", doc edits, or
+  speculative work to fill the gap.
+
+If the user is unreachable (true autonomous mode, no human in loop):
+exit cleanly with a status message naming the empty queue. Idle is a
+valid outcome. Inventing work is not.
+
+If a trigger requires information you can verify cheaply (a SQL count,
+a \`git log\` check, a file existence test), verify it yourself. If it
+requires information only the user has (a stakeholder commitment, a
+business threshold), ask — don't guess.
+
+## Repo-required sequence for code changes
+
+If you changed code, run:
 1. \`sidecar context --format markdown\`
-2. implement changes
-3. \`sidecar worklog record ...\`
-4. if behavior/design/architecture changed: \`sidecar decision record ...\`
+2. \`sidecar worklog record --done "<what changed>" --files <paths> --by agent\`
+3. if behavior/design/architecture changed:
+   \`sidecar decision record --title "<decision>" --summary "<why + rejected alternative>" --by agent\`
+4. if follow-up exists and it meets task criteria:
+   \`sidecar task create --title "<follow-up>" --summary "<summary>" --trigger "<trigger>" --entry-points <path1,path2> --done-condition "<done>" --validate-cmd "<cmd>" --priority medium\`
 5. \`sidecar summary refresh\`
 
-## Scope rules
-
-- If files changed: always record a worklog.
-- If behavior/design choice changed: record a decision.
-- If follow-up work exists: add a task.
-- Never skip summary refresh after recording work.
-
-## Definition of Done
-
-- [ ] Context reviewed
-  - \`sidecar context --format markdown\`
-- [ ] Work recorded
-  - \`sidecar worklog record --done "<what changed>" --files <paths> --by agent\`
-- [ ] Decision recorded when needed
-  - \`sidecar decision record --title "<decision>" --summary "<why>" --by agent\`
-- [ ] Follow-up task created when needed
-  - \`sidecar task add "<follow-up>" --priority medium --by agent\`
-- [ ] Summary refreshed
-  - \`sidecar summary refresh\`
-
-## Command patterns
-
-- Context: \`sidecar context --format markdown\`
-- Worklog: \`sidecar worklog record --done "<what changed>" --files src/a.ts,src/b.ts --by agent\`
-- Decision: \`sidecar decision record --title "<title>" --summary "<summary>" --by agent\`
-- Task: \`sidecar task add "<follow-up>" --priority medium --by agent\`
-- Summary: \`sidecar summary refresh\`
-
-## Example: small feature build
-
-\`\`\`bash
-sidecar context --format markdown
-# implement small todo app feature in src/app.ts and src/todo.ts
-sidecar worklog record --goal "todo feature" --done "Added todo CRUD handlers and wired routes" --files src/app.ts,src/todo.ts --by agent
-sidecar decision record --title "Use in-memory store for v1" --summary "Keeps implementation simple for initial feature" --by agent
-sidecar task add "Persist todos to sqlite" --priority medium --by agent
-sidecar summary refresh
-\`\`\`
+Run \`sidecar summary refresh\` only after you actually recorded something.
+
+## Command reference
+
+\`sidecar context --format markdown\`
+\`sidecar worklog record --done "<what changed>" --files <paths> --by agent\`
+\`sidecar decision record --title "<title>" --summary "<why + rejected alternative>" --by agent\`
+\`sidecar task create --title "<follow-up>" --summary "<summary>" --trigger "<trigger>" --entry-points <paths> --done-condition "<done>" --validate-cmd "<cmd>" --priority medium\`
+\`sidecar task set-status <task-id> --to active|blocked|done --reason "<why>" --by agent\`
+\`sidecar summary refresh\`
 
 ## Optional hygiene reminder
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecar-cli",
-  "version": "0.1.5-rc.1",
+  "version": "0.1.6-beta.2",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",