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

package/README.md

@@ -79,6 +79,18 @@ Run locally in dev mode:
 npm run dev -- --help
 ```
 
+## Release channels
+
+Sidecar ships features through `beta` → `rc` → `stable` as version bumps — there are no per-feature channel flags. Install `@beta` to try new features early; install default (stable) for the latest promoted release.
+
+| Channel | Current version | Notes |
+| --- | --- | --- |
+| stable (`latest`) | `0.1.4` | Promoted releases. Homebrew tracks this channel. |
+| rc | _none newer than stable_ | Release candidates published only when preparing a stable cut. |
+| beta | `0.1.5-beta.2` | Dual-runner pipelines, run replay, ambient capture via Claude Code hooks, typed validation + auto-approve, freestanding prompt specs, `sidecar demo`. |
+
+Per-version release notes live at [github.com/karlhills/sidecar-cli/releases](https://github.com/karlhills/sidecar-cli/releases).
+
 ## Quick start
 
 1. Initialize in a project directory:
@@ -188,9 +200,9 @@ Notes, decisions, worklogs:
 
 Tasks:
 
-- `sidecar task add "<title>" [--description <text>] [--priority low|medium|high] [--by human|agent] [--json]`
-- `sidecar task done <task-id> [--by human|agent] [--json]`
-- `sidecar task list [--status open|done|all] [--format table|json] [--json]`
+- `sidecar task create --title "<title>" --summary "<summary>" --goal "<goal>" [--type feature|bug|chore|research] [--status draft|ready|queued|running|review|blocked|done] [--priority low|medium|high] [--json]`
+- `sidecar task set-status <task-id> --to draft|ready|queued|running|review|blocked|done --reason "<text>" [--by human|agent] [--session <id>] [--json]`
+- `sidecar task list [--status draft|ready|queued|running|review|blocked|done|all] [--json]`
 
 Sessions:
 
@@ -422,7 +434,7 @@ sidecar context --format markdown
 sidecar session start --actor agent --name codex
 sidecar decision record --title "Use SQLite" --summary "Local-first persistence"
 sidecar worklog record --goal "init flow" --done "Implemented schema and command surface" --files src/cli.ts,src/db/schema.ts
-sidecar task add "Add integration tests" --priority medium --by agent
+sidecar task create --title "Add integration tests" --summary "Add integration coverage for init flow" --goal "Ensure init flow has regression coverage" --priority medium
 sidecar summary refresh
 sidecar session end --summary "Initialization and recording flow implemented"
 ```
@@ -437,7 +449,7 @@ Required minimum for any code change:
 1. `sidecar context --format markdown`
 2. `sidecar worklog record --done "<what changed>" --files <paths> --by agent`
 3. if behavior/design changed: `sidecar decision record ...`
-4. if follow-up exists: `sidecar task add ...`
+4. if follow-up exists: `sidecar task create ...`
 5. `sidecar summary refresh`
 
 Optional local enforcement:
@@ -477,7 +489,7 @@ When changes are made in this repo, document them in Sidecar:
 1. `sidecar context --format markdown`
 2. `sidecar worklog record --done "<what changed>" --files <paths> --by human|agent`
 3. `sidecar decision record ...` when behavior/design changes
-4. `sidecar task add ...` for follow-up work
+4. `sidecar task create ...` for follow-up work
 5. `sidecar summary refresh`
 
 ## Local storage details
@@ -567,7 +579,7 @@ Standard JSON envelope:
 {
   "ok": true,
   "version": "1.0",
-  "command": "task add",
+  "command": "task create",
   "data": {},
   "errors": []
 }
@@ -579,7 +591,7 @@ Failure envelope:
 {
   "ok": false,
   "version": "1.0",
-  "command": "task add",
+  "command": "task create",
   "data": null,
   "errors": ["..."]
 }

package/dist/cli.js

@@ -22,7 +22,7 @@ import { refreshSummaryFile } from './services/summary-service.js';
 import { buildContext } from './services/context-service.js';
 import { getCapabilitiesManifest } from './services/capabilities-service.js';
 import { addArtifact, listArtifacts } from './services/artifact-service.js';
-import { addDecision, addNote, addWorklog, getActiveSessionId, listRecentEvents } from './services/event-service.js';
+import { addDecision, addNote, addWorklog, createEvent, getActiveSessionId, listRecentEvents } from './services/event-service.js';
 import { currentSession, endSession, startSession, verifySessionHygiene } from './services/session-service.js';
 import { HOOK_EVENTS, handleHookEvent, hookEventSchema, hookPayloadSchema } from './services/hook-service.js';
 import { loadPromptSpec } from './prompts/prompt-spec.js';
@@ -39,6 +39,7 @@ import { compileTaskPrompt } from './prompts/prompt-service.js';
 import { runPipelineExecution, runTaskExecution } from './services/run-orchestrator-service.js';
 import { loadRunnerPreferences } from './runners/config.js';
 import { assignTask, queueReadyTasks } from './services/task-orchestration-service.js';
+import { transitionTaskStatus } from './services/task-status-service.js';
 import { buildReviewSummary, createFollowupTaskFromRun, reviewRun } from './services/run-review-service.js';
 const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const actorSchema = z.enum(['human', 'agent']);
@@ -1100,7 +1101,7 @@ task
     .description('List task packets')
     .option('--status <status>', 'draft|ready|queued|running|review|blocked|done|all', 'all')
     .option('--json', 'Print machine-readable JSON output')
-    .addHelpText('after', '\nExamples:\n  $ sidecar task list\n  $ sidecar task list --status open\n  $ sidecar task list --json')
+    .addHelpText('after', '\nExamples:\n  $ sidecar task list\n  $ sidecar task list --status draft\n  $ sidecar task list --json')
     .action((opts) => {
     const command = 'task list';
     try {
@@ -1158,6 +1159,64 @@ task
         handleCommandError(command, Boolean(opts.json), err);
     }
 });
+task
+    .command('set-status <task-id>')
+    .description('Transition task packet status with validation and an audit note')
+    .requiredOption('--to <status>', 'draft|ready|queued|running|review|blocked|done')
+    .requiredOption('--reason <text>', 'Why this manual transition is needed')
+    .option('--by <actor>', 'human|agent', 'human')
+    .option('--session <session-id>', 'Session id override')
+    .option('--json', 'Print machine-readable JSON output')
+    .addHelpText('after', '\nExamples:\n  $ sidecar task set-status T-001 --to ready --reason "Ready to queue"\n  $ sidecar task set-status T-001 --to done --reason "Administrative cleanup" --by agent --json')
+    .action((taskIdText, opts) => {
+    const command = 'task set-status';
+    try {
+        const taskId = taskIdText.trim().toUpperCase();
+        const toStatus = taskPacketStatusSchema.parse(opts.to);
+        const reason = String(opts.reason ?? '').trim();
+        if (!reason)
+            fail('Reason is required');
+        const by = actorSchema.parse(opts.by);
+        const { db, projectId } = requireInitialized();
+        const sessionId = maybeSessionId(db, projectId, opts.session);
+        const result = transitionTaskStatus(resolveProjectRoot(), taskId, toStatus);
+        const eventId = createEvent(db, {
+            projectId,
+            type: 'note',
+            title: `Task ${result.task_id} status changed`,
+            summary: `${result.from_status} -> ${result.to_status}: ${reason}`,
+            details: {
+                task_id: result.task_id,
+                from_status: result.from_status,
+                to_status: result.to_status,
+                reason,
+                command: 'task set-status',
+            },
+            createdBy: by,
+            sessionId,
+        });
+        db.close();
+        respondSuccess(command, Boolean(opts.json), {
+            task: result,
+            event: {
+                id: eventId,
+                type: 'note',
+                title: `Task ${result.task_id} status changed`,
+                summary: `${result.from_status} -> ${result.to_status}: ${reason}`,
+                created_by: by,
+                session_id: sessionId,
+                created_at: nowIso(),
+            },
+        }, [
+            `Updated ${result.task_id}: ${result.from_status} -> ${result.to_status}.`,
+            `Reason: ${reason}`,
+            `Recorded note event #${eventId}.`,
+        ]);
+    }
+    catch (err) {
+        handleCommandError(command, Boolean(opts.json), err);
+    }
+});
 task
     .command('create-followup <run-id>')
     .description('Create a follow-up task packet from a run report')

package/dist/services/capabilities-service.js

@@ -222,6 +222,13 @@ export function getCapabilitiesManifest(version) {
                         arguments: ['<task-id>'],
                         options: ['--agent-role planner|builder-ui|builder-app|reviewer|tester', '--runner codex|claude', '--json'],
                     },
+                    {
+                        name: 'set-status',
+                        description: 'Transition task packet status with validation',
+                        json_output: true,
+                        arguments: ['<task-id>'],
+                        options: ['--to draft|ready|queued|running|review|blocked|done', '--reason <text>', '--by human|agent', '--session <id>', '--json'],
+                    },
                     {
                         name: 'create-followup',
                         description: 'Create follow-up task from run report',

package/dist/services/task-status-service.js

@@ -0,0 +1,33 @@
+import { SidecarError } from '../lib/errors.js';
+import { getTaskPacket, saveTaskPacket } from '../tasks/task-service.js';
+const TASK_STATUS_TRANSITIONS = {
+    draft: ['ready', 'blocked', 'done'],
+    ready: ['draft', 'queued', 'blocked', 'done'],
+    queued: ['ready', 'running', 'blocked'],
+    running: ['ready', 'review', 'blocked'],
+    review: ['ready', 'blocked', 'done'],
+    blocked: ['ready', 'done'],
+    done: ['review'],
+};
+export function allowedTaskStatusTransitions(fromStatus) {
+    return TASK_STATUS_TRANSITIONS[fromStatus];
+}
+export function transitionTaskStatus(rootPath, taskId, toStatus) {
+    const task = getTaskPacket(rootPath, taskId);
+    const fromStatus = task.status;
+    if (fromStatus === toStatus) {
+        throw new SidecarError(`Task ${task.task_id} is already '${toStatus}'`);
+    }
+    const allowed = allowedTaskStatusTransitions(fromStatus);
+    if (!allowed.includes(toStatus)) {
+        throw new SidecarError(`Invalid status transition for ${task.task_id}: ${fromStatus} -> ${toStatus}. Allowed: ${allowed.join(', ')}`);
+    }
+    const updated = { ...task, status: toStatus };
+    const filePath = saveTaskPacket(rootPath, updated);
+    return {
+        task_id: task.task_id,
+        from_status: fromStatus,
+        to_status: toStatus,
+        path: filePath,
+    };
+}

package/package.json

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