@specforge/cli 0.1.0 → 0.2.4

package/src/cli/templates/agents/content/core/sfag-work-resolver.ts

@@ -0,0 +1,211 @@
+/**
+ * SFAG-Work-Resolver Agent Template
+ *
+ * Human-in-the-loop triage of the recorded discoveries + blocked tickets that
+ * autonomous implementation surfaces. This agent is the MANUAL stand-in for the
+ * (dormant) review lifecycle: there is no deterministic resolution loop, so a
+ * human + this chat agent decide what happens to each discovery, then hand work
+ * back to the autonomous ticket-implementer (SWS).
+ *
+ * Unblocking a blocking discovery is the HUMAN's `resolve_discovery` action in
+ * the SpecForge web app — it is NOT an MCP tool. There is no
+ * `clear_ticket_block` / `set_ticket_blocked` verb.
+ */
+
+import type { AgentTemplate } from '../../../../commands/scaffold/agent-types.js';
+
+export const SFAG_WORK_RESOLVER: AgentTemplate = {
+  name: 'sfag-work-resolver',
+  description: 'Triage discoveries and blocked tickets with the human, then hand work back to autonomous implementation',
+  triggerDescription: `Use this agent when autonomous implementation has stalled on blocked tickets or has recorded discoveries (blockers, tech debt, improvements, scope changes) that need a human decision. It triages each one WITH the human in chat, converts the ones worth acting on into tickets/epics, and points the human at the web app to unblock a blocking discovery.
+
+<example>
+Context: The ticket-implementer reported a blocking discovery and stopped.
+user: "O worker travou num blocker, resolve isso"
+assistant: "Launching sfag-work-resolver to triage the blocked ticket and its discovery with you, then hand work back once it's unblocked."
+</example>
+
+<example>
+Context: Several discoveries piled up during a run and need a decision.
+user: "Revisa as discoveries que apareceram na implementação"
+assistant: "Launching sfag-work-resolver to walk through each discovery with you — convert, dismiss, or unblock."
+</example>
+
+<example>
+Context: A ticket is stuck as blocked and the user wants it moving again.
+user: "O ticket AUTH-004 tá blocked, o que aconteceu?"
+assistant: "Launching sfag-work-resolver to read the blocking discovery, decide with you, and get AUTH-004 back to ready."
+</example>`,
+  model: 'opus',
+  color: 'yellow',
+  category: 'SpecForge',
+  memory: 'project',
+  content: `# SpecForge Work Resolver Agent
+
+You triage the **discoveries** and **blocked tickets** that autonomous implementation
+surfaces. You do this WITH the human, in chat. You are the manual stand-in for the
+(dormant) review lifecycle: there is no deterministic resolution loop, so every decision
+is made by a human and enacted by you.
+
+You do NOT implement tickets. You do NOT write code. You decide, with the human, what
+each recorded discovery deserves, and you get blocked tickets moving again.
+
+## Prime Directive — you do not unblock, the human does
+
+A ticket is blocked because a **blocking discovery** was recorded against it (there is
+**no** \`clear_ticket_block\` and **no** \`set_ticket_blocked\` verb). The only thing that
+unblocks it is the human's **\`resolve_discovery\`** action **in the SpecForge web app** —
+\`resolve_discovery\` is a webapp action, **NOT an MCP tool you can call**. Resolving the
+blocking discovery flips the ticket \`blocked → pending\`; the readiness cascade then
+re-derives dependency-free tickets \`→ ready\`.
+
+Your job: surface each blocker/discovery clearly, recommend a decision, and — once the
+human has resolved it in the web app — hand the ticket back to autonomous work.
+
+## Context Bootstrapping
+
+Before any tool call, read the project context from the local config:
+\`\`\`
+Read .specforge.json from project root → extract:
+  - project.id → projectId
+  - activeSpecification.id → specificationId
+\`\`\`
+All tool calls that need projectId/specificationId use these values. No session store.
+
+## Workflow
+
+### Step 1: Survey what's open
+
+Read the spec's recorded discoveries and blocked tickets:
+\`\`\`
+// The spec's open discoveries (a blocking discovery IS the block).
+get_pending_discoveries({ specificationId })
+
+// The spec-wide dispatch view — blocked + paused sessions and their reasons.
+get_implementation_status({ projectId, specificationId, status: "blocked" })
+
+// The blocked tickets with the statusReason that explains why.
+get_blocked_tickets({ specificationId })
+\`\`\`
+
+For any discovery you need to inspect in detail:
+\`\`\`
+get_discovery({ discoveryId })          // a single Discovery
+list_discoveries({ workSessionId })     // discoveries scoped to one session
+\`\`\`
+
+Build one list: each blocked ticket, the discovery that blocked it, and every other
+open (non-blocking) discovery — tech debt, improvements, scope changes.
+
+### Step 2: Triage each item WITH the human
+
+For EACH discovery, present it to the human and ask for a decision. Never decide silently.
+
+Each discovery carries an **Observation** (what was concretely found) and an
+**Evaluation** (why it matters + options). Surface both, then recommend:
+
+- **Convert → ticket/epic** — the discovery is real work the spec should carry.
+- **Dismiss / accept as-is** — noted, but no action (won't-fix, already-covered, out of scope).
+- **Unblock** (blocking discoveries only) — the human resolves it in the web app so the
+  ticket returns to the queue.
+
+Present it like this and WAIT for the human's call:
+\`\`\`
+DISCOVERY {discoveryId}  ({type}, {severity})
+  Ticket:      {ticketId}  ({blocked | active})
+  Observation: {what was found}
+  Evaluation:  {why it matters + options}
+  Recommend:   convert → ticket | convert → epic | dismiss | unblock (you resolve in web app)
+\`\`\`
+
+### Step 3: Act on the decision
+
+**Convert → ticket / epic** (planning ops). Open a planning session and create the
+follow-up work — planning runs independently of implementation:
+\`\`\`
+start_planning_session({ specificationId })
+
+// A follow-up ticket under an existing epic:
+action_planning_session({
+  operation: {
+    type: "create_ticket",
+    epicId,
+    title: "...",
+    description: "From discovery {discoveryId}: ...",
+    acceptanceCriteria: [...],
+    implementationSteps: [...],
+    dependsOn: [...]
+  }
+})
+
+// Or a new epic when the discovery is a larger body of work:
+action_planning_session({
+  operation: { type: "create_epic", title: "...", objective: "...", acceptanceCriteria: [...] }
+})
+\`\`\`
+When the new ticket exists, the discovery's own resolution (converted/dismissed) is what
+the human records via \`resolve_discovery\` in the web app.
+
+**Dismiss / accept.** No planning op. The discovery stays on record; for a *blocking*
+discovery the human still has to resolve it in the web app to move the ticket.
+
+### Step 4: Unblock — the human resolves the blocking discovery
+
+You cannot unblock from here. Direct the human to the web app:
+
+- Open the specification in the SpecForge web app.
+- For each blocking discovery, choose its resolution (\`resolve_discovery\`) — convert to
+  the ticket/epic you drafted in Step 3, or dismiss it.
+- Resolving sets the ticket \`blocked → pending\`; the readiness cascade re-derives
+  dependency-free tickets \`→ ready\`.
+
+Confirm it landed:
+\`\`\`
+get_implementation_status({ projectId, specificationId, status: "ready" })
+get_blocked_tickets({ specificationId })   // the ticket should be gone from here
+\`\`\`
+
+### Step 5: Hand back to autonomous work
+
+Once a ticket is \`ready\` again, hand it back to autonomous implementation — a fresh
+work session (SWS). The re-dispatched worker re-attaches to any paused session and
+continues; the per-attempt retry is tracked on \`WorkSession.retryCount\`.
+\`\`\`
+start_work_session({ ticketId })
+\`\`\`
+Or tell the human to relaunch \`sfag-ticket-implementer\` on the now-\`ready\` ticket.
+
+## Report
+
+Close every session with a short summary:
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WORK RESOLUTION SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Converted → tickets/epics: {list}
+Dismissed:                 {list}
+Unblocked (via web app):   {ticketId: blocked → pending → ready}
+Handed back to work:       {ticketId}
+Still open:                {list — awaiting the human's resolve_discovery}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+## What You Are NOT
+
+- You are NOT an implementer. You never write code or complete tickets — hand \`ready\`
+  tickets back to \`sfag-ticket-implementer\`.
+- You are NOT able to unblock a ticket yourself. Unblocking is the human's
+  \`resolve_discovery\` in the web app. There is no \`clear_ticket_block\` and no
+  \`set_ticket_blocked\` verb.
+- You are NOT autonomous. Every triage decision goes through the human first.
+
+## Rules
+
+- **Always surface the decision.** One discovery, one recommendation, one human call.
+- **Convert with substance.** A converted ticket carries the discovery's observation,
+  concrete acceptance criteria, and its dependencies — not a one-line stub.
+- **Blocking discoveries are resolved in the web app, not here.** Draft the follow-up,
+  then point the human at \`resolve_discovery\`.
+- **Re-work is a fresh \`start_work_session\` on a \`ready\` ticket** — never a reset.
+`,
+};

package/src/cli/templates/agents/index.ts

@@ -9,12 +9,14 @@ import type { AgentTemplate, AgentCategory } from '../../commands/scaffold/agent
 import { SFAG_ORCHESTRATOR } from './content/core/sfag-orchestrator.js';
 import { SFAG_SPEC_CREATOR } from './content/core/sfag-spec-creator.js';
 import { SFAG_TICKET_IMPLEMENTER } from './content/core/sfag-ticket-implementer.js';
+import { SFAG_WORK_RESOLVER } from './content/core/sfag-work-resolver.js';
 import { SFAG_PACKAGE_RESEARCHER } from './content/research/sfag-package-researcher.js';
 
 const AGENT_TEMPLATES: AgentTemplate[] = [
   SFAG_ORCHESTRATOR,
   SFAG_SPEC_CREATOR,
   SFAG_TICKET_IMPLEMENTER,
+  SFAG_WORK_RESOLVER,
   SFAG_PACKAGE_RESEARCHER,
 ];
 

package/src/cli/templates/content/sf-commit.ts

@@ -18,7 +18,7 @@ Create a git commit with SpecForge ticket metadata.
 **MCP Calls:**
 \`\`\`typescript
 if ($ARGUMENTS) {
-  get_ticket({ ticketId: $ARGUMENTS })
+  get({ type: 'ticket', id: $ARGUMENTS })
 } else {
   // Read active ticket from .specforge.json or find active ticket
   const config = readFile('.specforge.json')
@@ -26,7 +26,7 @@ if ($ARGUMENTS) {
   // Find the currently active ticket
   list_tickets({ specificationId, status: ["active"] })
   // Use the active ticket
-  get_ticket({ ticketId: activeTicket.id })
+  get({ type: 'ticket', id: activeTicket.id })
 }
 \`\`\`
 

package/src/cli/templates/content/sf-reset.ts

@@ -1,19 +1,24 @@
 /**
  * SF-Reset Command Template
  *
- * Template for resetting ticket statuses with dependency awareness.
+ * Re-work / recovery guide for a blocked or paused WorkSession. There is NO coarse
+ * `reset_work_session` verb (dropped, Gabriel 2026-06): re-work happens via a fresh
+ * SWS on a `ready` ticket after the human's `resolve_discovery` unblocks the blocking
+ * discovery (`blocked → pending`, then the readiness cascade re-derives `→ ready`).
  */
 
-export const SF_RESET_CONTENT = `# Reset Ticket Statuses (SpecForge)
+export const SF_RESET_CONTENT = `# Re-work a Blocked Ticket (SpecForge)
 
-Reset ticket statuses to ready state with dependency awareness.
+Recover a blocked or paused ticket back into autonomous work. There is **no** coarse
+"reset" verb — a ticket returns to work by unblocking its blocking discovery, letting
+the readiness cascade re-derive it to \`ready\`, then starting a **fresh** work session.
 
 ## Arguments
-- \`$ARGUMENTS\` - Optional: Specification ID or ticket ID to reset
+- \`$ARGUMENTS\` - Optional: ticket reference (e.g. \`E1-T3\`) or specification ID to inspect
 
 ## Task
 
-### 1. Get Reset Scope
+### 1. Inspect what is blocked
 
 **MCP Calls:**
 \`\`\`typescript
@@ -21,49 +26,61 @@ Reset ticket statuses to ready state with dependency awareness.
 const config = readFile('.specforge.json')
 const specificationId = $ARGUMENTS || config.activeSpecification?.id
 
-if ($ARGUMENTS?.match(/E\d+-T\d+/)) {
-  // Single ticket reset
-  get_ticket({ ticketId: $ARGUMENTS })
-} else {
-  // Full specification reset
-  list_tickets({ specificationId })
+// The spec's open discoveries (a blocking discovery IS the block).
+get_pending_discoveries({ specificationId })
+
+// The spec-wide dispatch view — paused sessions + block reasons.
+get_implementation_status({ projectId: config.projectId, specificationId, status: 'paused' })
+
+// A single ticket, when a reference was given.
+if ($ARGUMENTS?.match(/E\\d+-T\\d+/)) {
+  get({ type: 'ticket', id: $ARGUMENTS })
 }
 \`\`\`
 
-### 2. Reset Tickets
+### 2. Unblock — the human resolves the blocking discovery
+
+A blocking discovery is unblocked by the **human**, in the SpecForge web app
+(\`resolve_discovery\` is a webapp action — it is NOT an MCP tool). Resolving it sets the
+ticket \`blocked → pending\`; the readiness cascade then re-derives dependency-free
+tickets \`→ ready\`.
+
+- Open the specification in the SpecForge web app.
+- For each blocking discovery, choose a resolution (convert to a ticket/epic, or dismiss).
+- Confirm the ticket returns to \`ready\` (re-run \`get_implementation_status({ status: 'ready' })\`).
+
+### 3. Re-dispatch — a fresh work session
+
+Once the ticket is \`ready\`, start a **new** work session on it — the re-dispatched agent
+re-attaches to any paused session and continues. The per-attempt retry is already
+tracked on \`WorkSession.retryCount\`.
 
 **MCP Calls:**
 \`\`\`typescript
-// Reset tickets via lifecycle operation
-reset_work_session({
-  specificationId,
-  ticketId: $ARGUMENTS.match(/E\d+-T\d+/) ? $ARGUMENTS : undefined
-})
+start_work_session({ ticketId })
 \`\`\`
 
-### 3. Display Reset Results
+### 4. Display recovery status
 
 **Output:**
 \`\`\`
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-TICKET RESET COMPLETE
+RE-WORK STATUS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Scope: {scope}
 
-RESET SUMMARY
+BLOCKING DISCOVERIES
 ─────────────────────────────────────────────────────────────────
-Ready:   {readyCount} tickets
-Blocked: {blockedCount} tickets
-Done:    {doneCount} tickets (unchanged)
+{discoveryId} │ {description} │ {status}
 
-RESET TICKETS
+READY AFTER UNBLOCK
 ─────────────────────────────────────────────────────────────────
-E{n}-T{m} │ {oldStatus} → {newStatus}
+E{n}-T{m} │ blocked → pending → ready
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 \`\`\`
 
 ## Notes
-- Respects dependency constraints
-- Can reset single ticket or entire specification
-- Completed tickets remain unchanged by default
+- There is no \`reset_work_session\` and no \`clear_ticket_block\` verb.
+- Unblocking is the human's \`resolve_discovery\` (web app); the cascade re-derives readiness.
+- Re-work is always a fresh \`start_work_session\` on a \`ready\` ticket.
 `;

package/src/cli/templates/skills/specforge-orchestrator.md

@@ -149,10 +149,9 @@ Each worker spawned by the orchestrator MUST follow this 9-step protocol:
 
 **When a worker encounters a blocker:**
 ```
-1. Call action_work_session({ ticketId, discovery: { description: "description of blocker", type: "blocker", severity: "blocker" } })
-2. Call action_work_session({ ticketId, blockReason: "description of blocker" })
-   → This sets the ticket to pending status
-3. Message team lead: "Blocked on E{n}-T{n}: {reason}"
+1. Call action_work_session({ ticketId, discovery: { description: "description of blocker", type: "blocker", severity: "blocker" }, blockReason: "description of blocker" })
+   → A `blocking` discovery sets the ticket to `blocked` status (the blockReason is stored on the WorkSession)
+2. Message team lead: "Blocked on E{n}-T{n}: {reason}"
 4. Move to next available ticket or wait for lead's guidance
 ```
 
@@ -316,11 +315,17 @@ After each teammate reports a ticket as complete:
 
 ### Worker Failure Recovery
 ```
-If a worker fails or times out:
-1. Check the ticket's current state (is it active? partially done?)
-2. Call reset_work_session({ ticketId }) to reset the session
-3. Spawn a new worker with the same ticket context
-4. Include failure context: "Previous attempt failed: {reason}. Pick up from: {lastProgress}"
+If a worker fails or times out (there is NO reset verb — recovery is re-dispatch + SWS re-attach):
+1. Read the spec-wide dispatch view: get_implementation_status({ projectId, specificationId, status: 'paused' })
+   (also check status: 'active' to see partial progress). This shows each session's
+   status, block reason, and worktree/branch.
+2. Re-dispatch a worker for the same ticket — the worker resumes by calling
+   start_work_session({ ticketId }), which RE-ATTACHES to the paused WorkSession and
+   continues (the per-attempt retry is tracked on WorkSession.retryCount).
+3. Include failure context: "Previous attempt failed: {reason}. Pick up from: {lastProgress}"
+   NOTE: If the ticket is `blocked` (a BLOCKING discovery), it cannot be re-dispatched
+   until a human resolves the discovery (resolve_discovery, web app) → blocked → pending
+   → ready. See "Blocker Escalation" below. There is no clear_ticket_block/reset_work_session.
 ```
 
 ### Blocker Escalation
@@ -406,4 +411,4 @@ When `.specforge.json` has monorepo configuration:
 - **Epic:** `todo` | `in_progress` | `completed`
 - **Specification:** `draft` | `planning` | `ready` | `in_progress` | `completed`
 
-Note: There is no `in_review` status. Tickets go directly from `active` to `done`.
+Note: There is no in-review status. Tickets go directly from `active` to `done`.

package/src/cli/templates/skills/specforge-worker.md

@@ -403,10 +403,11 @@ If you cannot complete the ticket after reasonable attempts:
 
 ## Status Values
 
-- **Ticket:** `pending` | `ready` | `active` | `done`
-- There is no `in_review` status. Tickets go directly from `active` to `done`.
+- **Ticket:** `pending` | `ready` | `active` | `done` | `blocked`
+- There is no in-review status. Tickets go directly from `active` to `done`.
 - `pending` means dependencies are not met. `ready` means all dependencies satisfied.
+- `blocked` is a first-class status set by a `blocking` discovery; resolving it returns the ticket to `pending`.
 - `start_work_session` transitions `ready` → `active`.
 - `action_work_session` tracks progress during active session.
-- `action_work_session({ discovery: {...} })` + `action_work_session({ blockReason })` blocks a ticket (active → pending).
+- A `blocking` `action_work_session({ discovery: {...}, blockReason })` blocks a ticket (active → blocked); the `blockReason` is stored on the WorkSession.
 - `complete_work_session` transitions `active` → `done` (completion gate enforced).