ultra-builder-pro-cli 0.9.0 → 0.11.0

package/skills/ultra-verify/SKILL.md

@@ -1,92 +1,52 @@
 ---
 name: ultra-verify
-description: Run independent two-model verification with the current host as primary and a read-only Codex advisor, then verify and synthesize the evidence.
+description: Run independent two-model verification with the current host as primary and a read-only external advisor, then verify and synthesize both evidence sets. Use only when the user explicitly requests cross-model verification.
 ---
 
-# Ultra Verify — Independent Two-Model Verification
+# Run independent cross-model verification
 
-Claude Code remains primary. It writes the first independent analysis, verifies consequential
-claims, and owns the final answer. Codex is an untrusted read-only advisor. Use this workflow only
-when the user explicitly asks for cross-model verification.
+Claude Code writes the first analysis, verifies consequential claims, and owns the
+final answer. Codex is an untrusted read-only advisor.
 
 ## Modes
 
-- `decision <question>`: architecture or product decision.
-- `diagnose <symptoms>`: independent root-cause hypotheses.
-- `audit <scope>`: evidence-backed findings.
-- `estimate <task>`: estimates with explicit assumptions.
-
-## Preconditions
-
-1. Confirm `codex --version` plus authentication.
-2. Define the exact workspace, question, evidence standard, and response shape.
-3. Do not send secrets, unrelated files, or an unbounded home directory.
-4. Track four steps in the current host plan: primary analysis, advisor launch, completion wait,
-   and verified synthesis.
-
-## 1. Create the session and write the primary view
-
-```bash
-SESSION_ID="$(date +%Y%m%d-%H%M%S)-verify-<mode>"
-SESSION_PATH=".ultra/collab/${SESSION_ID}"
-mkdir -p "${SESSION_PATH}"
-```
-
-Write Claude Code's evidence-backed analysis to `${SESSION_PATH}/claude-analysis.md` before
-reading the advisor output. Record the mode, checkout, scope, and evidence boundary.
-
-## 2. Launch the advisor read-only
-
-Give the advisor the bounded raw question and evidence without the primary conclusion.
-
-```bash
-codex exec -s read-only \
-  -o "${SESSION_PATH}/codex-output.md" \
-  "<bounded prompt>" \
-  2> "${SESSION_PATH}/codex-error.log"
-```
-
-Never enable write-capable automation, danger-full-access, or permission bypass for the advisor.
-
-## 3. Wait for completed output
-
-Run the bundled waiter in an asynchronous or yielded shell session and poll it at bounded
-intervals; never hold one blocking tool call longer than 60 seconds.
-
-```bash
-python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-verify/scripts/verify_wait.py" \
-  "${SESSION_PATH}" --timeout 1200
-```
-
-The waiter reports the advisor as `complete`, `failed`, `empty`, or `pending`. Read the output only
-after its status is `complete` and the file is non-empty. Preserve the error log when it fails.
-
-## 4. Verify and synthesize
-
-Compare `claude-analysis.md` with `codex-output.md`:
-
-1. Verify claims against the current checkout, tests, runtime, or primary documentation.
-2. Separate verified agreement, useful dissent, and unsupported assertions.
-3. Explain scope, version, and assumption differences before judging the result.
-4. Write `synthesis.md` and `metadata.json`, then return one Claude Code-owned conclusion.
-
-Use `references/confidence-system.md` for evidence-based confidence and
-`references/cross-verify-modes.md` for mode-specific expectations. Model agreement never overrides
-failing tests or authoritative runtime evidence.
-
-## Degraded operation
-
-- Advisor failure: return the primary analysis with an explicit single-source warning.
-- Never block the underlying user task solely because the advisor is absent, unauthenticated, or
-  slow.
-
-## Session files
-
-```text
-.ultra/collab/<SESSION_ID>/
-  claude-analysis.md
-  codex-output.md
-  codex-error.log
-  metadata.json
-  synthesis.md
-```
+- `decision`: one consequential architecture or product choice;
+- `diagnose`: independent root-cause hypotheses;
+- `audit`: evidence-backed findings over a bounded scope;
+- `estimate`: an estimate with explicit assumptions and uncertainty.
+
+## Workflow
+
+1. Confirm the advisor CLI and authentication. Define the exact workspace, question,
+   evidence standard, and response shape. Exclude secrets and unrelated files.
+2. Create `.ultra/collab/<session-id>/` and write the primary host's evidence-backed
+   analysis to `claude-analysis.md` before reading advisor output.
+3. Launch Codex with the raw bounded question and evidence in a read-only sandbox. Do
+   not include the primary conclusion when independence matters:
+
+   ```bash
+   codex exec -s read-only \
+     -a never \
+     --ephemeral \
+     --ignore-user-config \
+     --ignore-rules \
+     -o "${SESSION_PATH}/codex-output.md" \
+     "<bounded prompt>" \
+     2> "${SESSION_PATH}/codex-error.log"
+   ```
+4. Run `scripts/verify_wait.py` resolved relative to this skill directory. Use a
+   yielded or asynchronous shell session and poll at bounded intervals; do not hold a
+   blocking tool call longer than one minute.
+5. Read advisor output only after the waiter reports a complete, non-empty file.
+6. Verify both analyses against the current checkout, tests, runtime, or primary
+   documentation. Explain scope, version, evidence, and assumption differences before
+   judging disagreement.
+7. Write session metadata and a synthesis artifact, then return one host-owned
+   conclusion.
+
+Read `references/cross-verify-modes.md` for mode-specific evidence and
+`references/confidence-system.md` when confidence language is useful. Model agreement
+never overrides failing tests or authoritative runtime evidence.
+
+Advisor failure degrades to the primary analysis with a single-source warning. It does
+not block the user's underlying task.

package/skills/ultra-verify/evals/evals.json

@@ -2,47 +2,44 @@
   "skill_name": "ultra-verify",
   "evals": [
     {
-      "id": 1,
-      "prompt": "/ultra-verify decision 'Should we use PostgreSQL or MongoDB for our new microservice?'",
-      "expected_output": "Claude writes its analysis first, launches Codex read-only, verifies both analyses, and returns one evidence-backed synthesis",
+      "id": "explicit-decision",
+      "prompt": "Run independent cross-model verification on the database choice, with the current host writing its view before the advisor.",
+      "should_trigger": true,
       "assertions": [
-        "Claude writes its own analysis before reading advisor output",
-        "Launches Codex with a read-only sandbox",
-        "Creates a session directory under .ultra/collab/",
+        "Writes the primary analysis before reading advisor output",
+        "Launches the advisor in a read-only sandbox",
+        "Uses a bounded session directory and completion waiter",
         "Verifies consequential claims against authoritative evidence",
-        "Separates verified agreement, useful dissent, and unsupported assertions"
+        "Returns one host-owned synthesis"
       ]
     },
     {
-      "id": 2,
-      "prompt": "/ultra-verify diagnose 'API returns 500 intermittently under load'",
-      "expected_output": "Independent hypotheses are reconciled through discriminating checks and evidence strength",
+      "id": "explicit-diagnosis",
+      "prompt": "Use two independent models to diagnose the intermittent 500 response and reconcile their hypotheses with discriminating checks.",
+      "should_trigger": true,
       "assertions": [
-        "Both analyses provide ranked hypotheses",
-        "Duplicate hypotheses are merged by root cause",
-        "Each retained hypothesis includes a verification step",
-        "Investigation order follows evidence strength and verification cost"
+        "Keeps both initial hypotheses independent",
+        "Deduplicates by root cause after both outputs complete",
+        "Orders verification by evidence and diagnostic value",
+        "Does not decide by model vote"
       ]
     },
     {
-      "id": 3,
-      "prompt": "/ultra-verify audit",
-      "expected_output": "Findings are deduplicated and verified against the current checkout without vote-based severity",
+      "id": "ordinary-analysis-negative",
+      "prompt": "Should this service use PostgreSQL or MongoDB?",
+      "should_trigger": false,
       "assertions": [
-        "Uses the same scope and severity model for both analyses",
-        "Verifies every reported location",
-        "Retains uniquely reported findings when source evidence confirms them",
-        "Severity does not depend on model agreement"
+        "Answers with the ordinary analysis workflow",
+        "Does not launch an external advisor without explicit cross-model intent"
       ]
     },
     {
-      "id": 4,
-      "prompt": "/ultra-verify estimate 'Implement OAuth2 login with two providers'",
-      "expected_output": "Two estimates are reconciled by scope, assumptions, dependencies, and risk",
+      "id": "ordinary-review-negative",
+      "prompt": "Review these changes before I commit.",
+      "should_trigger": false,
       "assertions": [
-        "Both analyses include work breakdowns and assumptions",
-        "Large differences are explained rather than averaged mechanically",
-        "Final range is supported by the reconciled work breakdown"
+        "Uses the standard review workflow",
+        "Does not substitute cross-model verification for native review"
       ]
     }
   ]

package/spec/cli-protocol.md

@@ -105,6 +105,9 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `change.get`              | `change get`                | 9     | any     |
 | `change.list`             | `change list`               | 9     | any     |
 | `change.context`          | `change context`            | 9     | mcp     |
+| `change.breadcrumb`       | `change breadcrumb`         | 10    | any     |
+| `change.learning_propose` | `change learning-propose`   | 10    | mcp     |
+| `change.learning_resolve` | `change learning-resolve`   | 10    | mcp     |
 | `change.converge`         | `change converge`           | 9     | mcp     |
 | `change.archive`          | `change archive`            | 9     | mcp     |
 | `system.doctor`           | `system doctor`             | 9     | mcp     |

package/spec/mcp-tools.yaml

@@ -3,7 +3,7 @@
 # Validated by spec/schemas/mcp-tools.schema.json (run `npm run test:spec`).
 # Trace: PLAN §7.3, decisions D12 / D29 / D31-D34.
 
-version: '1.0'
+version: '1.1'
 
 info:
   title: Ultra Builder Pro MCP tool contracts
@@ -398,6 +398,8 @@ tools:
             - change_blocked
             - change_converged
             - change_archived
+            - spec_learning_proposed
+            - spec_learning_resolved
         payload: { type: object }
     output_schema:
       type: object
@@ -759,7 +761,7 @@ tools:
 
   - name: change.get
     family: change
-    description: Read one continuous change unit from authoritative state.
+    description: Read one continuous change unit and its specification-learning candidates from authoritative state.
     phase: '9'
     readonly: true
     input_schema:
@@ -805,8 +807,8 @@ tools:
 
   - name: change.context
     family: change
-    description: Compile an inspectable task context manifest from Ultra state and external provider metadata references.
-    phase: '9'
+    description: Compile a role-scoped Context Spine manifest with readiness, budget, execution seam, and next-action evidence.
+    phase: '10'
     writer_role: mcp
     input_schema:
       type: object
@@ -815,7 +817,37 @@ tools:
       properties:
         id: { type: string }
         task_id: { type: string }
+        role: { type: string, enum: [plan, implement, check, review] }
+        gate: { type: string, enum: [alignment, planning, implementation, verification, review, convergence, recovery] }
+        next_action: { type: string, minLength: 3 }
         spec_refs: { type: array, items: { type: object } }
+        context_refs:
+          type: array
+          maxItems: 64
+          items:
+            type: object
+            required: [ref, reason]
+            additionalProperties: false
+            properties:
+              ref: { type: string, minLength: 1 }
+              kind: { type: string, enum: [spec, source, test, docs, external], default: source }
+              reason: { type: string, minLength: 3 }
+              required: { type: boolean, default: true }
+              digest: { type: string, pattern: '^[0-9a-f]{64}$' }
+        budget:
+          type: object
+          additionalProperties: false
+          properties:
+            max_tokens: { type: integer, minimum: 1, default: 12000 }
+            max_files: { type: integer, minimum: 1, default: 12 }
+        execution_contract:
+          type: object
+          additionalProperties: false
+          properties:
+            slice_kind: { type: string, enum: [tracer_bullet, expand_contract, integration_checkpoint], default: tracer_bullet }
+            public_seam: { type: string }
+            verification_command: { type: string }
+            context_budget_percent: { type: integer, minimum: 1, maximum: 100, default: 40 }
         allowed_paths: { type: array, items: { type: string } }
         provider_refs:
           type: object
@@ -852,12 +884,96 @@ tools:
         manifest_hash: { type: string, pattern: '^[0-9a-f]{64}$' }
         manifest: { type: object }
     errors:
+      - { code: VALIDATION_ERROR, description: 'context role, gate, references, budget, or execution contract is invalid' }
       - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
       - { code: CHANGE_TERMINAL, description: 'terminal change cannot compile a new context' }
+      - { code: TASK_NOT_FOUND, description: 'task id is not linked to the change' }
       - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
     cli_subcommand: change context
     emits_events: [context_updated]
 
+  - name: change.breadcrumb
+    family: change
+    description: Read the compact DB-derived Context Spine position, readiness, and single recommended next action.
+    phase: '10'
+    readonly: true
+    writer_role: any
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        id: { type: string }
+    output_schema:
+      type: object
+      required: [breadcrumb]
+      additionalProperties: false
+      properties:
+        breadcrumb: { type: object }
+    errors:
+      - { code: CHANGE_NOT_FOUND, description: 'explicit change id does not exist' }
+      - { code: STATE_DB_ERROR, description: 'runtime state could not be read' }
+    cli_subcommand: change breadcrumb
+    emits_events: []
+
+  - name: change.learning_propose
+    family: change
+    description: Propose one stable implementation discovery for approval-gated baseline specification convergence.
+    phase: '10'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [change_id, target_ref, summary]
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        change_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        task_id: { type: string }
+        target_ref: { type: string, minLength: 1 }
+        summary: { type: string, minLength: 3 }
+        evidence: { type: array, items: { type: string, minLength: 1 } }
+    output_schema:
+      type: object
+      required: [candidate]
+      additionalProperties: false
+      properties:
+        candidate: { type: object }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'candidate id, target, summary, or evidence is invalid' }
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'learning must resolve before convergence' }
+      - { code: TASK_NOT_FOUND, description: 'task is not linked to the change' }
+      - { code: DUPLICATE_LEARNING_ID, description: 'candidate id already exists' }
+    cli_subcommand: change learning-propose
+    emits_events: [spec_learning_proposed]
+
+  - name: change.learning_resolve
+    family: change
+    description: Approve, reject, or mark applied one specification-learning candidate through a guarded state transition.
+    phase: '10'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [change_id, candidate_id, decision]
+      additionalProperties: false
+      properties:
+        change_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        candidate_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        decision: { type: string, enum: [approve, reject, apply] }
+        resolution: { type: string }
+    output_schema:
+      type: object
+      required: [candidate]
+      additionalProperties: false
+      properties:
+        candidate: { type: object }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'decision or required resolution is invalid' }
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+      - { code: LEARNING_NOT_FOUND, description: 'candidate id does not exist for the change' }
+      - { code: ILLEGAL_LEARNING_TRANSITION, description: 'candidate state transition is not permitted' }
+    cli_subcommand: change learning-resolve
+    emits_events: [spec_learning_resolved]
+
   - name: change.converge
     family: change
     description: Deterministically verify task, spec, test, documentation, review, context, and incident diagnosis structure before closure.
@@ -880,6 +996,19 @@ tools:
               category: { type: string, enum: [diagnosis, diff, tests, spec, docs, review] }
               status: { type: string, enum: [pass, fail, not_applicable] }
               evidence: { type: string, minLength: 3 }
+              axis: { type: string, enum: [spec_fidelity, engineering_standards] }
+              seam: { type: string, minLength: 3 }
+              signal:
+                type: object
+                additionalProperties: false
+                required: [command, expected_red, observed_red, observed_green, deterministic]
+                properties:
+                  command: { type: string, minLength: 3 }
+                  expected_red: { type: string, minLength: 3 }
+                  observed_red: { type: boolean }
+                  observed_green: { type: boolean }
+                  deterministic: { type: boolean }
+                  duration_ms: { type: number, minimum: 0 }
     output_schema:
       type: object
       required: [ready, status, blockers]

package/spec/schemas/command-manifest.schema.json

@@ -1,47 +1,29 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ultra-builder-pro.dev/spec/command-manifest.schema.json",
-  "title": "Command manifest (frontmatter)",
-  "description": "YAML frontmatter contract for commands/ultra-*.md thin-shell files. Phase 3 薄壳化: 命令文件 ≤ 80 行正文，真实 workflow 放 skills/<name>/SKILL.md。additionalProperties=false (PLAN R19).",
+  "title": "Ultra command launcher frontmatter",
+  "description": "Portable source contract for a thin command launcher. Runtime metadata and workflow procedure belong outside the command file.",
   "type": "object",
-  "required": ["description"],
+  "required": ["description", "workflow-ref"],
   "additionalProperties": false,
   "properties": {
     "description": {
       "type": "string",
       "minLength": 10,
-      "description": "一句话触发描述; 给 runtime 的 skill router / 用户命令列表使用"
+      "maxLength": 240,
+      "description": "Concise user-visible action description."
     },
     "argument-hint": {
       "oneOf": [
         { "type": "string" },
         { "type": "array", "items": { "type": "string" }, "minItems": 1 }
       ],
-      "description": "Claude Code convention: hint shown after slash-command name. Both `argument-hint: [foo]` (YAML array form) and `argument-hint: \"[foo]\"` (string form) are accepted."
-    },
-    "allowed-tools": {
-      "type": "string",
-      "description": "Claude Code convention: comma-separated tool allowlist"
-    },
-    "model": {
-      "type": "string",
-      "enum": ["haiku", "sonnet", "opus"],
-      "description": "Claude Code convention: model routing hint"
+      "description": "Optional host launcher hint; it does not define argument semantics."
     },
     "workflow-ref": {
       "type": "string",
       "pattern": "^@skills/[a-z][a-z0-9\\-]*/SKILL\\.md$",
-      "description": "Phase 3 薄壳关键字段: 指向 skills/<name>/SKILL.md; 存在即表示该命令已迁为薄壳"
-    },
-    "mcp_tools_required": {
-      "type": "array",
-      "items": { "type": "string", "pattern": "^[a-z]+\\.[a-z_]+$" },
-      "uniqueItems": true,
-      "description": "Phase 3+: 命令运行时会调用的 MCP tool 名单; 无 MCP 时走 cli_fallback"
-    },
-    "cli_fallback": {
-      "type": "string",
-      "description": "Phase 3+: MCP 不可达时回退的 ultra-tools 子命令 (e.g. 'init' -> 'ultra-tools init')"
+      "description": "The single Skill that owns this workflow."
     }
   }
 }

package/spec/schemas/skill-manifest.schema.json

@@ -1,94 +1,24 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ultra-builder-pro.dev/spec/skill-manifest.schema.json",
-  "title": "Skill manifest (frontmatter)",
-  "description": "YAML frontmatter contract for skills/*/SKILL.md. Strict additionalProperties=false: any new field must be added here AND propagated through validate-skills.cjs (PLAN R19 single-source rule).",
+  "title": "Portable Agent Skill frontmatter",
+  "description": "Canonical source contract for skills/*/SKILL.md. Host invocation policy, UI metadata, runtime dependencies, and command hints belong in adapters or host-native metadata, not model instructions.",
   "type": "object",
   "required": ["name", "description"],
   "additionalProperties": false,
   "properties": {
     "name": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9\\-]*$",
-      "description": "kebab-case slug; matches the directory name"
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "Portable Agent Skills name; must match the parent directory."
     },
     "description": {
       "type": "string",
       "minLength": 10,
-      "description": "human-readable trigger sentence consumed by the runtime's skill router"
-    },
-    "runtime": {
-      "oneOf": [
-        { "type": "string", "enum": ["claude", "opencode", "codex", "kimi", "all"] },
-        {
-          "type": "array",
-          "items": { "type": "string", "enum": ["claude", "opencode", "codex", "kimi"] },
-          "minItems": 1,
-          "uniqueItems": true
-        }
-      ],
-      "description": "v4.5 — which runtime(s) this skill targets. Defaults to 'all' when absent (Phase 4 adapter installs everywhere)."
-    },
-    "mcp_tools_required": {
-      "type": "array",
-      "items": { "type": "string", "pattern": "^[a-z]+\\.[a-z_]+$" },
-      "uniqueItems": true,
-      "description": "v4.5 — MCP tool names this skill calls; Phase 3+ generators verify availability"
-    },
-    "cli_fallback": {
-      "type": "string",
-      "description": "v4.5 — ultra-tools subcommand to fall back to when MCP unreachable"
-    },
-    "complexity_hint": {
-      "type": "string",
-      "enum": ["haiku", "sonnet", "opus"],
-      "description": "v4.5 — model routing hint (Phase 7+)"
-    },
-    "argument-hint": {
-      "type": "string",
-      "description": "Claude Code convention: hint shown after slash-command name"
-    },
-    "allowed-tools": {
-      "type": "string",
-      "description": "Claude Code convention: comma-separated tool allowlist"
-    },
-    "user-invocable": {
-      "type": "boolean",
-      "description": "Claude Code convention: can the user call this via slash command"
-    },
-    "disable-model-invocation": {
-      "type": "boolean",
-      "description": "Claude Code convention: skill is not auto-invoked by the model"
-    },
-    "context": {
-      "type": "string",
-      "enum": ["fork", "main"],
-      "description": "Claude Code convention: 'fork' isolates skill output from main conversation"
-    },
-    "license": {
-      "type": "string",
-      "description": "third-party skill license (e.g. MIT)"
-    },
-    "metadata": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "author":  { "type": "string" },
-        "version": { "type": "string" }
-      },
-      "description": "third-party metadata block (vercel skills, etc.)"
-    }
-  },
-  "allOf": [
-    {
-      "if": { "required": ["user-invocable"], "properties": { "user-invocable": { "const": true } } },
-      "then": {
-        "not": {
-          "required": ["disable-model-invocation"],
-          "properties": { "disable-model-invocation": { "const": true } }
-        },
-        "errorMessage": "user-invocable=true cannot coexist with disable-model-invocation=true"
-      }
+      "maxLength": 1024,
+      "description": "Concise discovery metadata that states both what the skill does and when to use it."
     }
-  ]
+  }
 }

package/spec/schemas/state-db.sql

@@ -197,11 +197,40 @@ CREATE TABLE IF NOT EXISTS context_snapshots (
   provider_refs_json TEXT NOT NULL DEFAULT '{}',
   manifest_path      TEXT NOT NULL,
   manifest_hash      TEXT NOT NULL,
+  role               TEXT NOT NULL DEFAULT 'plan'
+                       CHECK (role IN ('plan', 'implement', 'check', 'review')),
+  gate               TEXT NOT NULL DEFAULT 'alignment'
+                       CHECK (gate IN ('alignment', 'planning', 'implementation', 'verification', 'review', 'convergence', 'recovery')),
+  next_action        TEXT NOT NULL DEFAULT 'Resolve the next Ultra workflow action.',
+  readiness          TEXT NOT NULL DEFAULT 'ready'
+                       CHECK (readiness IN ('ready', 'blocked')),
+  blockers_json      TEXT NOT NULL DEFAULT '[]',
+  context_json       TEXT NOT NULL DEFAULT '{}',
+  token_estimate     INTEGER NOT NULL DEFAULT 0 CHECK (token_estimate >= 0),
+  token_budget       INTEGER NOT NULL DEFAULT 12000 CHECK (token_budget > 0),
   created_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
 );
 
 CREATE INDEX IF NOT EXISTS context_snapshots_change ON context_snapshots(change_id, created_at);
 
+CREATE TABLE IF NOT EXISTS spec_learning_candidates (
+  id            TEXT PRIMARY KEY,
+  change_id     TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  task_id       TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  target_ref    TEXT NOT NULL,
+  summary       TEXT NOT NULL,
+  evidence_json TEXT NOT NULL DEFAULT '[]',
+  status        TEXT NOT NULL DEFAULT 'proposed'
+                  CHECK (status IN ('proposed', 'approved', 'rejected', 'applied')),
+  resolution    TEXT,
+  proposed_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  resolved_at   TEXT,
+  applied_at    TEXT
+);
+
+CREATE INDEX IF NOT EXISTS spec_learning_change
+  ON spec_learning_candidates(change_id, status, proposed_at);
+
 CREATE TABLE IF NOT EXISTS trace_links (
   id          INTEGER PRIMARY KEY AUTOINCREMENT,
   change_id   TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
@@ -274,3 +303,5 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('9.0', 'Continuous change units, context snapshots, trace links, incidents, projection outbox, and durable consumers');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('9.1', 'Kimi runtime support in durable events and sessions');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('10.0', 'Role-scoped context snapshots, deterministic breadcrumbs, and approval-gated specification learning');