@askdkc/kiokuko 0.2.7 → 0.2.9

package/migrations/022_embedding_setup_v2.sql

@@ -0,0 +1,236 @@
+-- Persist local embedding setup state while retaining the immutable v1
+-- semantic projections. This migration performs no model or network I/O.
+
+CREATE TABLE embedding_profiles_v2 (
+    profile_id TEXT PRIMARY KEY
+        CHECK (length(profile_id) = 64 AND profile_id NOT GLOB '*[^0-9a-f]*'),
+    schema_version INTEGER NOT NULL DEFAULT 1 CHECK (schema_version IN (1, 2)),
+    provider_kind TEXT NOT NULL
+        CHECK (provider_kind IN ('openai-compatible', 'local-transformers')),
+    endpoint_fingerprint TEXT
+        CHECK (endpoint_fingerprint IS NULL OR (length(endpoint_fingerprint) = 64 AND endpoint_fingerprint NOT GLOB '*[^0-9a-f]*')),
+    model TEXT NOT NULL,
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    distance_metric TEXT NOT NULL CHECK (distance_metric = 'cosine'),
+    distance_ceiling REAL NOT NULL CHECK (distance_ceiling > 0.0 AND distance_ceiling < 2.0),
+    document_template_version INTEGER NOT NULL CHECK (document_template_version > 0),
+    query_template_version INTEGER NOT NULL CHECK (query_template_version > 0),
+    preset_id TEXT,
+    source_model TEXT,
+    artifact_repository TEXT,
+    model_revision TEXT,
+    artifact_manifest_hash TEXT
+        CHECK (artifact_manifest_hash IS NULL OR (length(artifact_manifest_hash) = 64 AND artifact_manifest_hash NOT GLOB '*[^0-9a-f]*')),
+    inference_engine TEXT,
+    inference_engine_version TEXT,
+    dtype TEXT,
+    pooling TEXT,
+    normalize INTEGER CHECK (normalize IS NULL OR normalize IN (0, 1)),
+    maximum_tokens INTEGER CHECK (maximum_tokens IS NULL OR maximum_tokens > 0),
+    input_contract TEXT,
+    query_prefix TEXT,
+    document_prefix TEXT,
+    created_at TEXT NOT NULL,
+    CHECK (
+        (schema_version = 1 AND provider_kind = 'openai-compatible'
+            AND endpoint_fingerprint IS NOT NULL
+            AND preset_id IS NULL AND source_model IS NULL AND artifact_repository IS NULL
+            AND model_revision IS NULL AND artifact_manifest_hash IS NULL
+            AND inference_engine IS NULL AND inference_engine_version IS NULL
+            AND dtype IS NULL AND pooling IS NULL AND normalize IS NULL
+            AND maximum_tokens IS NULL AND input_contract IS NULL
+            AND query_prefix IS NULL AND document_prefix IS NULL)
+        OR
+        (schema_version = 2 AND provider_kind = 'local-transformers'
+            AND endpoint_fingerprint IS NULL
+            AND preset_id IS NOT NULL AND source_model IS NOT NULL
+            AND artifact_repository IS NOT NULL AND model_revision IS NOT NULL
+            AND artifact_manifest_hash IS NOT NULL AND inference_engine IS NOT NULL
+            AND inference_engine_version IS NOT NULL AND dtype IS NOT NULL
+            AND pooling IS NOT NULL AND normalize IS NOT NULL
+            AND maximum_tokens IS NOT NULL AND input_contract IS NOT NULL
+            AND query_prefix IS NOT NULL AND document_prefix IS NOT NULL)
+    )
+);
+
+INSERT INTO embedding_profiles_v2 (
+    profile_id, schema_version, provider_kind, endpoint_fingerprint, model,
+    dimensions, distance_metric, distance_ceiling, document_template_version,
+    query_template_version, created_at
+)
+SELECT profile_id, 1, provider_kind, endpoint_fingerprint, model,
+       dimensions, distance_metric, distance_ceiling, document_template_version,
+       query_template_version, created_at
+  FROM embedding_profiles;
+
+CREATE TABLE embedding_runtime_v2 (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    active_profile_id TEXT REFERENCES embedding_profiles_v2(profile_id),
+    generation INTEGER NOT NULL CHECK (generation > 0),
+    activated_at TEXT
+);
+
+INSERT INTO embedding_runtime_v2 (singleton, active_profile_id, generation, activated_at)
+SELECT singleton, active_profile_id, generation, activated_at
+  FROM embedding_runtime;
+
+CREATE TABLE entry_embeddings_v2 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v2(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    document_hash TEXT NOT NULL CHECK (length(document_hash) = 64 AND document_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (length(embedding) = dimensions * 4)
+);
+
+INSERT INTO entry_embeddings_v2 (
+    entry_id, profile_id, revision, content_hash, document_hash, dimensions,
+    embedding, vector_hash, created_at
+)
+SELECT entry_id, profile_id, revision, content_hash, document_hash, dimensions,
+       embedding, vector_hash, created_at
+  FROM entry_embeddings;
+
+CREATE TABLE embedding_jobs_v2 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v2(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('pending', 'leased', 'failed', 'blocked')),
+    attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+    available_at TEXT NOT NULL,
+    lease_id TEXT,
+    lease_expires_at TEXT,
+    error_code TEXT CHECK (error_code IS NULL OR error_code IN (
+        'timeout', 'rate_limited', 'provider_unavailable', 'invalid_response',
+        'dimension_mismatch', 'secret_blocked', 'profile_changed', 'entry_changed'
+    )),
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (
+        (state = 'leased' AND lease_id IS NOT NULL AND lease_expires_at IS NOT NULL)
+        OR (state <> 'leased' AND lease_id IS NULL AND lease_expires_at IS NULL)
+    )
+);
+
+INSERT INTO embedding_jobs_v2 (
+    entry_id, profile_id, revision, content_hash, state, attempts,
+    available_at, lease_id, lease_expires_at, error_code, created_at, updated_at
+)
+SELECT entry_id, profile_id, revision, content_hash, state, attempts,
+       available_at, lease_id, lease_expires_at, error_code, created_at, updated_at
+  FROM embedding_jobs;
+
+CREATE TABLE query_embeddings_v2 (
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v2(profile_id) ON DELETE CASCADE,
+    query_hash TEXT NOT NULL CHECK (length(query_hash) = 64 AND query_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    last_used_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, query_hash),
+    CHECK (length(embedding) = dimensions * 4)
+);
+
+INSERT INTO query_embeddings_v2 (
+    profile_id, query_hash, dimensions, embedding, vector_hash, created_at, last_used_at
+)
+SELECT profile_id, query_hash, dimensions, embedding, vector_hash, created_at, last_used_at
+  FROM query_embeddings;
+
+DROP INDEX idx_query_embeddings_lru;
+DROP TABLE query_embeddings;
+DROP INDEX idx_embedding_jobs_claim;
+DROP TABLE embedding_jobs;
+DROP INDEX idx_entry_embeddings_profile_revision;
+DROP TABLE entry_embeddings;
+DROP TABLE embedding_runtime;
+DROP TRIGGER embedding_profiles_immutable_update;
+DROP TABLE embedding_profiles;
+
+ALTER TABLE embedding_profiles_v2 RENAME TO embedding_profiles;
+ALTER TABLE embedding_runtime_v2 RENAME TO embedding_runtime;
+ALTER TABLE entry_embeddings_v2 RENAME TO entry_embeddings;
+ALTER TABLE embedding_jobs_v2 RENAME TO embedding_jobs;
+ALTER TABLE query_embeddings_v2 RENAME TO query_embeddings;
+
+CREATE TRIGGER embedding_profiles_immutable_update
+BEFORE UPDATE ON embedding_profiles
+BEGIN
+    SELECT RAISE(ABORT, 'embedding_profiles are immutable');
+END;
+
+CREATE INDEX idx_entry_embeddings_profile_revision
+    ON entry_embeddings(profile_id, entry_id, revision);
+CREATE INDEX idx_embedding_jobs_claim
+    ON embedding_jobs(profile_id, state, available_at, entry_id);
+CREATE INDEX idx_query_embeddings_lru
+    ON query_embeddings(profile_id, last_used_at, query_hash);
+
+CREATE TABLE embedding_model_installations (
+    installation_id TEXT PRIMARY KEY,
+    preset_id TEXT NOT NULL,
+    repository_id TEXT NOT NULL,
+    revision TEXT NOT NULL,
+    artifact_manifest_hash TEXT NOT NULL CHECK (length(artifact_manifest_hash) = 64 AND artifact_manifest_hash NOT GLOB '*[^0-9a-f]*'),
+    relative_path TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('staging', 'verified', 'corrupt', 'missing')),
+    total_bytes INTEGER NOT NULL CHECK (total_bytes >= 0),
+    installed_at TEXT NOT NULL,
+    verified_at TEXT,
+    last_checked_at TEXT NOT NULL
+);
+
+CREATE TABLE embedding_settings (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    mode TEXT NOT NULL CHECK (mode IN ('off', 'optional', 'required')),
+    provider_kind TEXT CHECK (provider_kind IS NULL OR provider_kind IN ('local-transformers', 'openai-compatible', 'legacy-environment')),
+    preset_id TEXT,
+    model_installation_id TEXT REFERENCES embedding_model_installations(installation_id),
+    vector_backend TEXT NOT NULL CHECK (vector_backend IN ('auto', 'javascript', 'sqlite-vec')),
+    batch_size INTEGER NOT NULL CHECK (batch_size BETWEEN 1 AND 64),
+    timeout_ms INTEGER NOT NULL CHECK (timeout_ms BETWEEN 100 AND 120000),
+    legacy_profile_id TEXT REFERENCES embedding_profiles(profile_id),
+    setup_state TEXT NOT NULL CHECK (setup_state IN ('disabled', 'requires_setup', 'installing', 'ready', 'degraded')),
+    updated_at TEXT NOT NULL
+);
+
+INSERT INTO embedding_settings (
+    singleton, mode, provider_kind, preset_id, model_installation_id,
+    vector_backend, batch_size, timeout_ms, legacy_profile_id, setup_state, updated_at
+)
+SELECT 1,
+       'off',
+       CASE WHEN r.active_profile_id IS NULL THEN NULL ELSE 'legacy-environment' END,
+       NULL,
+       NULL,
+       'auto',
+       16,
+       30000,
+       r.active_profile_id,
+       CASE WHEN r.active_profile_id IS NULL THEN 'disabled' ELSE 'requires_setup' END,
+       COALESCE(r.activated_at, '1970-01-01T00:00:00.000Z')
+  FROM embedding_runtime AS r;
+
+CREATE TABLE embedding_setup_runs (
+    setup_id TEXT PRIMARY KEY,
+    preset_id TEXT NOT NULL,
+    phase TEXT NOT NULL CHECK (phase IN ('planned', 'downloading', 'verifying', 'probing', 'activating', 'embedding', 'completed', 'failed')),
+    model_installation_id TEXT REFERENCES embedding_model_installations(installation_id),
+    active_profile_id TEXT REFERENCES embedding_profiles(profile_id),
+    initial_entry_count INTEGER NOT NULL CHECK (initial_entry_count >= 0),
+    processed_entry_count INTEGER NOT NULL CHECK (processed_entry_count >= 0),
+    failure_code TEXT,
+    started_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    completed_at TEXT
+);

package/migrations/down/022_embedding_setup_v2.sql

@@ -0,0 +1,133 @@
+-- Manual rollback for migration 022. Stop every Kiokuko process and make a
+-- full SQLite backup before running this script. Local v2 profiles are not
+-- silently converted to the v1 representation.
+
+BEGIN IMMEDIATE;
+
+CREATE TEMP TRIGGER embedding_setup_v2_rollback_guard
+BEFORE DELETE ON schema_migrations
+WHEN EXISTS (SELECT 1 FROM embedding_profiles WHERE schema_version = 2)
+BEGIN
+    SELECT RAISE(ABORT, 'migration 022 rollback requires removing local v2 profiles explicitly');
+END;
+
+CREATE TABLE embedding_profiles_v1 (
+    profile_id TEXT PRIMARY KEY CHECK (length(profile_id) = 64 AND profile_id NOT GLOB '*[^0-9a-f]*'),
+    provider_kind TEXT NOT NULL CHECK (provider_kind IN ('openai-compatible')),
+    endpoint_fingerprint TEXT NOT NULL CHECK (length(endpoint_fingerprint) = 64 AND endpoint_fingerprint NOT GLOB '*[^0-9a-f]*'),
+    model TEXT NOT NULL,
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    distance_metric TEXT NOT NULL CHECK (distance_metric = 'cosine'),
+    distance_ceiling REAL NOT NULL CHECK (distance_ceiling > 0.0 AND distance_ceiling < 2.0),
+    document_template_version INTEGER NOT NULL CHECK (document_template_version > 0),
+    query_template_version INTEGER NOT NULL CHECK (query_template_version > 0),
+    created_at TEXT NOT NULL
+);
+INSERT INTO embedding_profiles_v1 (
+    profile_id, provider_kind, endpoint_fingerprint, model, dimensions,
+    distance_metric, distance_ceiling, document_template_version,
+    query_template_version, created_at
+)
+SELECT profile_id, provider_kind, endpoint_fingerprint, model, dimensions,
+       distance_metric, distance_ceiling, document_template_version,
+       query_template_version, created_at
+  FROM embedding_profiles;
+
+CREATE TABLE embedding_runtime_v1 (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    active_profile_id TEXT REFERENCES embedding_profiles_v1(profile_id),
+    generation INTEGER NOT NULL CHECK (generation > 0),
+    activated_at TEXT
+);
+INSERT INTO embedding_runtime_v1 (singleton, active_profile_id, generation, activated_at)
+SELECT singleton, active_profile_id, generation, activated_at FROM embedding_runtime;
+
+CREATE TABLE entry_embeddings_v1 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v1(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    document_hash TEXT NOT NULL CHECK (length(document_hash) = 64 AND document_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (length(embedding) = dimensions * 4)
+);
+INSERT INTO entry_embeddings_v1 SELECT * FROM entry_embeddings;
+
+CREATE TABLE embedding_jobs_v1 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v1(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('pending', 'leased', 'failed', 'blocked')),
+    attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+    available_at TEXT NOT NULL,
+    lease_id TEXT,
+    lease_expires_at TEXT,
+    error_code TEXT CHECK (error_code IS NULL OR error_code IN (
+        'timeout', 'rate_limited', 'provider_unavailable', 'invalid_response',
+        'dimension_mismatch', 'secret_blocked', 'profile_changed', 'entry_changed'
+    )),
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (
+        (state = 'leased' AND lease_id IS NOT NULL AND lease_expires_at IS NOT NULL)
+        OR (state <> 'leased' AND lease_id IS NULL AND lease_expires_at IS NULL)
+    )
+);
+INSERT INTO embedding_jobs_v1 SELECT * FROM embedding_jobs;
+
+CREATE TABLE query_embeddings_v1 (
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v1(profile_id) ON DELETE CASCADE,
+    query_hash TEXT NOT NULL CHECK (length(query_hash) = 64 AND query_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    last_used_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, query_hash),
+    CHECK (length(embedding) = dimensions * 4)
+);
+INSERT INTO query_embeddings_v1 SELECT * FROM query_embeddings;
+
+DELETE FROM schema_migrations WHERE version = 22 AND name = '022_embedding_setup_v2.sql';
+DROP TRIGGER embedding_setup_v2_rollback_guard;
+
+DROP TABLE embedding_setup_runs;
+DROP TABLE embedding_settings;
+DROP TABLE embedding_model_installations;
+DROP INDEX idx_query_embeddings_lru;
+DROP TABLE query_embeddings;
+DROP INDEX idx_embedding_jobs_claim;
+DROP TABLE embedding_jobs;
+DROP INDEX idx_entry_embeddings_profile_revision;
+DROP TABLE entry_embeddings;
+DROP TABLE embedding_runtime;
+DROP TRIGGER embedding_profiles_immutable_update;
+DROP TABLE embedding_profiles;
+
+ALTER TABLE embedding_profiles_v1 RENAME TO embedding_profiles;
+ALTER TABLE embedding_runtime_v1 RENAME TO embedding_runtime;
+ALTER TABLE entry_embeddings_v1 RENAME TO entry_embeddings;
+ALTER TABLE embedding_jobs_v1 RENAME TO embedding_jobs;
+ALTER TABLE query_embeddings_v1 RENAME TO query_embeddings;
+
+CREATE TRIGGER embedding_profiles_immutable_update
+BEFORE UPDATE ON embedding_profiles
+BEGIN
+    SELECT RAISE(ABORT, 'embedding_profiles are immutable');
+END;
+CREATE INDEX idx_entry_embeddings_profile_revision
+    ON entry_embeddings(profile_id, entry_id, revision);
+CREATE INDEX idx_embedding_jobs_claim
+    ON embedding_jobs(profile_id, state, available_at, entry_id);
+CREATE INDEX idx_query_embeddings_lru
+    ON query_embeddings(profile_id, last_used_at, query_hash);
+
+COMMIT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askdkc/kiokuko",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Model-agnostic external memory for AI coding agents",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "dist/",
     "migrations/",
     "skills/",
+    "docs/",
     "templates/",
     "README.md",
     "README.ja.md",
@@ -32,6 +33,7 @@
     "test:unit": "node scripts/run-tests.mjs tests/unit",
     "test:integration": "node scripts/run-tests.mjs tests/integration",
     "test:sqlite-vec": "node --import tsx tests/ci/sqlite-vec-package-smoke.ts",
+    "test:global-install": "node tests/ci/global-install-smoke.mjs",
     "test:evaluation": "npm run build && node scripts/run-retrieval-evaluation.mjs",
     "test:benchmark": "npm run build && node scripts/run-retrieval-benchmark.mjs",
     "test:e2e:codex": "npm run build && node scripts/run-enno-agent-e2e.mjs codex",
@@ -41,7 +43,6 @@
     "sampledb:generate": "node --import tsx tests/fixtures/sample-database.ts tests/sampledb/kiokuko.sqlite3",
     "test:sampledb": "npm run build && node --import tsx tests/ci/verify-sample-database.ts",
     "pack:check": "npm pack --dry-run",
-    "prepare": "npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run pack:check"
   },
   "dependencies": {
@@ -52,12 +53,32 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
-  "optionalDependencies": {
+  "overrides": {
+    "adm-zip": "0.6.0",
+    "sharp": "0.35.4"
+  },
+  "peerDependencies": {
+    "@huggingface/hub": "2.16.1",
+    "@huggingface/transformers": "4.2.0",
     "sqlite-vec": "0.1.9"
   },
+  "peerDependenciesMeta": {
+    "@huggingface/hub": {
+      "optional": true
+    },
+    "@huggingface/transformers": {
+      "optional": true
+    },
+    "sqlite-vec": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@huggingface/hub": "2.16.1",
+    "@huggingface/transformers": "4.2.0",
     "@types/node": "^24.0.0",
     "@types/semver": "^7.8.0",
+    "sqlite-vec": "0.1.9",
     "tsx": "^4.20.3",
     "typescript": "^5.9.2"
   }

package/skills/kiokuko-enno-oduno/SKILL.md

@@ -34,6 +34,20 @@ phase report require the stored digest plus a complete disposition for every
 slot; other phase schemas omit those fields. Submitting advice does not advance
 the main Enno status.
 
+### Recovery-only advisory restoration
+
+After a successful `enno_advice_submit`, use its complete `advisoryRound` from
+the current context whenever it is still available. Call `enno_advice_read` at
+most once only when the current state is `aggregated` but the contribution
+bodies are missing after session termination or client reroute. The read restores
+a stored current round; it is not advisor fanout, state advancement, or
+confirmation.
+
+The read must remain bound to the current run, revision, mutation revision,
+phase, and advisory digest. If it fails, do not infer contributions or invent
+dispositions. Never restore provider/model identity or raw advisor output;
+preserve existing failure codes such as `unsafe_output`.
+
 ## Activation boundary
 
 Apply this Skill only when one of these is true:
@@ -119,6 +133,36 @@ action together with the host-retained capability catalog.
 
 Review the approved contract rather than the quality of the final prose response.
 
+Final Review advisory input is evidence for judgment, not a vote. Evaluate each
+slot by its role, concrete evidence, and correspondence to an acceptance
+criterion; never treat agreement count as correctness evidence. Advisor
+disagreement alone is non-blocking and must not trigger replan or user
+confirmation.
+
+For each slot, `adopted` means that at least part of its contribution
+concretely affected the current judgment or output. `not_adopted` means its
+content was considered but not used. `unavailable` is reserved for the existing
+failure, timeout, or isolation-unavailable outcomes. Adoption does not approve
+every recommendation; record a short rationale for what evidence was used or
+why it was not used.
+
+Only evidence-backed contract blockers may produce replan feedback. Keep at most
+eight blockers, each tied to a violated acceptance criterion or approved
+contract invariant, a repository-relative path, concrete observed evidence,
+impact or regression risk, a bounded Zenki change, and an existing or focused
+verifier that proves the fix. Merge duplicate findings with the same criterion,
+path, observed behavior, and requested change.
+
+Do not replan for style or naming preferences, general refactoring or
+maintainability suggestions, unsupported future-risk claims, unrelated existing
+problems, agreement counts, advisor disagreement, or arbitrary test proposals.
+Keep `review.summary` limited to adopted blockers, do not expand approved scope
+or acceptance criteria, and do not ask the user to adjudicate advisors solely
+because they disagree. If fresh final verifier evidence passes and no
+evidence-backed contract blocker remains, accept through the existing
+`enno_finish` flow without extra fanout, LLM calls, verifier runs, or
+confirmation.
+
 Confirm all of the following before acceptance:
 
 - every approved WorkUnit completed under the current contract revision;

package/templates/AGENTS.md

@@ -14,7 +14,7 @@ Use the Kiokuko MCP tools rather than reading or modifying the SQLite file direc
 
 ### Before non-trivial work
 
-At the ideal, planning, and final-review phases, the parent host may fan out exactly three fixed advisor slots. Kiokuko does not launch advisors. The parent host must verify isolated read-only execution; prompt wording is not proof, and a slot that cannot be verified is reported as `unavailable`. Advisor input excludes Enno run identity, workspace, orchestration identity, revisions, and idempotency keys. Only the parent aggregator calls `enno_advice_submit`; results are `host_reported`, without provider/model identity or raw subagent output. Contributions use fixed slots, fixed failure codes, canonical JSON, control-character rejection, repository-relative evidence paths, and 16 KiB per-slot / 48 KiB per-round UTF-8 limits. Secret-shaped completed output becomes `unsafe_output` without persistence or forwarding. The advisory lifecycle is `not_started → fanout_requested → aggregated → consumed`. Aggregated rounds suppress duplicate fanout, expose the stored digest and required slot dispositions, and make the current phase report schema require both the digest and complete dispositions; other phases omit those fields. Final Review is two-phase: `enno_verify_prepare` executes final verifiers outside database transactions with shell disabled and repository-relative cwd, then stores evidence bound to the current contract revision, mutation revision, verifier specification digest, and full repository-state digest. Identical evidence is reused only while all bindings remain current; repository changes or verifier mutation invalidate it. The final advisory fanout is returned only after evidence is prepared. `enno_finish` never spawns a subprocess, rechecks repository state inside its mutation transaction, and decides accept/replan/block from the full stored criteria, WorkUnit, verifier, and repository evidence.
+At the ideal, planning, and final-review phases, the parent host may fan out exactly three fixed advisor slots. Kiokuko does not launch advisors. The parent host must verify isolated read-only execution; prompt wording is not proof, and a slot that cannot be verified is reported as `unavailable`. Advisor input excludes Enno run identity, workspace, orchestration identity, revisions, and idempotency keys. Only the parent aggregator calls `enno_advice_submit`; results are `host_reported`, without provider/model identity or raw subagent output. Contributions use fixed slots, fixed failure codes, canonical JSON, control-character rejection, repository-relative evidence paths, and 16 KiB per-slot / 48 KiB per-round UTF-8 limits. Secret-shaped completed output becomes `unsafe_output` without persistence or forwarding. The advisory lifecycle is `not_started → fanout_requested → aggregated → consumed`. Aggregated rounds suppress duplicate fanout, expose the stored digest and required slot dispositions, and make the current phase report schema require both the digest and complete dispositions; other phases omit those fields. If an aggregated round's contribution bodies are missing after session termination or client reroute, use the recovery-only `enno_advice_read` once with the current identity and digest; do not read on the normal path, rerun advisors, or infer dispositions. Final Review is two-phase: `enno_verify_prepare` executes final verifiers outside database transactions with shell disabled and repository-relative cwd, then stores evidence bound to the current contract revision, mutation revision, verifier specification digest, and full repository-state digest. Identical evidence is reused only while all bindings remain current; repository changes or verifier mutation invalidate it. The final advisory fanout is returned only after evidence is prepared. Final Review must deduplicate evidence-backed contract blockers; disagreement or evidence-free suggestions do not justify replan or user adjudication. `enno_finish` never spawns a subprocess, rechecks repository state inside its mutation transaction, and decides accept/replan/block from the full stored criteria, WorkUnit, verifier, and repository evidence.
 
 If plan submission returns `userFacingRecovery`, show only its what-happened, work-state, resolution, and choices in the user's language. For every choice, present its label and recommendation first, then translate and present `whenToChoose` as the intent the choice fits and `whatHappens` as its exact result. Do not expose the machine `action`, internal tool or field names, capability catalog, digest, run identity, revision, presentation version, raw JSON, or reason code. Do not retry, cancel, or create a new task automatically: wait for the user's explicit choice. Continue the same plan only by attaching the complete catalog retained from task preparation; never ask the user to locate or construct that catalog. A plan-review choice asks the user what to change and performs no implementation. For an active planning attempt, a restart choice explicitly cancels it before starting a new `task_prepare` with current capabilities. If the projection says the attempt already ended, do not try to cancel it again; start a new task only after the user chooses restart. A cancel choice creates no replacement and leaves an already-ended attempt unchanged.