agent-bober 0.11.6 → 0.15.0

package/skills/bober.impact/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: bober.impact
+description: Analyse the impact radius of a symbol or file in the code graph — which symbols are affected and which tests cover it. Writes a markdown report to .bober/graph/impact/<slug>.md.
+argument-hint: <symbol|file>
+handoffs:
+  - label: "Plan Feature"
+    command: /bober-plan
+    prompt: "Plan changes to the analysed symbol"
+  - label: "Run Sprint"
+    command: /bober-sprint
+    prompt: "Build changes to the affected code"
+---
+
+# bober.impact — Impact Analysis Skill
+
+You are running the **bober.impact** skill. Your job is to analyse the impact radius of a symbol or file — what other symbols depend on it and which tests cover it.
+
+## Usage
+
+```
+/bober-impact <symbol|file>
+```
+
+Examples:
+- `/bober-impact sandboxPath` — analyse a function by name
+- `/bober-impact src/graph/client.ts` — analyse a file
+- `/bober-impact GraphClient` — analyse a class
+- `/bober-impact TokensaveCli.sync` — analyse a method
+
+## What This Skill Produces
+
+A markdown file at `.bober/graph/impact/<slug>.md` with three sections:
+
+```markdown
+# Impact: <target>
+
+## Affected symbols
+- `<symbol>` (<kind>) — <file>:<line>
+...
+
+## Tests covering this symbol
+- `<symbol>` (<kind>) — <file>:<line>
+...
+```
+
+The slug is derived from the target: lowercase, non-alphanumeric characters replaced with `-`, consecutive `-` collapsed, leading/trailing `-` stripped, truncated to 40 characters.
+
+## Running via CLI
+
+```bash
+agent-bober impact sandboxPath
+```
+
+Output:
+```
+Starting graph engine...
+Analysing impact for: sandboxPath
+Impact report written: .bober/graph/impact/sandboxpath.md
+  Affected symbols: N
+  Test coverage:    N
+```
+
+## Running via MCP Tools (Alternative)
+
+You can produce equivalent output directly using MCP tools:
+
+1. Get impact radius: `get_impact_radius` with `{ target: "<symbol>" }`
+2. Find test coverage: `query_graph` with `{ pattern: "tests_for", target: { symbol: "<symbol>", ... } }`
+3. Format as markdown with the exact section headings:
+   - `# Impact: <target>`
+   - `## Affected symbols`
+   - `## Tests covering this symbol`
+4. Write to `.bober/graph/impact/<slug>.md`
+
+## Slug Derivation Rules
+
+```
+target.toLowerCase()
+  .replace(/[^a-z0-9]+/g, '-')   // non-alphanumeric → -
+  .replace(/-+/g, '-')            // collapse consecutive -
+  .replace(/^-+|-+$/g, '')        // strip leading/trailing -
+  .slice(0, 40)                   // max 40 chars
+```
+
+Examples:
+- `sandboxPath` → `sandboxpath`
+- `src/orchestrator/tools/handlers.ts` → `src-orchestrator-tools-handlers-ts`
+- `MyClass.doThing` → `myclass-dothing`
+- `__internal__` → `internal`
+
+## Prerequisites
+
+- `graph.enabled: true` in `bober.config.json`
+- `tokensave` >= 6.0.0-beta.1 installed
+- Graph must be initialised and synced (`agent-bober graph init && agent-bober graph sync`)
+
+## Error Handling
+
+- If graph.enabled=false: exits 1 with instructions to enable it
+- If tokensave missing: exits 1 with install hint
+- If the symbol is not found in the graph: writes a report noting no affected symbols

package/skills/bober.incident/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: bober-incident
+description: Use when responding to a production incident or system-level failure — kicks off the incident pipeline (diagnose → propose actions → deploy with gates → verify resolution → postmortem). The top-level entry that routes between bober-diagnoser, bober-deployer, and bober-postmortemer based on incident phase.
+---
+
+# Top-Level Incident Response
+
+## Overview
+
+This skill governs the **full incident lifecycle** — from the first symptom report through root-cause diagnosis, remediation execution, resolution verification, and postmortem synthesis. It is the entry point that routes between all Tier 3 sub-disciplines.
+
+The lifecycle is **phased and deterministic**. Each phase transition is driven by the output of a sub-skill (diagnoser, deployer, verifier) and gated by the incident state machine. No phase can be skipped. No resolution can bypass verification. This is the architecture that prevents "I fixed it" from meaning "I changed something and it seems better now."
+
+Key architectural invariants:
+- Every incident has a timeline (`timeline.jsonl`) from creation to resolution.
+- Every destructive action passes through a checkpoint gate before execution.
+- Every resolution requires a verifiable artifact (metric evidence or an override token with an audit trail).
+- Every resolved incident triggers a postmortem automatically.
+
+This skill does **not** replace `bober.diagnose`, `bober.deploy`, `bober.runbook`, or `bober.postmortem`. It orchestrates them.
+
+## The Iron Law
+
+```
+NO INCIDENT WITHOUT TIMELINE; NO RESOLUTION WITHOUT VERIFICATION
+```
+
+Both clauses are unconditional. They do not have exceptions for urgency, familiarity, or pipeline mode.
+
+## When to Use
+
+Use this skill when:
+- A page fires (PagerDuty, OpsGenie, or any on-call alert)
+- An SLO breach is detected (error rate, latency, availability below threshold)
+- A user-reported outage is confirmed by at least one objective signal
+- A deployment causes observable regression (rollout watchdog fires)
+- Any system-level failure requires coordinated diagnosis + remediation
+
+Do NOT use this skill for:
+- Planned maintenance (no incident, no postmortem required)
+- Feature work that happens to touch infrastructure
+- Read-only investigation with no remediation intent (use `bober.diagnose` directly)
+
+## Workflow
+
+Execute each phase in order. Do not skip phases. Phase transitions are guarded by the incident state machine.
+
+### Phase 1: Start the Incident
+
+```bash
+bober incident start "<symptom>" [--severity S1|S2|S3|S4]
+# Returns: incidentId
+```
+
+This creates the incident artifact directory (`.bober/incidents/<id>/`) with all required files. The incident is immediately in status `investigating`. The incidentId anchors all subsequent artifacts.
+
+Severity semantics (informational — does NOT affect routing):
+- **S1** — Total outage; all users affected; no workaround.
+- **S2** — Major degradation; significant user impact; partial workaround available.
+- **S3** — Partial degradation; moderate impact; workaround available.
+- **S4** — Minor issue; limited impact; no immediate user harm.
+
+### Phase 2: Diagnose
+
+Invoke the `bober-diagnoser` agent with the incidentId and symptom. The diagnoser:
+1. Queries observability tools (`obs__*__*`).
+2. Writes a `diagnoses/<diagnosisId>.json` with hypotheses + nextActions.
+3. Each nextAction declares `blastRadius: safe | risky`.
+
+The incident state machine reads `nextActions`:
+- One or more `risky` actions → transition to `remediating`.
+- No risky actions (or no actions at all) → stay at `investigating`. Operator ends the incident with `bober incident end`.
+
+### Phase 3: Remediate (if nextActions include risky steps)
+
+Invoke the `bober-deployer` agent for each risky nextAction.
+
+Each action passes through the Sprint 20 gate:
+- Gate mechanism is resolved from `bober.config.json` → `pipeline.checkpointMechanism`.
+- In `careful` mode: operator must explicitly approve each risky action before execution.
+- In `autopilot` mode: gate fires and auto-approves but STILL writes an audit trail.
+
+No action is executed without a `ChangeEntry` (with `inverse.description`) written first.
+
+After execution, verify resolution:
+```bash
+bober incident end --verified   # if external verification confirms
+bober incident end --override "Investigation concluded; no metric available"  # operator override
+```
+
+### Phase 4: Verify Resolution
+
+Resolution requires one of:
+1. `opts.verifyResult.verified === true` — metric confirmation from `verifyResolution()`.
+2. `opts.overrideToken = 'SKIP_METRIC_VERIFY: <reason>'` — operator asserts resolution with documented reason.
+
+Neither path can be skipped. The gate is enforced in `setIncidentStatus` (Sprint 22).
+
+### Phase 5: Postmortem
+
+On transition to `resolved`, Sprint 23's auto-trigger fires:
+- `generatePostmortem(projectRoot, incidentId)` synthesizes `postmortem.md` from all artifacts.
+- The postmortemPath is written to `incident.json`.
+
+The postmortem is automatic. Operators can view or regenerate:
+```bash
+bober postmortem show <incidentId>
+bober postmortem generate <incidentId>  # re-synthesize
+```
+
+## Slash Command Flow (/bober-incident)
+
+When a user invokes `/bober-incident` from Claude Code:
+
+1. **If no symptom provided in the invocation:**
+   - Prompt: "What is the symptom or alert? (e.g., '500 errors on checkout endpoint', 'p99 latency >3s on API gateway')"
+   - Wait for a clear, specific symptom description before proceeding.
+   - Do NOT proceed with a vague symptom like "something is wrong".
+
+2. **If symptom is provided:**
+   - Run: `bober incident start "<symptom>" [--severity <S1|S2|S3|S4>]`
+   - Surface the incidentId to the user immediately.
+   - Transition to diagnosis phase.
+
+3. **At each phase transition:**
+   - Announce the transition clearly: "Phase transition: investigating → remediating"
+   - Display the incidentId so the operator can track state.
+   - Surface any gate approvals required before proceeding.
+
+4. **Output format:**
+   - Use markdown headers for phases.
+   - Use code blocks for commands.
+   - Use bold for incidentId and phase names.
+   - Show `bober incident status <id>` output at each transition.
+
+Example invocation flow:
+```
+/bober-incident 500 errors spiking on checkout endpoint
+
+→ Incident created: inc-20260524-500-errors-on
+→ Phase: investigating
+→ Severity: S2 (user-visible checkout failure)
+
+[Diagnoser output: connection pool exhausted after migration 042]
+
+→ Phase transition: investigating → remediating
+→ Risky actions proposed: 2
+
+  1. Scale deployment api 3→6 replicas (risky)
+  2. Disable flag new_checkout_flow (risky)
+
+[Gate approval required for each step]
+```
+
+## Phase Transition Diagram
+
+```
+                   ┌──────────────────────────────────────────────────────┐
+                   │                                                       │
+                   ▼                                                       │
+            ┌───────────────┐                                              │
+            │ investigating │                                              │
+            └───────┬───────┘                                              │
+                    │                                                      │
+       diagnoser produces                                                  │
+       nextActions with                                                    │
+       ≥1 risky                                                            │
+                    │                                                      │
+                    ▼                                                      │
+            ┌───────────────┐                                              │
+            │  remediating  │                                              │
+            └───────┬───────┘                                              │
+                    │                                                      │
+       all proposed actions executed                                       │
+       + postcondition passed                                              │
+                    │                                                      │
+                    ▼                                                      │
+            ┌───────────────┐ ──── verifyResolution fails ─────────────────┤
+            │   monitoring  │                                              │
+            └───────┬───────┘                                              │
+                    │                                                      │
+       verifyResolution.verified=true                                      │
+       for criteria.windowMinutes                                          │
+                    │                                                      │
+                    ▼                                                      │
+            ┌───────────────┐ ──── user re-opens (reason REQUIRED) ────────┘
+            │    resolved   │
+            └───────────────┘   (auto-postmortem triggered by setIncidentStatus)
+
+At any phase: user issues `bober incident abort <id> --reason <text> [--confirm-rollback]`
+              ──────────────────────────────────────► aborted (terminal)
+```
+
+State machine constraints enforced by `transitionPhase()` in `src/incident/orchestrator.ts`:
+- `aborted` is **terminal**: no transitions out.
+- `resolved → remediating` is **forbidden** (must re-open to `investigating` first).
+- `resolved → investigating` requires an explicit `reason` (re-open path).
+- All other transitions follow the table exactly; invalid transitions throw `InvalidTransitionError`.
+
+## Red Flags - STOP and Follow Process
+
+Encountering any of these signals means the incident is being handled incorrectly. STOP the current action and follow the documented path.
+
+- **About to mark resolved without a verifyResult or overrideToken.** Resolution without evidence is conjecture. Use `--verified` or `--override <reason>` — never skip the gate.
+- **About to execute a rollback without `--confirm-rollback`.** Silent rollback is a footgun. Rollback changes system state; it must be explicit. If you want rollback, use `bober incident abort <id> --reason <text> --confirm-rollback`.
+- **About to run a risky action directly in the shell, bypassing `executeAction`.** Any command that modifies system state MUST go through the deploy gate so an inverse is recorded. No exceptions for "trivial" changes.
+- **About to batch-approve multiple risky actions in a single gate invocation.** Each risky action requires its own checkpoint approval. Per-step gates exist to prevent "approve all" disasters.
+- **About to close an incident without a timeline event.** Every phase transition and every action MUST be recorded in `timeline.jsonl`. Closing an incident with an empty timeline means the postmortem will have no evidence to synthesize.
+- **About to re-open a resolved incident without a reason.** The re-open path (`resolved → investigating`) requires an explicit reason. A reason-less re-open erases the audit trail of why the incident was re-opened.
+- **About to skip the diagnoser and go straight to remediation.** "I know what's wrong" is the most dangerous statement in incident response. Run the diagnoser first to document hypotheses.
+
+## Common Rationalizations
+
+| Rationalization | Why It's Wrong |
+|----------------|---------------|
+| "I know what's wrong — skipping diagnosis to save time." | Without documented hypotheses, the postmortem will have no root cause. Skipping diagnosis means you cannot verify the fix addressed the actual cause. |
+| "The metric is unavailable but I know it's resolved." | Use `--override <reason>` with a documented reason. This creates an audit trail. Do NOT skip the gate entirely — the `resolved` gate exists to prevent wishful resolution. |
+| "It's a tiny change — the gate is overkill." | The gate's cost is one approval. The cost of an ungated risky change to production is a potential second incident. Classify risky when in doubt. |
+| "The rollback will fix the abort side-effects automatically." | Rollback must be explicitly confirmed with `--confirm-rollback`. Silent rollback could make the situation worse. Document the abort reason first; then decide on rollback separately. |
+| "I'll write the postmortem later when I have more time." | The postmortem auto-triggers on `resolved`. If you are deferring it, you are either not marking the incident resolved or suppressing auto-generation. Both are process violations. |
+| "We don't need a severity — it's obvious." | Severity is metadata that feeds into postmortem priority, SLO budgets, and escalation decisions. Set it at `bober incident start` so downstream tooling can use it. |
+
+## Quick Reference
+
+| Question | Answer |
+|---------|--------|
+| How do I start a Severity 1 incident? | `bober incident start "<symptom>" --severity S1` |
+| How do I check the current phase? | `bober incident status <id>` |
+| How do I end an incident after external verification? | `bober incident end <id> --verified` |
+| How do I end an incident when no metric is available? | `bober incident end <id> --override "reason here"` |
+| How do I abort without rolling back? | `bober incident abort <id> --reason "<text>"` |
+| How do I abort AND roll back? | `bober incident abort <id> --reason "<text>" --confirm-rollback` |
+| How do I re-open a resolved incident? | `bober incident start "<symptom>"` (new incident) OR `transitionPhase(..., 'investigating', { reason })` programmatically |
+| Where are the artifacts? | `.bober/incidents/<incidentId>/` |
+| What gates a risky action? | `resolveRiskyActionMechanismName()` → disk/cli/pr/noop per `bober.config.json` |
+| When is the postmortem generated? | Automatically when `setIncidentStatus(_, _, 'resolved', ...)` is called |
+
+## Related Skills
+
+| Skill | Use when |
+|-------|---------|
+| [`bober.diagnose`](../bober.diagnose/SKILL.md) | Running the 4-phase root-cause investigation. Invoked by `/bober-incident` after `start`. |
+| [`bober.deploy`](../bober.deploy/SKILL.md) | Executing a remediation action with gate discipline. Invoked for each risky nextAction. |
+| [`bober.runbook`](../bober.runbook/SKILL.md) | Executing a known remediation procedure step-by-step. Runbook steps delegate to `bober.deploy` for risky steps. |
+| [`bober.postmortem`](../bober.postmortem/SKILL.md) | Synthesizing the incident postmortem after resolution. Auto-triggered; also available manually via `bober postmortem generate <id>`. |

package/skills/bober.onboard/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: bober.onboard
+description: Generate onboarding documentation from the code graph — architecture overview, hotspots, knowledge gaps, and communities. Writes 5 markdown files to .bober/onboarding/.
+handoffs:
+  - label: "Analyse Impact"
+    command: /bober-impact
+    prompt: "Analyse the impact radius of a hotspot symbol"
+  - label: "Plan Feature"
+    command: /bober-plan
+    prompt: "Plan a feature using onboarding context"
+---
+
+# bober.onboard — Onboarding Documentation Skill
+
+You are running the **bober.onboard** skill. Your job is to generate a complete set of onboarding documents for this codebase using the code graph.
+
+## What This Skill Produces
+
+Five markdown files in `.bober/onboarding/`:
+
+1. **README.md** — entry point with links to all other documents
+2. **architecture-overview.md** — public API per module, sorted alphabetically
+3. **hotspots.md** — high-complexity symbols worth reviewing (table with score + reason)
+4. **knowledge-gaps.md** — potentially unused (dead code) + public APIs without internal callers
+5. **communities.md** — module groupings by community
+
+## Prerequisites
+
+- `graph.enabled: true` in `bober.config.json`
+- `tokensave` >= 6.0.0-beta.1 installed
+- Graph must be initialised (`agent-bober graph init`)
+
+## Running via CLI
+
+```bash
+agent-bober onboard
+```
+
+This command:
+1. Starts a short-lived tokensave engine
+2. Queries the graph for status, hotspots, dead code, circular deps, module APIs, and file inventory
+3. Passes results to the OnboardingComposer renderer
+4. Writes all 5 files to `.bober/onboarding/`
+5. Prints a summary table with file paths and sizes
+
+Expected output:
+```
+Starting graph engine...
+Querying code graph...
+Writing artifacts to .bober/onboarding/...
+
+Onboarding artifacts written:
+
+  .bober/onboarding/README.md                     <size> bytes
+  .bober/onboarding/architecture-overview.md      <size> bytes
+  .bober/onboarding/hotspots.md                   <size> bytes
+  .bober/onboarding/knowledge-gaps.md             <size> bytes
+  .bober/onboarding/communities.md                <size> bytes
+
+5 files written (<total> bytes total)
+```
+
+## Running via MCP Tools (Alternative)
+
+You can also produce equivalent onboarding content directly using the MCP tools:
+
+1. Get architecture overview: `get_architecture_overview`
+2. Find hotspots: `semantic_search_nodes` with query `"hotspots high complexity"`
+3. Find dead code: `semantic_search_nodes` with query `"dead code unused symbols"`
+4. Find communities: `list_communities` (if available) or `get_architecture_overview`
+
+Format the results using the same structure as the generated documents and write to `.bober/onboarding/`.
+
+## Re-running
+
+The command is safe to re-run. Files with the generation marker are updated in-place (preserving any content you wrote above the marker). Files without the marker are refused to prevent overwriting manual edits.
+
+To force a fresh generation, delete the files in `.bober/onboarding/` and re-run.
+
+## Error Handling
+
+- If graph.enabled=false: exits 1 with instructions to enable it
+- If tokensave missing: exits 1 with install hint
+- If a file lacks the generation marker: exits with an error explaining which file needs attention

package/skills/bober.plan/SKILL.md

@@ -152,6 +152,16 @@ After receiving the user's answers, generate a complete PlanSpec. Follow the sch
 7. **Non-functional requirements:** Performance, security, accessibility, reliability considerations
 8. **Tech notes:** Integration points, data model overview, security considerations
 
+<HARD-GATE>
+Do NOT write any .bober/contracts/*.json file until one of the following has happened:
+
+1. INTERACTIVE protocol — the user has explicitly approved the assumptions and outOfScope sections above. Record approval as a resolvedClarifications entry with questionId='gate-design-approval' and the user's verbatim approval in the answer field.
+
+2. AUTONOMOUS protocol — every assumption in the spec is backed by cited evidence (minimum: a file path; preferred: file:line). Record self-approval as resolvedClarifications entry with questionId='gate-design-approval', answer='Autonomous self-approval', resolvedBy='planner', and metadata.approvalEvidence field listing the cited file paths.
+
+Violating this gate produces orphan contracts that diverge from the spec. Discovered violations result in contracts being deleted and spec status reverted to 'needs-clarification'.
+</HARD-GATE>
+
 ## Step 6: Decompose into Sprint Contracts
 
 Decompose the PlanSpec into ordered sprints. This is the most critical step.
@@ -210,6 +220,47 @@ Save all artifacts to the `.bober/` directory:
    {"event":"plan-created","specId":"...","title":"...","sprintCount":N,"timestamp":"..."}
    ```
 
+## Step 7.5: Decide — Ready or Needs Clarification?
+
+After self-answering the clarifying questions in Step 4, score the remaining ambiguity 0-10 using this rubric:
+
+| Score | Meaning |
+|-------|---------|
+| 0-2   | Fully specified. Every behavior, edge case, error path is concrete. |
+| 3-4   | Mostly specified. Small judgment calls remain (library choice, exact wording). |
+| 5-6   | Some load-bearing decisions deferred to the generator, but codebase has clear patterns. |
+| 7-8   | Significant ambiguity. The generator would have to make architectural guesses. |
+| 9-10  | Fundamental specification gaps. Sprint cannot be reliably implemented. |
+
+**Decision:**
+
+- If score < 7 AND no questions are unresolved → set `status: "draft"` and proceed to Step 8 (sprint contracts get saved).
+- If score >= 7 OR any question remains unresolved → set `status: "needs-clarification"`, populate `clarificationQuestions`, populate `resolvedClarifications` for any you self-answered, and STOP. Do not write sprint contracts. Save the spec, surface the open questions to the user, and exit.
+
+**When clarification is needed, surface it like this:**
+
+```
+⚠ Plan needs clarification before sprints can run.
+Spec: <title>
+Ambiguity score: <N>/10
+
+Open questions:
+
+  Q1 [scope]: <question>
+    A) <option>
+    B) <option>
+    💡 Suggested: <recommendation if available>
+
+  Q2 [data-model]: <question>
+
+Resolve via either:
+  /bober-plan answer <specId> Q1 "<your answer>"     (one-shot per question)
+  npx agent-bober plan answer <specId>               (interactive walkthrough)
+  Or edit .bober/specs/<specId>.json directly and flip status to "ready".
+```
+
+The user resolves the questions via the `bober plan answer` CLI command (or by editing the spec file directly). Once all questions are answered, the runtime flips status to `ready` and the next `/bober-sprint` or `/bober-run` invocation can proceed.
+
 ## Step 8: Output Summary
 
 Present a clean, readable summary to the user:

package/skills/bober.plan/references/spec-schema.md

@@ -24,10 +24,34 @@ PlanSpec files are stored at: `.bober/specs/<specId>.json`
   "description": "string (required, 2-3 sentences)",
   "mode": "string (required, one of: greenfield, brownfield)",
   "preset": "string (optional, e.g.: nextjs, react-vite, solidity, anchor, api-node, python-api)",
-  "status": "string (required, one of: planned, in-progress, completed, archived)",
+  "status": "string (required, one of: draft, needs-clarification, ready, in-progress, completed, abandoned)",
+
+  "ambiguityScore": "number (optional, 0-10) — planner's self-rated ambiguity. >= 7 forces status='needs-clarification'.",
+
+  "clarificationQuestions": [
+    {
+      "questionId": "string (required, e.g. 'Q1')",
+      "category": "string (required, one of: scope | user-personas | data-model | tech-constraints | design-ux | integrations | non-functional | error-handling | integration-risk | pattern-conflict | regression-risk | other)",
+      "question": "string (required, ends in '?')",
+      "options": [
+        { "label": "string (e.g. 'A')", "description": "string" }
+      ],
+      "recommendation": "string (optional, planner's suggested answer based on codebase evidence)",
+      "ambiguityWeight": "number (optional, 0-10, how much this question contributes to overall ambiguity)"
+    }
+  ],
+
+  "resolvedClarifications": [
+    {
+      "questionId": "string (required, matches a clarificationQuestions entry)",
+      "answer": "string (required, free-form)",
+      "resolvedAt": "string (required, ISO-8601)",
+      "resolvedBy": "string (required, one of: user | planner)"
+    }
+  ],
 
   "assumptions": [
-    "string — each assumption the planner is making"
+    "string — each assumption the planner is making, ideally with codebase evidence"
   ],
 
   "outOfScope": [
@@ -90,7 +114,10 @@ PlanSpec files are stored at: `.bober/specs/<specId>.json`
 | `description` | 2-3 sentence summary of the feature and its user value. |
 | `mode` | Must match the `project.mode` in `bober.config.json` (`greenfield` or `brownfield`). |
 | `preset` | Must match the `project.preset` in `bober.config.json`, if set (e.g., `nextjs`, `solidity`, `anchor`). |
-| `status` | Lifecycle state: `planned` (not started), `in-progress` (sprints running), `completed` (all sprints done), `archived` (abandoned or superseded). |
+| `status` | Lifecycle state. `draft`: planner emitted a complete plan, no sprints run yet. `needs-clarification`: planner refused to fully decompose; user must answer the open `clarificationQuestions` before sprints can run. `ready`: clarifications resolved, pipeline may proceed. `in-progress`: at least one sprint has started. `completed`: all sprints done. `abandoned`: planner or user dropped this spec. |
+| `ambiguityScore` | Planner's self-rating 0-10. If `>= 7`, the planner MUST set `status: "needs-clarification"` and emit at least one `clarificationQuestions` entry — the pipeline will refuse to run sprints from such a spec. |
+| `clarificationQuestions` | Open questions awaiting user answers. Each unresolved entry blocks sprint execution. |
+| `resolvedClarifications` | Question/answer history (both autonomous self-answers and user inputs via `bober plan answer`). |
 
 ### Features Array
 
@@ -155,7 +182,7 @@ Bad criteria:
   "description": "A complete user authentication system supporting email/password registration and login, with session management and protected routes. This enables the application to identify users and restrict access to authorized content.",
   "mode": "greenfield",
   "preset": "react-vite",
-  "status": "planned",
+  "status": "draft",
   "assumptions": [
     "The application does not currently have any authentication system",
     "PostgreSQL is the database, as configured in the project",