clawspec 1.0.8 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.8",
+  "version": "1.0.11",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [

package/src/orchestrator/service.ts

@@ -675,6 +675,13 @@ export class ClawSpecService {
         repoStatePaths.planningJournalSnapshotFile,
         project.planningJournal?.lastSyncedAt,
       );
+      const snapshot = await journalStore.readSnapshot(repoStatePaths.planningJournalSnapshotFile);
+      const digest = await journalStore.digest(project.changeName);
+      this.logger.info(`[clawspec] cs-work check for ${project.changeName}:`);
+      this.logger.info(`  - hasUnsyncedChanges: ${hasUnsyncedChanges}`);
+      this.logger.info(`  - Snapshot: entryCount=${snapshot?.entryCount}, lastEntryAt=${snapshot?.lastEntryAt}, hash=${snapshot?.contentHash?.slice(0, 8)}`);
+      this.logger.info(`  - Current digest: entryCount=${digest.entryCount}, lastEntryAt=${digest.lastEntryAt}, hash=${digest.contentHash.slice(0, 8)}`);
+      this.logger.info(`  - fallbackLastSyncedAt: ${project.planningJournal?.lastSyncedAt}`);
       if (!hasUnsyncedChanges) {
         const isDetached = !isProjectContextAttached(project);
         if (isDetached) {
@@ -951,7 +958,8 @@ export class ClawSpecService {
       return;
     }
 
-    const planningProject = await this.findPlanningProjectBySessionKey(ctx.sessionKey);
+    const planningProject = await this.findPlanningProjectBySessionKey(ctx.sessionKey)
+      ?? await this.findPlanningProjectByContext(ctx);
     if (planningProject) {
       await this.finalizePlanningTurn(planningProject, event);
       return;
@@ -2314,6 +2322,27 @@ export class ClawSpecService {
     );
   }
 
+  private async findPlanningProjectByContext(ctx: PromptBuildContext): Promise<ProjectState | undefined> {
+    const routingContext = deriveRoutingContext(ctx);
+    if (!routingContext.channelId) {
+      return undefined;
+    }
+
+    const match = await this.stateStore.findActiveProjectForMessage({
+      channel: routingContext.channel,
+      channelId: routingContext.channelId,
+      accountId: routingContext.accountId,
+      conversationId: routingContext.conversationId,
+    });
+    if (!match) {
+      return undefined;
+    }
+
+    return match.project.status === "planning" && match.project.phase === "planning_sync"
+      ? match.project
+      : undefined;
+  }
+
   private async findDiscussionProjectBySessionKey(sessionKey?: string): Promise<ProjectState | undefined> {
     if (!sessionKey) {
       return undefined;
@@ -2438,9 +2467,12 @@ export class ClawSpecService {
       }
     }
 
-    if (!journalDirty) {
-      await journalStore.writeSnapshot(repoStatePaths.planningJournalSnapshotFile, project.changeName, timestamp);
-    }
+    await journalStore.writeSnapshot(repoStatePaths.planningJournalSnapshotFile, project.changeName, timestamp);
+    const writtenSnapshot = await journalStore.readSnapshot(repoStatePaths.planningJournalSnapshotFile);
+    const currentDigest = await journalStore.digest(project.changeName);
+    this.logger.info(`[clawspec] Planning snapshot written for ${project.changeName}:`);
+    this.logger.info(`  - Snapshot: entryCount=${writtenSnapshot?.entryCount}, lastEntryAt=${writtenSnapshot?.lastEntryAt}, hash=${writtenSnapshot?.contentHash?.slice(0, 8)}`);
+    this.logger.info(`  - Current digest: entryCount=${currentDigest.entryCount}, lastEntryAt=${currentDigest.lastEntryAt}, hash=${currentDigest.contentHash.slice(0, 8)}`);
     await this.writeLatestSummary(repoStatePaths, latestSummary);
 
     const finalized = await this.stateStore.updateProject(project.channelKey, (current) => ({
@@ -3172,6 +3204,10 @@ function isPassiveAssistantPlanningMessage(text: string): boolean {
     return true;
   }
 
+  if (/^heartbeat(?:[_\s-]?(?:ok|ping|alive))?$/i.test(normalized)) {
+    return true;
+  }
+
   const collapsed = normalized.replace(/\s+/g, " ").trim();
   if (/^[▶✓⚠↻ℹ]/u.test(collapsed)) {
     return true;

package/src/worker/prompts.ts

@@ -188,18 +188,26 @@ export function buildPlanningPrependContext(params: {
         "Required workflow for this turn:",
         "0. The active change directory shown above is the only OpenSpec change directory you may inspect or modify in this turn.",
         "1. Read planning-journal.jsonl, .openspec.yaml, and any planning artifacts that already exist.",
-        "2. Treat the prefetched OpenSpec instruction files in this context as the authoritative source for artifact structure, output paths, and writing guidance.",
-        "3. Use the current visible chat context plus the planning journal to decide whether there are substantive new requirements, constraints, or design changes since the last planning sync.",
-        "4. If there is no substantive planning change, say so clearly in chat and do not rewrite artifacts unnecessarily.",
-        "5. If artifacts are missing or stale, update `proposal`, `specs`, `design`, and `tasks` in dependency order using those prefetched OpenSpec instruction files.",
-        "6. Do not generate or rewrite planning artifacts from ad-hoc structure guesses; follow OpenSpec instruction/template constraints only.",
-        "7. Before updating each artifact, post a short chat update naming the artifact you are about to refresh.",
-        "8. After updating each artifact, post a short chat update describing what changed and what artifact comes next.",
-        "9. For any implementation-oriented task item, ensure tasks.md contains an explicit testing task (new tests or updated tests) and a validation command.",
-        "10. Stop after planning artifacts are refreshed and apply-ready. Do not implement code in this turn.",
-        "11. End with a concise summary and a mandatory final line exactly in this shape: `Next: run `cs-work` to start implementation.`",
-        "12. Never scan sibling directories under `openspec/changes`, never switch to another change, and never restore or rewrite unrelated files.",
-        "13. Do not claim that OpenSpec instructions were skipped in this sync turn. The plugin already executed those commands before this turn began.",
+        "2. **CRITICAL**: The prefetched OpenSpec instruction blocks below contain the EXACT prompts you must follow to generate each artifact.",
+        "3. Each instruction block shows:",
+        "   - Instruction: The EXACT prompt/guidance for generating that artifact",
+        "   - Template: The structure/format to follow",
+        "4. **YOU MUST**:",
+        "   - Treat each instruction block's 'Instruction' section as if it were given to you directly by the user",
+        "   - Follow the instruction's requirements, structure, and sections EXACTLY as specified",
+        "   - Use the planning journal and user requirements to fill in the CONTENT, but follow the instruction for STRUCTURE",
+        "   - Do NOT create your own format - the instruction tells you exactly what to write and how",
+        "5. The allowed planning scope is limited to what is explicitly supported by the current user message, the planning journal, existing dependency artifacts, and the prefetched OpenSpec instructions.",
+        "6. Do not invent endpoints, features, constraints, files, acceptance criteria, test scenarios, or architecture details that are not grounded in those sources.",
+        "7. If there is no substantive planning change, say so clearly in chat and do not rewrite artifacts unnecessarily.",
+        "8. Update artifacts in dependency order: proposal → specs → design → tasks, using the prefetched instruction prompts for each.",
+        "9. Before updating each artifact, post a short chat update naming the artifact you are about to refresh.",
+        "10. After updating each artifact, post a short chat update describing what changed and what artifact comes next.",
+        "11. For any implementation-oriented task item, ensure tasks.md contains an explicit testing task (new tests or updated tests) and a validation command.",
+        "12. Stop after planning artifacts are refreshed and apply-ready. Do not implement code in this turn.",
+        "13. End with a concise summary and a mandatory final line exactly in this shape: `Next: run `cs-work` to start implementation.`",
+        "14. Never scan sibling directories under `openspec/changes`, never switch to another change, and never restore or rewrite unrelated files.",
+        "15. Do not claim that OpenSpec instructions were skipped in this sync turn. The plugin already executed those commands before this turn began.",
       ]
     : [
         "Discussion rules for this turn:",

package/test/assistant-journal.test.ts

@@ -166,3 +166,38 @@ test("inbound bot/system messages are ignored by planning journal capture", asyn
   assert.equal(project?.planningJournal?.dirty, false);
   assert.equal(project?.planningJournal?.entryCount, 0);
 });
+
+test("heartbeat assistant replies are not appended to the planning journal", async () => {
+  const harness = await createServiceHarness("clawspec-ignore-heartbeat-journal-");
+  const { service, repoPath } = harness;
+  const channelKey = "discord:ignore-heartbeat-journal:default:main";
+  const promptContext = createPromptContext("ignore-heartbeat-journal");
+  const userPrompt = "Add one more API endpoint.";
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+  await service.recordPlanningMessageFromContext(promptContext, userPrompt);
+  await service.handleBeforePromptBuild(
+    { prompt: userPrompt, messages: [] },
+    promptContext,
+  );
+
+  await service.handleAgentEnd(
+    {
+      success: true,
+      messages: [
+        { role: "user", content: userPrompt },
+        { role: "assistant", content: "HEARTBEAT_OK" },
+      ],
+    },
+    promptContext,
+  );
+
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const journalStore = new PlanningJournalStore(repoStatePaths.planningJournalFile);
+  const entries = await journalStore.list("demo-change");
+
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0]?.role, "user");
+});

package/test/planning-journal.test.ts

@@ -67,3 +67,58 @@ test("planning journal falls back to lastSyncedAt when no snapshot exists yet",
     true,
   );
 });
+
+test("snapshot is always written after planning sync regardless of journal dirty state", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-snapshot-always-"));
+  const journalPath = path.join(tempRoot, "planning-journal.jsonl");
+  const snapshotPath = path.join(tempRoot, "planning-journal.snapshot.json");
+  const store = new PlanningJournalStore(journalPath);
+
+  await store.append({
+    timestamp: "2026-03-27T03:00:00.000Z",
+    changeName: "test",
+    role: "user",
+    text: "initial requirement",
+  });
+
+  const snapshot1 = await store.writeSnapshot(snapshotPath, "test", "2026-03-27T03:05:00.000Z");
+  assert.equal(snapshot1.entryCount, 1);
+
+  await store.append({
+    timestamp: "2026-03-27T03:10:00.000Z",
+    changeName: "test",
+    role: "assistant",
+    text: "planning sync response",
+  });
+
+  const snapshot2 = await store.writeSnapshot(snapshotPath, "test", "2026-03-27T03:15:00.000Z");
+  assert.equal(snapshot2.entryCount, 2);
+  assert.equal(await store.hasUnsyncedChanges("test", snapshotPath), false);
+});
+
+test("snapshot correctly captures all journal entries including assistant messages", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-snapshot-complete-"));
+  const journalPath = path.join(tempRoot, "planning-journal.jsonl");
+  const snapshotPath = path.join(tempRoot, "planning-journal.snapshot.json");
+  const store = new PlanningJournalStore(journalPath);
+
+  await store.append({
+    timestamp: "2026-03-27T03:00:00.000Z",
+    changeName: "test",
+    role: "user",
+    text: "user requirement",
+  });
+  await store.append({
+    timestamp: "2026-03-27T03:05:00.000Z",
+    changeName: "test",
+    role: "assistant",
+    text: "assistant response",
+  });
+
+  const snapshot = await store.writeSnapshot(snapshotPath, "test");
+  const digest = await store.digest("test");
+
+  assert.equal(snapshot.entryCount, digest.entryCount);
+  assert.equal(snapshot.lastEntryAt, digest.lastEntryAt);
+  assert.equal(snapshot.contentHash, digest.contentHash);
+});

package/test/queue-planning.test.ts

@@ -168,6 +168,8 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
   assert.match(injected?.prependContext ?? "", /openspec instructions proposal --change demo-change --json/);
   assert.match(injected?.prependContext ?? "", /planning-instructions[\\/]+proposal\.json/);
   assert.deepEqual(instructionCalls, ["proposal", "specs", "design", "tasks"]);
+  assert.match(injected?.prependContext ?? "", /allowed planning scope is limited/i);
+  assert.match(injected?.prependContext ?? "", /Do not invent endpoints, features, constraints, files, acceptance criteria, test scenarios, or architecture details/i);
   assert.match(injected?.prependContext ?? "", /mandatory final line exactly in this shape/i);
   assert.equal(runningProject?.status, "planning");
   assert.equal(runningProject?.phase, "planning_sync");
@@ -207,6 +209,48 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
   assert.equal(snapshot?.changeName, "demo-change");
 });
 
+test("cs-plan finalizes and writes a fresh snapshot even if agent_end sessionKey changes", async () => {
+  const harness = await createServiceHarness("clawspec-visible-plan-fallback-");
+  const { service, stateStore, repoPath } = harness;
+  const channelKey = "discord:visible-plan-fallback:default:main";
+  const promptContext = {
+    trigger: "user",
+    channel: "discord",
+    channelId: "visible-plan-fallback",
+    accountId: "default",
+    conversationId: "main",
+    sessionKey: "agent:main:discord:channel:visible-plan-fallback",
+  };
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+  await service.recordPlanningMessageFromContext(promptContext, "add another API endpoint");
+
+  await service.handleBeforePromptBuild(
+    { prompt: "cs-plan", messages: [] },
+    promptContext,
+  );
+
+  await service.handleAgentEnd(
+    { messages: [], success: true, durationMs: 10 },
+    {
+      ...promptContext,
+      sessionKey: "agent:main:discord:channel:visible-plan-fallback:other",
+    },
+  );
+
+  const finalized = await stateStore.getActiveProject(channelKey);
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const snapshot = await readJsonFile<any>(repoStatePaths.planningJournalSnapshotFile, null);
+
+  assert.equal(finalized?.status, "ready");
+  assert.equal(finalized?.phase, "tasks");
+  assert.equal(finalized?.planningJournal?.dirty, false);
+  assert.equal(snapshot?.changeName, "demo-change");
+  assert.equal(snapshot?.entryCount, 1);
+});
+
 test("cs-plan clears stale execution control artifacts from earlier worker runs", async () => {
   const harness = await createServiceHarness("clawspec-visible-plan-cleanup-");
   const { service, stateStore, repoPath } = harness;