ultra-builder-pro-cli 0.19.1 → 0.21.1

package/.ultra-template/docs/research/README.md

@@ -3,12 +3,33 @@
 Store durable research evidence here only when it is too detailed for the baseline
 specification. Baseline decisions and accepted behavior remain in `.ultra/specs/`.
 
-## Required step reports
+## Initialization modes
 
-Every selected `ultra-research` step writes one immutable report at
-`.ultra/docs/research/<workflow-id>/<step-id>.md`. Full and adoption research therefore
-produce seventeen reports. The shared specifications are updated during research but
-do not replace these per-step evidence records.
+`ultra-init` creates the scaffold and records classification; it never runs research
+or approves a baseline. A later explicit `ultra-research` invocation handles:
+
+- greenfield baseline evidence with adaptive product and architecture coverage;
+- brownfield adoption of observed product, runtime, quality, operations, known
+  failures, and documentation drift;
+- migrated or damaged authority only after backup-first `ultra-doctor` recovery,
+  followed by evidence-backed brownfield adoption.
+
+Blank templates are never baseline evidence. Existing authority is preserved rather
+than replaced by this scaffold.
+
+## Included-area reports
+
+Every included research area that executes, verifies, or reuses evidence writes one
+immutable report at `.ultra/docs/research/<workflow-id>/<step-id>.md`. The accepted
+coverage determines the report set; `full` and `adoption` describe baseline purpose,
+not a requirement to execute all seventeen catalog areas. Omitted areas create no
+report. The shared specifications are updated during research but do not replace these
+per-area evidence records.
+
+This directory is only for baseline establishment and adoption. Active Change research
+writes below
+`.ultra/changes/active/<change-id>/research/<workflow-id>/<step-id>.md`; it updates the
+Change overlay and never edits accepted baseline specifications.
 
 ## Report contract
 

package/.ultra-template/specs/discovery.md

@@ -67,7 +67,7 @@ decision. Include source date, segment, geography, and assumptions when applicab
 
 ## Baseline Gaps
 
-Reference authoritative gap ids from `.ultra/state.db`.
+Reference authoritative gap ids from `.ultra/.runtime/state.db`.
 
 | Gap id | Category | Status | Evidence | Owner |
 |---|---|---|---|---|

package/.ultra-template/tasks/tasks.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "4.5",
   "generated_at": "1970-01-01T00:00:00.000Z",
-  "source": ".ultra/state.db",
+  "source": ".ultra/.runtime/state.db",
   "tasks": []
 }

package/CHANGELOG.md

@@ -7,6 +7,94 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.1] — 2026-07-29
+
+### Fixed
+
+- Increased the packed four-host integration-test timeout to preserve the same
+  release gate on slower clean Linux runners instead of cancelling a healthy
+  tarball installation and MCP round-trip near the previous limit.
+
+## [0.21.0] — 2026-07-29
+
+### Added
+
+- Added a trackable semantic artifact registry with digest, provenance,
+  ownership, freshness, and orphan detection while keeping mutable SQLite,
+  leases, telemetry, backups, and worktrees under the ignored
+  `.ultra/.runtime/` boundary.
+- Added typed Change deltas, documentation reconciliation records, immutable
+  task and role context snapshots, transactional plan publication, and
+  self-contained delivery archives with crash-safe recovery journals.
+- Added workflow revision and supersession contracts so accepted intent can
+  evolve without rewriting history or leaving active documents detached from
+  their owning workflow.
+- Added schema 20 migration and backup-first recovery for legacy
+  `.ultra/state.db` projects, including safe runtime relocation and inode-pinned
+  archive finalization on supported POSIX platforms.
+
+### Changed
+
+- Published one exact eleven-capability graph across all four host interaction
+  contracts. Every adapter now presents the same
+  `inspect -> suggest -> host-native ask -> normalize -> persist -> apply -> read back`
+  flow, owns no semantic authority, and waits for explicit invocation before another
+  public capability starts.
+- Updated current workflow, authority, runtime, and project templates for the separate
+  greenfield, brownfield-adoption, and migrated-authority paths.
+- Made every Change converge through a current plan, DB-backed task contract,
+  bounded context, risk-selected verification, review, documentation
+  reconciliation, and local delivery archive. Research remains adaptive and
+  may be omitted when current evidence is sufficient.
+- Defined `.ultra/` as project-local cross-session workflow memory: registered
+  specifications and evidence carry semantic bodies, while MCP and SQLite own
+  lifecycle state, references, digests, legal transitions, and recovery.
+- Extended packed-package conformance to cover prompt hygiene, native interaction
+  parity, exact public capabilities, user-handbook byte preservation, and project
+  inertness before `ultra-init`.
+
+### Fixed
+
+- Fixed archive, plan, session-close, worktree, and migration mutations so
+  partial failures recover the prior files and state instead of reporting false
+  success or leaving split authority.
+- Fixed context and delivery gates accepting stale, cross-project, symlinked,
+  malformed, unowned, or digest-mismatched artifacts.
+- Fixed draft baselines exempting arbitrary files under `.ultra/specs/`; only
+  the four reserved baseline scaffold files are provisional before baseline
+  readiness, and every additional spec is diagnosed as an orphan immediately.
+- Fixed host hooks and adapters resolving legacy state paths or becoming a
+  second semantic authority. Hooks now observe active workflow state, protect
+  projections, and surface recovery without forcing a semantic route.
+
+### Removed
+
+- Removed the non-Ultra `learn` command and Skill, automatic session-to-Skill mining,
+  and both global output-style personas from source, host adapters, and npm
+  distribution. Ultra no longer creates user Skills or controls communication style.
+
+## [0.20.0] — 2026-07-28
+
+### Added
+
+- Added schema 19 and `decision.complete` so settled normalized intent reaches a
+  terminal lifecycle state without fabricating a second user approval or an
+  artifact checkpoint. Existing settled schema-18 threads migrate safely.
+
+### Changed
+
+- Unified semantic selection across Claude Code, Codex, OpenCode, and Kimi Code
+  as `inspect -> suggest -> ask if unresolved -> normalize -> persist`, using
+  each host's native structured question surface with a direct-question
+  fallback.
+- Made research coverage and planning posture owner-selected after model
+  recommendation while preserving autonomous fact finding, synthesis,
+  decomposition, and reversible implementation judgment.
+- Stopped requiring a ceremonial decision checkpoint after every normalized
+  answer. Artifact checkpoints remain explicit digest-bound freshness gates.
+- Made unanswered non-blocking follow-ups advisory instead of global workflow
+  gates; unanswered blocking choices and blocking deferrals still fail closed.
+
 ## [0.19.1] — 2026-07-26
 
 ### Fixed
@@ -817,7 +905,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.19.1...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.19.1...v0.20.0
 [0.19.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.17.1...v0.18.0

package/README.md

@@ -43,7 +43,7 @@ Ultra Builder Pro addresses those gaps with four ideas:
 2. **Low-load user alignment.** The agent investigates observable facts itself
    and asks the user only for material intent, scope, risk, or authorization
    decisions—normally one dependent decision at a time.
-3. **Durable project authority.** `.ultra/state.db` records baselines, changes,
+3. **Durable project authority.** `.ultra/.runtime/state.db` records baselines, changes,
    decisions, workflows, tasks, evidence digests, sessions, incidents, and
    recovery state across hosts and sessions.
 4. **Convergent delivery.** Research, plans, implementation, tests, review, and
@@ -63,7 +63,7 @@ flowchart LR
     U["User<br/>intent and material decisions"] <--> H["Host agent<br/>reasoning and implementation"]
     H <--> S["Ultra skills<br/>task-specific workflows"]
     S <--> M["Ultra MCP<br/>state, evidence, freshness, recovery"]
-    M <--> D[(".ultra/state.db")]
+    M <--> D[(".ultra/.runtime/state.db")]
     H --> A["Code, specifications,<br/>tests and review artifacts"]
     A --> M
     K["Lifecycle hooks<br/>breadcrumb and projection protection"] --> M
@@ -73,8 +73,8 @@ The responsibility split is deliberate:
 
 | Owner | Responsibility |
 |---|---|
-| **User** | Product intent, material scope and trade-offs, destructive actions, publishing and deployment authorization |
-| **Host model** | Fact-finding, synthesis, research coverage, route recommendation, reversible implementation decisions |
+| **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
+| **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
 | **Ultra MCP** | Durable state, evidence references, digests, freshness, locks, valid transitions and hard recovery |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of generated projections |
@@ -121,6 +121,8 @@ Requirements:
 
 - Node.js 22 or newer;
 - Git for the normal project workflow;
+- Python 3 on a POSIX platform with `dir_fd` filesystem operations for
+  inode-pinned archive finalization and recovery;
 - one or more supported coding-agent hosts.
 
 Install globally into all detected host configuration directories:
@@ -189,7 +191,7 @@ Initialization:
 - identifies the repository root and scope;
 - classifies the repository as greenfield, brownfield, or migrated;
 - initializes Git when needed;
-- creates `.ultra/` and schema 18 project authority;
+- creates `.ultra/` and schema 20 project authority;
 - verifies that the scaffold and database can be read back;
 - completes without silently starting research, creating a commit, adding a
   remote, or pushing anything.
@@ -205,16 +207,18 @@ The common path after baseline approval is:
 ```text
 ultra-change
   -> optional ultra-think or bounded ultra-research
-  -> ultra-plan when planning is needed
+  -> ultra-plan
   -> ultra-dev
   -> risk-selected ultra-test
   -> ultra-review
   -> ultra-deliver
 ```
 
-That diagram is a common path, not a mandatory pipeline. A small current task
-can take a shorter valid route; a high-risk or unclear change can require more
-research, planning, checking, or user alignment.
+Each public workflow is explicitly invoked rather than auto-chained. Thinking and
+research coverage are adaptive, and verification depth is risk-selected, but every
+Change reaches a current plan, DB-backed task contract, and role-scoped context before
+development. “Direct Build” skips Research only; it does not bypass Plan, Task, or
+Context authority.
 
 ### 2. Adopt an existing project
 
@@ -231,9 +235,11 @@ product story. It builds a current-system baseline from:
 - APIs, data, permissions, integrations, deployment, and recovery seams;
 - known failures, documentation drift, technical debt, and unresolved unknowns.
 
-During `ultra-research`, the host model selects the smallest evidence-backed set
-of applicable catalog areas. Every included area receives one explicit
-disposition:
+During `ultra-research`, the host model inspects current evidence and recommends
+the smallest sufficient route. The owner selects, modifies, delegates, or
+defers it through the host-native question surface unless the current request
+already resolves the route. The normalized accepted coverage is then stored in
+`.ultra/.runtime/state.db`. Every included area receives one explicit disposition:
 
 - `execute` — produce fresh evidence;
 - `verify_existing` — validate an existing artifact;
@@ -243,7 +249,8 @@ disposition:
 
 The catalog is not a mandatory document set or questionnaire. Omitted areas
 create no workflow rows; an explicit exclusion is recorded only when retaining
-that rationale is useful.
+that rationale is useful. MCP validates state, evidence, and transitions; it
+does not store or prove the preceding UI interaction.
 
 Older projection-only Ultra projects are preserved and routed through a
 backup-first migration or rebaseline. Use `ultra-doctor` when initialization
@@ -263,8 +270,8 @@ The host then recommends one valid capability:
 
 - `ultra-think` for a material unresolved decision or diagnosis;
 - bounded `ultra-research` for a real evidence gap;
-- `ultra-plan` for task decomposition and dependency planning;
-- `ultra-dev` when a current task contract is already executable;
+- `ultra-plan` for the required task decomposition and dependency planning boundary;
+- `ultra-dev` after the current plan has produced an executable task contract;
 - `ultra-status` when the user needs the current authority and available routes;
 - `ultra-doctor` when state or installation health is degraded.
 
@@ -299,32 +306,58 @@ The next piece of daily work starts with a new `ultra-change`.
 | `ultra-deliver` | Reconcile specifications, close local authority, and archive the change |
 | `ultra-status` | Read the current breadcrumb, blockers, evidence, and allowed transitions |
 | `ultra-doctor` | Diagnose installation or project-state faults and expose safe recovery |
-| `learn` | Turn one approved, verified reusable procedure into a portable user skill |
+
+These eleven capabilities are the complete public Ultra command graph. Each capability
+returns current `allowed_transitions`; the host may recommend one, but another public
+capability starts only after an explicit user command or skill invocation.
 
 ## What lives in `.ultra/`
 
 ```text
 .ultra/
-  state.db                 # sole durable Ultra authority
-  specs/                   # current product and architecture baseline
+  .runtime/                # local mutable state; ignored by Git
+    state.db               # lifecycle, index, transition, and freshness authority
+    checkpoint.json        # advisory recovery projection
+    backups/               # verified migration and recovery snapshots
+    collab/                # local collaboration scratch
+    sessions/              # local leases and session runtime
+    worktrees/             # registered local Git worktrees
+    telemetry/             # local operational telemetry
+  specs/                   # digest-bound product and architecture baseline
   changes/
-    active/                # current Change artifacts
+    active/<id>/           # all current Change semantics and evidence
+      research/            # Change-only findings and research reports
+      delta/               # typed baseline overlay and semantic payloads
+      documentation/       # documentation overlay and reconciliation evidence
+      contexts/            # immutable role/task context snapshots
+      test/                # Change-scoped test reports
+      review/              # Change-scoped review workers and summary
+      delivery/            # Change-scoped delivery evidence
     archive/               # immutable delivered Change artifacts
-  docs/research/           # evidence reports for selected research areas
-  reports/                 # test, review, and delivery evidence
+  docs/research/           # baseline-only research evidence
+  reports/templates/       # blank report schemas; never delivery evidence
   tasks/
     tasks.json             # generated projection, never the authority
     contexts/              # bounded role/task context artifacts
 ```
 
-The host agent writes semantic specifications and evidence artifacts. MCP
-validates their references and digests, records workflow state, and rejects
-stale or illegal transitions. Generated Markdown and JSON help humans and tools
-inspect the project, but `.ultra/state.db` remains authoritative.
+Together, `.ultra/` is Ultra's project-local cross-session workflow memory. The
+host model writes semantic specifications and evidence through the active
+workflow. MCP records lifecycle state, references, digests, provenance, and
+accepted intent, then rejects stale or illegal transitions. The DB is the
+lifecycle and index authority; registered digest-bound files carry the semantic
+or evidence bodies that the DB references. Generated projections and working
+scratch are not authority.
+
+Ultra does not store chain-of-thought, raw prompts, transcripts, general
+conversational or episodic memory, or code-graph payloads. External memory and
+graph systems remain separate providers; Ultra may store bounded metadata
+references to them as workflow context. Only `.ultra/.runtime/` is ignored by
+Git: semantic and evidence artifacts can travel with the repository, while
+SQLite, leases, telemetry, and recovery scratch remain checkout-local.
 
-Ultra does not store chain-of-thought, raw prompts, transcripts, cross-session
-memory, or code-graph content. Memory and graph systems remain separate
-providers; Ultra may store only bounded metadata references to them.
+See [Artifact authority](./docs/ARTIFACT-AUTHORITY.md) for the promotion and
+evidence rules.
 
 ## Optional orchestration
 
@@ -376,7 +409,7 @@ host's existing model session.
   reinstall only the degraded host.
 - **Project state is unhealthy:** invoke `ultra-doctor` or run
   `ultra-tools system doctor`. Repairs and schema migrations are backup-first.
-- **A projection disagrees with MCP:** trust `.ultra/state.db`; do not repair
+- **A projection disagrees with MCP:** trust `.ultra/.runtime/state.db`; do not repair
   `tasks.json` or generated context Markdown by hand.
 - **A workflow appears blocked:** use `ultra-status` to read the exact current
   workflow, blocker, owner decision, and mechanically valid transitions.

package/adapters/_shared/codex-assets.cjs

@@ -8,6 +8,8 @@ const { spawnSync } = require('node:child_process');
 const yaml = require('js-yaml');
 const {
   CORE_PUBLIC_SKILLS,
+  RUNTIME_SUPPORT_FILES,
+  RUNTIME_WORKER_FILES,
   WORKFLOW_HOOK_FILES,
   skillPolicy,
   skillsForRuntime,
@@ -21,7 +23,10 @@ const {
   removeTree,
   writeAtomic,
 } = require('./file-ops.cjs');
-const { interactionContract } = require('./interaction-contract.cjs');
+const {
+  adaptInteractionGuidance,
+  interactionContract,
+} = require('./interaction-contract.cjs');
 
 const PLUGIN_NAME = 'ultra-builder-pro';
 const MANAGED_MARKER = 'Managed by Ultra Builder Pro Codex adapter.';
@@ -104,7 +109,7 @@ function adaptSkillAsset(input, targetName, _rel) {
 }
 
 function adaptHostText(input, skillName = '') {
-  let text = String(input);
+  let text = adaptInteractionGuidance(input, 'codex');
   text = text.replaceAll('codex-collab', 'cc-collab');
   text = text.replaceAll('CLAUDE.md', 'AGENTS.md');
   text = text.replaceAll('$CLAUDE_PLUGIN_ROOT/skills', '~/plugins/ultra-builder-pro/skills');
@@ -122,11 +127,6 @@ function adaptHostText(input, skillName = '') {
     text = adaptCodexPrimaryText(text, skillName);
   }
 
-  if (skillName === 'learn') {
-    text = text.replaceAll("current host's user skill directory", '`~/.agents/skills`');
-    text += `\n\n## Codex packaging requirement\n\nEach learned pattern must be a valid skill directory, not a loose Markdown file. The generated\n\`SKILL.md\` must start with only \`name\` and \`description\` frontmatter. Also create\n\`agents/openai.yaml\` with \`policy.allow_implicit_invocation: false\`. A new Codex task is required\nbefore the learned skill appears in discovery.\n`;
-  }
-
   return text;
 }
 
@@ -135,7 +135,6 @@ function adaptedDescription(sourceDescription, targetName) {
     'cc-collab': 'Ask Claude Code for an independent read-only analysis while Codex owns verification and synthesis. Use only when the user explicitly requests CC or Claude Code collaboration.',
     'ultra-verify': 'Run Codex-primary cross-model verification with a read-only Claude Code advisor. Use only when the user explicitly requests independent model verification.',
     'ultra-dev': 'Execute one authoritative Ultra task with Codex-native implementation, verification, and review. Use when a dependency-ready slice is ready for development.',
-    'learn': 'Extract one verified reusable workflow from the current Codex task into a portable user skill. Use when the user explicitly asks to preserve the method.',
   };
   return special[targetName] || adaptHostText(String(sourceDescription || `${titleCase(targetName)} workflow for Codex.`), targetName)
     .replace(/\s+/g, ' ')
@@ -295,6 +294,16 @@ function copyHooks(repoRoot, pluginRoot) {
 function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
   const source = path.join(repoRoot, 'mcp-server', 'server.cjs');
   const cliSource = path.join(repoRoot, 'adapters', '_shared', 'codex-ultra-tools-entry.cjs');
+  const runtimeWorkerSources = new Map([
+    [
+      'session-close-journal-worker.cjs',
+      path.join(repoRoot, 'orchestrator', 'session-close-journal-worker.cjs'),
+    ],
+    [
+      'doctor-backup-worker.cjs',
+      path.join(repoRoot, 'mcp-server', 'lib', 'doctor-backup-worker.cjs'),
+    ],
+  ]);
   const runtimeRoot = path.join(pluginRoot, 'runtime');
   const buildRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-codex-mcp-build-'));
   let nccCli;
@@ -359,6 +368,54 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
     removeTree(cliBuildRoot);
   }
 
+  for (const workerFile of RUNTIME_WORKER_FILES) {
+    const workerSource = runtimeWorkerSources.get(workerFile);
+    if (!workerSource) {
+      throw new Error(`Ultra runtime worker source is not registered: ${workerFile}`);
+    }
+    const workerBuildRoot = fs.mkdtempSync(path.join(
+      os.tmpdir(),
+      `ubp-${path.basename(workerFile, '.cjs')}-build-`,
+    ));
+    try {
+      const bundled = spawnSync(process.execPath, [
+        nccCli,
+        'build',
+        workerSource,
+        '-o',
+        workerBuildRoot,
+        '--no-cache',
+        '--quiet',
+      ], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+      });
+      if (bundled.error) throw bundled.error;
+      if (bundled.status !== 0) {
+        const detail = (bundled.stderr || bundled.stdout || '').trim();
+        throw new Error(
+          `ncc failed to bundle Ultra runtime worker ${workerFile}${detail ? `: ${detail}` : ''}`,
+        );
+      }
+      const workerOutput = path.join(workerBuildRoot, 'index.cjs');
+      if (!fs.existsSync(workerOutput)) {
+        throw new Error(`ncc did not emit Ultra runtime worker ${workerFile}`);
+      }
+      fs.copyFileSync(workerOutput, path.join(runtimeRoot, workerFile));
+    } finally {
+      removeTree(workerBuildRoot);
+    }
+  }
+
+  for (const supportFile of RUNTIME_SUPPORT_FILES) {
+    const sourceFile = path.join(repoRoot, 'mcp-server', 'lib', supportFile);
+    if (!fs.existsSync(sourceFile) || !fs.statSync(sourceFile).isFile()) {
+      throw new Error(`Ultra runtime support asset is missing: ${supportFile}`);
+    }
+    fs.copyFileSync(sourceFile, path.join(runtimeRoot, supportFile));
+  }
+
   const runtimeBootstrap = runtime === 'kimi' ? `
 const fs = require('node:fs');
 const pluginRoot = path.resolve(__dirname, '..');
@@ -381,9 +438,6 @@ if (!process.env.UBP_ROOT_DIR) {
   }
   process.env.UBP_ROOT_DIR = rootDir;
 }
-if (!process.env.UBP_DB_PATH) {
-  process.env.UBP_DB_PATH = path.join(process.env.UBP_ROOT_DIR, '.ultra', 'state.db');
-}
 ` : '';
 
   const launcher = `'use strict';
@@ -409,6 +463,10 @@ main().catch((error) => {
     path.join(repoRoot, 'mcp-server', 'hook-event.cjs'),
     path.join(runtimeRoot, 'hook-event.cjs'),
   );
+  fs.copyFileSync(
+    path.join(repoRoot, 'mcp-server', 'lib', 'plan-publication-worker.cjs'),
+    path.join(runtimeRoot, 'plan-publication-worker.cjs'),
+  );
 
   const sourceToolsFile = path.join(repoRoot, 'spec', 'mcp-tools.yaml');
   const upstreamManifest = yaml.load(fs.readFileSync(sourceToolsFile, 'utf8'));

package/adapters/_shared/interaction-contract.cjs

@@ -1,40 +1,53 @@
 'use strict';
 
+const { PUBLIC_CAPABILITY_GRAPH } = require('./runtime-assets.cjs');
+
 const SURFACES = Object.freeze({
   claude: Object.freeze({
     primary: 'AskUserQuestion',
     fallback: 'direct_user_interaction',
+    availability: 'interactive_session',
   }),
   codex: Object.freeze({
     primary: 'request_user_input',
     fallback: 'direct_user_interaction',
+    availability: 'current_mode_exposes_tool',
   }),
   opencode: Object.freeze({
     primary: 'question',
     fallback: 'direct_user_interaction',
+    availability: 'question_permission_not_denied',
   }),
   kimi: Object.freeze({
-    primary: 'native_question_surface',
+    primary: 'AskUserQuestion',
     fallback: 'direct_user_interaction',
+    availability: 'interactive_non_auto_mode',
   }),
 });
 
+const GENERIC_QUESTION_GUIDANCE =
+  /Use the host-native structured question surface declared by the installed interaction\s+contract(?: when it exists)?\./g;
+
 function interactionContract(runtime) {
   const question = SURFACES[runtime];
   if (!question) throw new Error(`unsupported interaction runtime: ${runtime}`);
   return {
-    schema_version: '1.0',
+    schema_version: '1.2',
     runtime,
+    public_capability_graph: PUBLIC_CAPABILITY_GRAPH,
     authority: {
       user: [
         'product_intent',
         'material_scope_and_tradeoffs',
+        'semantic_route_selection',
+        'risk_acceptance',
         'destructive_or_external_effect_authorization',
       ],
       host_model: [
         'fact_finding_and_synthesis',
         'reversible_implementation_judgment',
-        'coverage_risk_and_route_recommendation',
+        'semantic_route_recommendation',
+        'accepted_intent_normalization',
       ],
       ultra_mcp: [
         'durable_state_and_evidence_refs',
@@ -44,10 +57,30 @@ function interactionContract(runtime) {
     },
     interaction: {
       question_surface: question,
+      semantic_selection_flow: [
+        'inspect',
+        'suggest',
+        'host_native_ask',
+        'normalize',
+        'persist',
+        'apply',
+        'read_back',
+      ],
+      adapter_authority: 'none',
       dependent_decisions: 'one_at_a_time',
       independent_low_load_questions: { maximum: 3 },
       explicit_current_intent: 'normalize_without_reconfirmation',
-      unavailable_native_surface: 'use_direct_interaction',
+      dismissed_question: 'remain_unanswered',
+      unavailable_native_surface: 'use_direct_interaction_if_permitted',
+      host_forbids_interaction: 'remain_unanswered',
+    },
+    persistence: {
+      accepted_intent: 'trust_as_current_authority',
+      accepted_intent_recall: 'breadcrumb_and_decision_list',
+      user_interaction_proof: 'not_required',
+      raw_prompt_or_transcript: 'never_store',
+      pending_question: 'store_only_when_recovery_requires_it',
+      application_evidence: 'record_applied_refs_when_another_authority_changes',
     },
     routing: {
       semantic_recommendation_owner: 'host_model',
@@ -58,4 +91,26 @@ function interactionContract(runtime) {
   };
 }
 
-module.exports = { SURFACES, interactionContract };
+function interactionPrompt(runtime) {
+  const contract = interactionContract(runtime);
+  const surface = contract.interaction.question_surface;
+  const host = {
+    claude: 'Claude Code',
+    codex: 'Codex',
+    opencode: 'OpenCode',
+    kimi: 'Kimi Code',
+  }[runtime];
+  const primary = runtime === 'opencode' ? `\`${surface.primary}\`` : surface.primary;
+  return `Use ${host} ${primary} when ${surface.availability.replaceAll('_', ' ')} permits it.`;
+}
+
+function adaptInteractionGuidance(input, runtime) {
+  return String(input).replace(GENERIC_QUESTION_GUIDANCE, interactionPrompt(runtime));
+}
+
+module.exports = {
+  SURFACES,
+  adaptInteractionGuidance,
+  interactionContract,
+  interactionPrompt,
+};