@specforge/canary-cli 0.2.16 → 0.2.18

package/src/cli/templates/agents/content/core/sfag-ticket-implementer.ts

@@ -98,6 +98,21 @@ So, before every \`start_work_session\`:
 (If you are not inside a git worktree, SWS still runs — the precondition treats a
 non-git caller as clean.)
 
+### Pass your \`worktree\` when you run in parallel
+
+The MCP-local git reads (clean status, commit hash) resolve in the MCP server's current
+directory. When several workers run **concurrently under one orchestrator, they share one
+MCP server** — so each worker MUST tell SWS/CWS which worktree it lives in, or every
+worker's git evidence would come from the launcher's directory instead of its own.
+
+- If the orchestrator gave you a worktree path, pass it as \`worktree\` on **every**
+  \`start_work_session\` and \`complete_work_session\` call (use the same value for both).
+- Two active sessions in the **same** worktree are denied (\`concurrent_worktree\`) — that
+  denial means you are missing (or sharing) a worktree; create your own (\`git worktree
+  add\`) and retry with its path.
+- Running a **single** session in the current directory? Omit \`worktree\` — the current
+  directory is used, exactly as before.
+
 ## Step 1: Pick a ticket (autonomous)
 
 Pick the next actionable ticket yourself — no need to ask anyone:
@@ -111,7 +126,8 @@ Keep going through ready tickets until none remain.
 
 Ensure the worktree is clean (see the git-clean precondition), then:
 \`\`\`
-start_work_session({ ticketId })
+start_work_session({ ticketId })                       // single session, current directory
+start_work_session({ ticketId, worktree: "/abs/path/to/your/worktree" })  // parallel worker
 // ready → active; returns the full orientation + workSessionId (the sessionId).
 \`\`\`
 Read the orientation in full. It IS your brief:
@@ -124,7 +140,9 @@ Read the orientation in full. It IS your brief:
 
 If SWS comes back \`outcome: "denied"\`, read the guidance and act on it: \`git_dirty\` →
 commit and retry; \`unfinished_dependencies\` → a dependency is not \`done\`, pick a
-different ready ticket; an aborted implementation → stop, this spec is off-limits.
+different ready ticket; \`concurrent_worktree\` → another active session is in your
+worktree, create your own (\`git worktree add\`) and retry with its \`worktree\` path; an
+aborted implementation → stop, this spec is off-limits.
 
 ## Step 3: Implement + record — the assay-driven order
 
@@ -193,15 +211,24 @@ action_work_session({ ticketId, action: {
 }})
 \`\`\`
 Any **extra or divergent** file (not in the planned set) needs a justification, or it
-costs coherence:
+costs coherence. When you justify one, VERIFY what plan item it fulfils and set
+\`fulfills\` (both \`kind\` and \`id\` are required): if the file **replaces a declared file**
+of a step, link it with \`{kind:"step", id:<step id>, fileId:<the declared fileChangeId>}\`
+— that link is what UNBLOCKS the finalize when the plan under-declared the file; if it
+exists to satisfy an **acceptance criterion or a test**, use
+\`{kind:"acceptance_criterion"|"test", id}\`:
 \`\`\`
 action_work_session({ ticketId, action: {
   action: "add_file_change_justification", workSessionId,
   expectedPath: "src/util/hash.ts", expectedAction: "create",
-  justification: "Extracted the hashing helper the AC requires; shared by the service."
+  justification: "Produced this instead of the declared src/util/crypto.ts; same role.",
+  fulfills: { kind: "step", id: "<step id>", fileId: "<declared fileChangeId>" }
 }})
 \`\`\`
-Use \`amend_file_change_justification\` to replace one after a rejection.
+A deviation that replaces a declared file WITHOUT a \`fulfills.step\` holds the finalize,
+and coherence reads low because the plan under-declared it — that is expected and honest.
+Use \`amend_file_change_justification\` to replace one after a rejection (re-declare the
+corrected \`fulfills\` — the amend OVERRIDES the prior link).
 
 ### 3d. Acceptance criteria (AC)
 
@@ -241,7 +268,10 @@ complete_work_session({
   ticketId,
   summary: "Implemented user registration: service, endpoint, validation, tests",
   filesCreated: [...], filesModified: [...],
-  validation: { tests: { passed: 8, failed: 0 } }
+  validation: { tests: { passed: 8, failed: 0 } },
+  // If you passed a worktree to start_work_session, pass the SAME one here so the
+  // commit hash is read from YOUR worktree (omit it for a single session).
+  // worktree: "/abs/path/to/your/worktree"
 })
 // active → done; finalizes the WorkSession; the cascade unblocks dependents.
 // When every spec ticket is done, the spec → done and the ImplementationSession finalizes.
@@ -330,6 +360,7 @@ ticket — never a reset.
 ## Quality Gate (self-check before complete_work_session)
 
 - [ ] Worktree was clean before start_work_session (no \`git_dirty\` denial)
+- [ ] If running in parallel: passed your \`worktree\` path to start_work_session AND complete_work_session
 - [ ] All implementation steps marked done via mark_implementation_step_completion
 - [ ] Tests run and recorded via record_test_result; every skip/failure justified
 - [ ] Every touched/divergent file recorded via record_file_change; divergences justified