akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/core/standards/resolve-standards-context.js

@@ -28,24 +28,12 @@ function refType(ref) {
     const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
     // 0.9.0 conceptId `<stash-subdir>/<name>`: delegate to the D-R2 reverse table
     // so the leading stash subdir maps back to its asset type (the canonical path).
-    const conceptType = typeNameFromConceptId(body)?.type;
-    if (conceptType !== undefined)
-        return conceptType;
-    // DOCUMENTED EXCEPTION (ref-grammar decision D-R3 migration window): a tolerant
-    // legacy `type:name` arm survives ONLY because live callers still hand this
-    // recognition-only seam the old spelling — `propose.ts` builds
-    // `${options.type}:${options.name}`, and a pre-migration stored ref may still
-    // reach here before the 0.10.0 grammar removal. It never crosses a storage
-    // boundary, so it stays until those feeders flip.
-    const colon = body.indexOf(":");
-    if (colon > 0)
-        return body.slice(0, colon).trim() || undefined;
-    return undefined;
+    return typeNameFromConceptId(body)?.type;
 }
 /**
  * Resolve the standards context for a write target identified by its asset ref.
  *
- * @param ref       Canonical asset ref of the write target (e.g. `skill:foo`).
+ * @param ref       Canonical asset ref of the write target (e.g. `skills/foo`).
  *                  When undefined, the target is a general authoring flow.
  * @param stashRoot Stash root directory.
  */

package/dist/core/standards/resolve-stash-standards.js

@@ -53,14 +53,14 @@ function collectMarkdownFiles(dir) {
     return results;
 }
 /**
- * Derive a fact ref (`fact:conventions/naming`) from an absolute markdown path
+ * Derive a fact ref (`facts/conventions/naming`) from an absolute markdown path
  * relative to the facts root. Mirrors the canonical-name derivation in
  * `asset-spec.ts` (POSIX separators, `.md` stripped).
  */
 function toFactRef(factsRoot, absPath) {
     const rel = path.relative(factsRoot, absPath).split(path.sep).join("/");
     const name = rel.endsWith(".md") ? rel.slice(0, -3) : rel;
-    return `fact:${name}`;
+    return `${FACTS_SUBDIR}/${name}`;
 }
 export function resolveStashStandards(stashRoot) {
     const factsRoot = path.join(stashRoot, FACTS_SUBDIR);

package/dist/core/standards/resolve-type-conventions.js

@@ -28,9 +28,9 @@ import { placementTypes } from "../asset/asset-placement.js";
 import { parseFrontmatter } from "../asset/frontmatter.js";
 /** Sub-path (under the stash root) for per-type SOFT convention facts. */
 export const TYPE_CONVENTIONS_SUBDIR = path.join("facts", "conventions", "assets");
-/** The `fact:` ref prefix for a per-type convention, e.g. `fact:conventions/assets/skill`. */
+/** The slash conceptId for a per-type convention, e.g. `facts/conventions/assets/skill`. */
 export function typeConventionRef(type) {
-    return `fact:conventions/assets/${type}`;
+    return `facts/conventions/assets/${type}`;
 }
 /**
  * Read the SOFT authoring-convention body for asset type `type`, if a stash

package/dist/core/state/migrations.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { runMigrations as runSqliteMigrations } from "../../storage/engines/sqlite-migrations.js";
+import { assertMigrationRegistry, runMigrations as runSqliteMigrations, } from "../../storage/engines/sqlite-migrations.js";
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
     {
@@ -59,7 +59,7 @@ export const STATE_MIGRATIONS = [
       --   id          TEXT PK     — UUID (crypto.randomUUID()); stable directory name.
       --   stash_dir   TEXT        — absolute stash root; multi-stash installs need
       --                             this to partition proposal lists per stash.
-      --   ref         TEXT        — target asset ref (e.g. "lesson:alpha");
+      --   ref         TEXT        — target asset ref (e.g. "lessons/alpha");
       --                             indexed for ref-scoped queue views.
       --   status      TEXT        — "pending" | "accepted" | "rejected"; indexed
       --                             so pending-queue queries are fast.
@@ -76,7 +76,7 @@ export const STATE_MIGRATIONS = [
       --   metadata_json TEXT      — JSON object for future proposal fields.
       --                             Current fields stored here: sourceRun,
       --                             review, confidence, gateDecision (#577),
-      --                             backupContent, eligibilitySource.
+      --                             backupContent.
       --
       -- ADD COLUMN extension points (future migrations):
       --   ALTER TABLE proposals ADD COLUMN source_run TEXT DEFAULT NULL;
@@ -350,11 +350,12 @@ export const STATE_MIGRATIONS = [
     //
     // VESTIGIAL as of the Chunk-8 fold: the legacy `proposal.json` import moved
     // OUT of the live per-operation path and INTO the one-time migrator
-    // (`src/migrate/legacy/proposal-fs-import.ts`, wired through `akm migrate apply`),
+    // (`scripts/akm-migrate/migrate/legacy/proposal-fs-import.ts`, wired through
+    // `akm-migrate apply`),
     // whose idempotency is INSERT OR IGNORE on the proposal UUID plus migrate-apply's
-    // own journal — it no longer reads or writes this ledger. The CREATE TABLE
-    // stays because the migration registry is APPEND-ONLY and checksum-sealed:
-    // removing a released fragment would make the schema_migrations ledger of an
+    // incomplete sentinel — it no longer reads or writes this ledger. The CREATE TABLE
+    // stays because migration IDs are append-only: removing a released migration
+    // would make the schema_migrations ledger of an
     // already-migrated rc database stop being an exact ordered prefix, and the
     // runner would refuse to open it. The empty table is harmless.
     //
@@ -832,17 +833,17 @@ export const STATE_MIGRATIONS = [
     //
     // The state.db half of the three-DB merge (plan §3.2/§8, normative §11.4,
     // chunk-8 cutover design §1). This migration is PURE,
-    // SEALABLE, IDEMPOTENT DDL ONLY — `CREATE TABLE IF NOT EXISTS` (+ indexes),
+    // IDEMPOTENT DDL ONLY — `CREATE TABLE IF NOT EXISTS` (+ indexes),
     // never a DROP or a data move. The actual data movement (the workflow.db merge,
     // the usage_events rescue from index.db, the full old-ref→item_ref re-key, and
-    // the workflow.db delete / index.db quarantine) is CODE — a journaled step of
-    // the migrate-apply flow (`src/cli/config-migrate.ts` `cutover-applied` phase),
-    // driven by `src/migrate/legacy/three-db-cutover.ts`. See the no-DROP contract
-    // carve-out note in `src/core/state-db.ts`.
+    // the workflow.db delete / index.db quarantine) is idempotent migrate-apply
+    // code driven by
+    // `scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`. See the no-DROP
+    // contract carve-out note in `src/core/state-db.ts`.
     //
     // The three workflow tables are the 10 pre-cutover workflow migrations
-    // (the frozen `src/migrate/legacy/workflow-migrations-bodies.ts` base schema +
-    // 001–010) folded into one baseline at their FINAL post-010 shape — column
+    // (the frozen `scripts/akm-migrate/migrate/legacy/workflow-migrations-bodies.ts`
+    // base schema + 001–010) folded into one baseline at their FINAL post-010 shape — column
     // lists, CHECK constraints, and indexes copied verbatim. `usage_events` mirrors
     // index.db's former `ensureUsageEventsSchema` (`src/indexer/usage/usage-events.ts`),
     // its new durable home. `legacy_state` mirrors `ensureLegacyStateTable`
@@ -958,7 +959,32 @@ export const STATE_MIGRATIONS = [
       );
     `,
     },
+    // ── Migration 021 — asset_salience / asset_outcome: missing_since (#733) ────
+    //
+    // Orphan-GC grace clock (Workstream C / #733,
+    // docs/architecture/specs/0.9.0-close-out-plan.md). Neither table carries a
+    // column that records when a row's ref STOPPED resolving against
+    // `entries.item_ref` — `updated_at` is bumped by improve itself on every
+    // touch, so it cannot double as a "went missing" timestamp.
+    //
+    // `missing_since` is stamped by `runOrphanStateGcPass`
+    // (src/commands/improve/loop-stages.ts) the first time a row's ref fails to
+    // resolve against the live index, cleared the moment the ref resolves
+    // again, and used to gate deletion once `STATE_GC_GRACE_MS` (7 days) has
+    // elapsed — and ONLY when `improve.stateGc.collect` is true (default
+    // false). Mirrors the additive ADD-COLUMN style of migration 011.
+    //
+    // NULL = never missing (the steady-state default for every existing row —
+    // both a fresh row and a pre-migration row read back NULL here).
+    {
+        id: "021-asset-state-missing-since",
+        up: `
+      ALTER TABLE asset_salience ADD COLUMN missing_since INTEGER DEFAULT NULL;
+      ALTER TABLE asset_outcome ADD COLUMN missing_since INTEGER DEFAULT NULL;
+    `,
+    },
 ];
+assertMigrationRegistry(STATE_MIGRATIONS);
 /**
  * Apply every pending migration in a single transaction per migration.
  *
@@ -968,8 +994,5 @@ export const STATE_MIGRATIONS = [
  * Called automatically by `openStateDatabase()`.
  */
 export function runMigrations(db, options) {
-    runSqliteMigrations(db, STATE_MIGRATIONS, {
-        applyPending: options?.applyPending,
-        generationMarker: options?.generationMarker,
-    });
+    runSqliteMigrations(db, STATE_MIGRATIONS, { applyPending: options?.applyPending });
 }

package/dist/core/state-db.js

@@ -45,11 +45,10 @@
  * merge-target tables at their final shape. The one-time, filesystem-derived,
  * fail-closed DATA movement (the workflow.db merge, the usage_events rescue, the
  * full old-ref→item_ref re-key, and the workflow.db unlink / index.db quarantine
- * rename) is deliberately NOT a sealed SQL migration body: it is a journaled step
- * of the migrate-apply coordinator (`src/cli/config-migrate.ts` `cutover-applied`
- * phase → `src/migrate/legacy/three-db-cutover.ts`). So the no-DROP contract here
- * is intact — the physical workflow.db deletion happens outside the ledger DDL,
- * under the backup-verified-restorable fail-closed gate.
+ * rename) runs as idempotent code in the migrate-apply coordinator
+ * (`scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`). So the no-DROP
+ * contract here is intact: physical workflow.db deletion happens outside the
+ * ledger DDL, after a verified backup and committed data transaction.
  *
  * ## Schema design: indexed columns vs. metadata_json
  *
@@ -73,7 +72,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { openDatabase } from "../storage/database.js";
 import { assertCurrentMigrationLedger, assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
-import { openManagedDatabase, withManagedDb, withManagedDbAsync } from "../storage/managed-db.js";
+import { openManagedDatabase, withManagedDb } from "../storage/managed-db.js";
 import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
 import { assertNoPendingMigrationOperation } from "./migration-operation.js";
 import { getDataDir } from "./paths.js";
@@ -182,14 +181,6 @@ export function openStateDatabase(dbPath) {
 export function withStateDb(fn, opts) {
     return withManagedDb(() => openStateDatabase(opts?.path), fn, opts);
 }
-/**
- * Async sibling of {@link withStateDb} — for `fn`s that hold the handle across
- * an `await` (the sync version would close it too early). Same borrow/own +
- * optional `path` override semantics.
- */
-export function withStateDbAsync(fn, opts) {
-    return withManagedDbAsync(() => openStateDatabase(opts?.path), fn, opts);
-}
 /**
  * Fire-and-forget telemetry write to state.db (Chunk-8 WI-8.3: usage_events'
  * durable home). Skips entirely when state.db does not exist yet (never

package/dist/core/structured.js

@@ -15,7 +15,7 @@
  *
  * Layering: this file lives in `core/` — NOT `llm/` — because the agent path
  * must be able to reach it and `agent/ ⇏ llm/` is an enforced invariant
- * (`tests/architecture/agent-no-llm-sdk-guard.test.ts`). The transport is
+ * (`tests/integration/architecture/agent-no-llm-sdk-guard.test.ts`). The transport is
  * always injected; this module never performs IO of its own.
  *
  * Retry semantics: only parse/validation misses are retried (with corrective

package/dist/core/subprocess.js

@@ -148,6 +148,7 @@ export async function readStream(stream, opts) {
     }
 }
 const EMPTY_READ = { text: "", timedOut: false };
+const UNBOUNDED_STREAM_READ_SAFETY_MS = 60 * 60 * 1000;
 function toError(err) {
     return err instanceof Error ? err : new Error(String(err));
 }
@@ -238,10 +239,11 @@ export async function runManagedSubprocess(cmd, opts) {
         else
             abortSignal.addEventListener("abort", onAbort, { once: true });
     }
-    // Stream-drain timeout: the wall budget plus a 2 s grace, or 30 s when there
-    // is no kill timer. Ensures the caller never hangs past the budget even if a
-    // killed child leaves a pipe write-end open in a background thread.
-    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
+    // Stream-drain timeout: the wall budget plus a 2 s grace, or a one-hour
+    // safety bound when execution itself is unbounded. This timer starts with
+    // capture, so the null-timeout path must not impose a short hidden deadline
+    // on an otherwise healthy long-running process.
+    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : UNBOUNDED_STREAM_READ_SAFETY_MS;
     const stdoutPromise = capture
         ? readStream(proc.stdout ?? null, {
             timeoutMs: streamDrainTimeoutMs,

package/dist/core/text-truncation.js

@@ -9,9 +9,11 @@
  * implementations historically maintained overlapping-but-not-identical
  * vocabularies of hanging-connector words, which was a maintenance trap.
  *
- * This module is the single source of truth. `distill` continues to layer its
- * own section-heading regex on top (those patterns are distill-specific and
- * intentionally stay local to that module).
+ * This module is the single source of truth. A separate section-heading regex
+ * (`HEADING_FRAGMENT_PATTERNS` in
+ * `src/commands/proposal/validators/proposal-quality-validators.ts`) layers on
+ * top of these heuristics and is shared across distill, consolidate, and
+ * reflect rather than staying local to any one of them.
  */
 /**
  * Words that, when ending a sentence, suggest the description was truncated
@@ -87,8 +89,10 @@ export const TRUNCATION_TRAILING_WORDS = new Set([
  *   - Trailing ellipsis (`...` or `…`)
  *   - Last word matches {@link TRUNCATION_TRAILING_WORDS}
  *
- * Does NOT detect section-heading fragments — that check is distill-specific
- * and lives in `src/commands/distill.ts` (`HEADING_FRAGMENT_PATTERNS`).
+ * Does NOT detect section-heading fragments — that check lives in
+ * `HEADING_FRAGMENT_PATTERNS` in
+ * `src/commands/proposal/validators/proposal-quality-validators.ts`, shared by
+ * distill, consolidate, and reflect.
  */
 export function detectTruncatedDescription(description) {
     const trimmed = description.trim();

package/dist/core/type-presentation.js

@@ -38,7 +38,7 @@ function shellQuote(value) {
 }
 /** Reproduced from `output/renderers.ts#buildWorkflowAction` — the one function-valued `ACTION_BUILDERS.workflow` entry. */
 function buildWorkflowAction(ref) {
-    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+    return `Start or resume execution with \`akm workflow run ${shellQuote(ref)}\`.`;
 }
 /**
  * Exhaustive over {@link KnownType} — a HAND-WRITTEN literal, not derived
@@ -74,7 +74,7 @@ export const TYPE_PRESENTATION = {
     secret: {
         label: "Secret",
         renderer: "secret-file",
-        action: (ref) => `akm show ${ref} -> name only (value never shown); akm secret path ${ref} -> file path; akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
+        action: (ref) => `akm show ${ref} -> name only (value never shown); akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
     },
     lesson: {
         label: "Lesson",
@@ -84,7 +84,7 @@ export const TYPE_PRESENTATION = {
     task: {
         label: "Task",
         renderer: "task-yaml",
-        action: (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`,
+        action: (ref) => `akm show ${ref} -> inspect; akm task run <id> -> run now; edit the file + akm task sync -> unschedule`,
     },
     session: {
         label: "Session",

package/dist/core/warn.js

@@ -78,9 +78,6 @@ export function setLogFile(filePath) {
 export function clearLogFile() {
     logFilePath = undefined;
 }
-export function getLogFile() {
-    return logFilePath;
-}
 function appendToLogFile(level, args) {
     if (!logFilePath)
         return;