akm-cli 0.9.0-beta.4 → 0.9.0-beta.40

package/dist/core/config/config-schema.js

@@ -133,6 +133,34 @@ export const ImproveProcessConfigSchema = z
     // consolidation pass skips entirely (emits `pool_below_min_size`). 0 disables
     // the guard. Only meaningful on the `consolidate` process. Default 500.
     minPoolSize: z.number().int().min(0).optional(),
+    // Consolidate process: deterministic near-duplicate dedup pre-pass (#617).
+    // A cheap, no-LLM fast path that collapses obvious duplicates (`.derived`
+    // origin pairs + content twins) before the LLM consolidation. Default OFF
+    // — when absent the consolidate pass behaves byte-identically to today.
+    // `cosineThreshold` is a strict floor in [0, 1] (default 0.97) for the
+    // optional embedding-similarity match; exact normalized content-hash
+    // equality always collapses regardless of the threshold. Only meaningful
+    // on the `consolidate` process.
+    dedup: z
+        .object({
+        enabled: z.boolean().optional(),
+        cosineThreshold: z.number().min(0).max(1).optional(),
+        // WS-3a: maximum pool size for the O(n²) cosine-similarity twin compare.
+        // Only the first `cosineCandidateLimit` memories are cosine-compared;
+        // exact-hash matches still run over the full pool. Default 500. Raise
+        // with care — cost is O(n²).
+        cosineCandidateLimit: z.number().int().positive().optional(),
+    })
+        .strict()
+        .optional(),
+    // Consolidate process: judged-state cache (#581). When enabled, a memory
+    // whose current content hash equals its cached judged hash is SKIPPED from
+    // the LLM pool (judged-unchanged → no re-judge), letting one run sweep the
+    // whole corpus at O(changed/new) cost instead of narrowing to a recent
+    // time-window slice. Default OFF — when absent the consolidate pass behaves
+    // byte-identically to today (the incrementalSince path is unaffected). Only
+    // meaningful on the `consolidate` process.
+    judgedCache: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     qualityGate: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     contradictionDetection: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     // Extract process config (only meaningful for extract process)
@@ -144,18 +172,178 @@ export const ImproveProcessConfigSchema = z
     // on the `extract` process.
     minContentChars: z.number().int().min(0).optional(),
     maxChunkSize: z.number().int().min(1).max(50).optional(),
+    // Consolidate process: narrow candidate pool to memories modified within
+    // this duration window plus their graph neighbours. Only meaningful on
+    // the `consolidate` process. Absent = full-pool sweep.
+    incrementalSince: z.string().optional(),
+    // Consolidate process: hard cap on memories processed per pass.
+    // Reflect/distill: max refs processed (same as profile-level `limit`).
+    limit: positiveInt.optional(),
+    // Consolidate process: graph neighbours per changed memory during
+    // incremental consolidation. Default 5. Only meaningful with incrementalSince.
+    neighborsPerChanged: z.number().int().min(1).optional(),
+    // Distill process: skip distill entirely when reflect produced zero planned refs.
+    requirePlannedRefs: z.boolean().optional(),
+    // proactiveMaintenance process (Layer 2): staleness gate + rotation cooldown
+    // in days (default 30). Only meaningful on `proactiveMaintenance`.
+    dueDays: z.number().int().min(0).optional(),
+    // proactiveMaintenance process: top-N bound per run (default 25). Alias for
+    // `limit`; `maxPerRun` wins when both are set.
+    maxPerRun: positiveInt.optional(),
+    // graphExtraction process (#624 P2): when set, rank eligible files by
+    // utility_scores DESC and process only the top-N per run (incremental
+    // high-signal-first sweep). Unset = process all eligible (current
+    // behavior). Only meaningful on `graphExtraction`.
+    topN: positiveInt.optional(),
+    // MemoryInference process: minimum pending memory count to run the pass.
+    minPendingCount: z.number().int().min(0).optional(),
     // Extract process: minimum number of new (unseen, in-window) candidate
     // sessions below which the extract pass skips entirely (emits an
     // `improve_skipped` event with `reason: "below_min_new_sessions"`). 0
     // disables the guard. Only meaningful on the `extract` process. Default 0
     // (disabled) so existing behaviour is preserved; only opted-in profiles set it.
     minNewSessions: z.number().int().min(0).optional(),
+    // Extract process: cap on NEW sessions processed (LLM-called) per run; the
+    // rest roll to the next run (still unseen). 0 disables. Absent = default 25.
+    maxSessionsPerRun: z.number().int().min(0).optional(),
     // #561 — index agent sessions as a searchable `session` asset (extract
     // process). Absent = on-when-an-LLM-is-available (fail-open when offline).
+    // COST: when on, each processed session makes a SECOND LLM call (the session
+    // summary) on top of the extraction call — i.e. ~2 LLM calls/session. Set to
+    // false to halve per-session extract cost at the price of unsearchable
+    // sessions. (Unchanged/skip sessions still cost zero — the content-hash
+    // ledger gates both calls upstream.)
     indexSessions: z.boolean().optional(),
     // #561 — minimum session duration in minutes for session indexing. 0
     // disables the gate. Absent = default 5. Only meaningful on `extract`.
     minSessionDuration: z.number().min(0).optional(),
+    // Consolidate process: fallback p90 wall-clock time per consolidation chunk
+    // in seconds, used for cold-start budget estimation when no telemetry
+    // history exists. The actual p90 is derived from observed run durations
+    // once sufficient history accumulates; this value is only used on the very
+    // first run. Default 30 s. Only meaningful on the `consolidate` process.
+    p90ChunkSecondsDefault: z.number().finite().positive().optional(),
+    // WS-3b: Homeostatic demotion (step 0a). Before any LLM merge, demote
+    // retrievalSalience for stale/low-value assets so the merge pool is bounded
+    // and high-SNR. Demotion is state.db-only (file content untouched);
+    // re-promotable on re-retrieval. Default OFF. Only meaningful on the
+    // `consolidate` process.
+    homeostaticDemotion: z
+        .object({
+        enabled: z.boolean().optional(),
+        // Minimum days since last retrieval to consider an asset stale (default 30).
+        staleDays: z.number().int().min(0).optional(),
+        // Demotion factor: multiply retrievalSalience by this when stale (default 0.5).
+        demotionFactor: z.number().min(0).max(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Schema-similarity gate (step 0b). At intake, if a new candidate's
+    // body embedding is within epsilon of an existing derived-layer lesson/knowledge
+    // node, mark it schema-consistent and lower its priority. Default OFF.
+    // Only meaningful on the `consolidate` and `extract` processes.
+    schemaSimilarity: z
+        .object({
+        enabled: z.boolean().optional(),
+        // Epsilon: cosine similarity threshold above which a candidate is schema-consistent
+        // (default 0.85 — looser than dedup's 0.97 since we want to catch conceptual overlap).
+        epsilon: z.number().min(0).max(1).optional(),
+        // Multiplicative factor applied to candidate confidence when schema-consistent.
+        // Default 0.5 — halves the confidence so schema-consistent candidates are less likely
+        // to pass the quality gate and create redundant stash entries.
+        confidencePenalty: z.number().min(0).max(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Hot-probation intake buffer (step 0c, #604). New system-generated
+    // extractions enter captureMode: hot-probation and spend ONE consolidation
+    // cycle in probation. Dedup + quality second-pass runs before promotion.
+    // Default OFF. Only meaningful on the `extract` process.
+    hotProbation: z
+        .object({
+        enabled: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Anti-collapse guards (step 8). Prevents the consolidation pipeline
+    // from collapsing too aggressively and losing diversity.
+    //   - maxGeneration: refuse to merge two assets both above this generation (default 2).
+    //   - lexicalDiversityCheck: low n-gram diversity ⇒ raise merge threshold.
+    //   - randomClusterFraction: occasional random (non-similar) cluster in pool (default 0.05).
+    // Default OFF. Only meaningful on the `consolidate` process.
+    antiCollapse: z
+        .object({
+        enabled: z.boolean().optional(),
+        maxGeneration: z.number().int().min(1).optional(),
+        lexicalDiversityCheck: z.boolean().optional(),
+        randomClusterFraction: z.number().min(0).max(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: CLS (Complementary Learning System) interleaving (step 9).
+    // distill/memoryInference prompts include embedding-retrieved existing adjacent
+    // lessons/knowledge to prevent catastrophic interference with prior generalizations.
+    // Default OFF. Only meaningful on `distill` and `memoryInference` processes.
+    cls: z
+        .object({
+        enabled: z.boolean().optional(),
+        // Number of adjacent lessons/knowledge to include in prompts (default 3).
+        adjacentCount: z.number().int().min(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Distill→source fidelity check (step 10). After a distill proposal,
+    // check it against its cited source memories; a contradiction flag forces
+    // human review. Default OFF. Only meaningful on `distill` process.
+    fidelityCheck: z
+        .object({
+        enabled: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
+    // #609 — recombine process: minimum related-memory cluster size before an
+    // LLM generalization call. Default 3. Only meaningful on `recombine`.
+    minClusterSize: z.number().int().min(2).optional(),
+    // #609 — recombine process: hard cap on clusters processed per run (one
+    // bounded LLM call each). Default 5. Only meaningful on `recombine`.
+    maxClustersPerRun: positiveInt.optional(),
+    // #632 — recombine process: max members a cluster may contain before it is
+    // SKIPPED (drops bland over-broad buckets). When set, largest-first ranking
+    // no longer starves tighter clusters. Default UNSET = no cap. Only
+    // meaningful on `recombine`.
+    maxClusterSize: positiveInt.optional(),
+    // #632 — recombine process: tag values that must never form a tag cluster
+    // (generic project-wide tags). Default UNSET/[]. Only meaningful on
+    // `recombine`.
+    excludeTags: z.array(z.string().min(1)).optional(),
+    // #609 — recombine process: relatedness signal used to form clusters
+    // (tags | graph | both). Clustering is by relatedness, never embedding
+    // similarity. Default "tags". Only meaningful on `recombine`.
+    relatednessSource: z.enum(["tags", "graph", "both"]).optional(),
+    // #609 — recombine process: consecutive re-inductions required before a
+    // hypothesis is promoted to a lesson. Default 2. Only meaningful on
+    // `recombine`.
+    confirmThreshold: z.number().int().min(1).optional(),
+    // #615 — procedural process: minimum number of distinct assets sharing the
+    // same successful normalized ordered-action sequence before it is compiled
+    // into a workflow proposal. Default 3. Only meaningful on `procedural`.
+    minRecurrence: z.number().int().min(2).optional(),
+    // #615 — procedural process: hard cap on workflow proposals emitted per run
+    // (one bounded LLM call each). Default 3. Only meaningful on `procedural`.
+    maxProposalsPerRun: positiveInt.optional(),
+    // #615 — procedural process: asset type a compiled sequence is emitted as.
+    // Reserved; v1 always emits "workflow". Only meaningful on `procedural`.
+    emitAs: z.enum(["workflow", "skill"]).optional(),
+    // #639 — semantic value-floor filter for the `reflect` process. When
+    // enabled, proposals classified as "low-value" by the deterministic noise
+    // gate are deferred. DEFAULT OFF (absent / { enabled: false } = pre-#639
+    // byte-identical behaviour). Only meaningful on the `reflect` process.
+    lowValueFilter: z.object({ enabled: z.boolean().optional() }).strict().optional(),
+    // #641 — procedural-aware floor for the `extract` process triage gate.
+    // When true, a session must have markers>=1 OR editCommit>=0.5 to pass, even
+    // if score>=minScore. DEFAULT OFF (absent/false = pre-#641 byte-identical).
+    // Only meaningful on the `extract` process when triage is also enabled.
+    proceduralAwareFloor: z.boolean().optional(),
     // Triage process config (only meaningful for the `triage` process)
     applyMode: z.enum(["queue", "promote"]).optional(),
     policy: z.string().min(1).optional(),
@@ -181,6 +369,9 @@ const ImproveProfileProcessesSchema = z
     graphExtraction: ImproveProcessConfigSchema.optional(),
     validation: ImproveProcessConfigSchema.optional(),
     triage: ImproveProcessConfigSchema.optional(),
+    proactiveMaintenance: ImproveProcessConfigSchema.optional(),
+    recombine: ImproveProcessConfigSchema.optional(),
+    procedural: ImproveProcessConfigSchema.optional(),
 })
     .passthrough()
     .superRefine((val, ctx) => {
@@ -204,6 +395,9 @@ const ImproveProfileProcessesSchema = z
         "validation",
         "extract",
         "triage",
+        "proactiveMaintenance",
+        "recombine",
+        "procedural",
     ]);
     for (const k of Object.keys(raw)) {
         if (!allowed.has(k)) {
@@ -221,6 +415,16 @@ export const ImproveProfileConfigSchema = z
     processes: ImproveProfileProcessesSchema.optional(),
     autoAccept: nonNegativeNumber.optional(),
     limit: positiveInt.optional(),
+    // #616 — bounded multi-cycle phasing. Number of prep->loop->post-loop
+    // cycles per run. positiveInt forbids 0/negative. DEFAULT 1 => byte-identical
+    // single-pass behavior.
+    maxCycles: positiveInt.optional(),
+    // #614 — symmetric valence weighting in the eligibility sort. When true,
+    // the attention term becomes |valence| MAGNITUDE so BOTH strong positive
+    // and strong negative feedback drive attention (utility stays dominant) and
+    // strong-signed assets are routed to a fix/reinforce lane. DEFAULT OFF —
+    // false/absent preserves the legacy negative-only ranking byte-for-byte.
+    symmetricValence: z.boolean().optional(),
     sync: z
         .object({
         enabled: z.boolean().optional(),
@@ -337,6 +541,7 @@ const SearchGraphBoostSchema = z
 export const SearchConfigSchema = z
     .object({
     minScore: nonNegativeNumber.optional(),
+    defaultExcludeTypes: z.array(nonEmptyString).optional(),
     curateRerank: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     graphBoost: SearchGraphBoostSchema.optional(),
 })
@@ -355,10 +560,74 @@ const ImproveUtilityDecaySchema = z
     feedbackStabilityBoost: z.number().finite().min(1).optional(),
 })
     .strict();
+// #612 / WS-4 — auto-accept gate calibration + bounded, opt-in per-phase
+// threshold auto-tune. DEFAULT OFF: when absent (or `autoTune: false`) no
+// tuning occurs, so the gate behaves byte-identically to today.
+// WS-4 adds: per-phase persistence (state.db) + auto-tune ceiling default 85.
+const ImproveCalibrationSchema = z
+    .object({
+    /** Master switch for the bounded threshold auto-tune. Default false (parity). */
+    autoTune: z.boolean().optional(),
+    /** Lower bound (0-100) the tuned threshold may never drop below. */
+    minThreshold: z.number().int().min(0).max(100).optional(),
+    /**
+     * Upper bound (0-100) the tuned threshold may never rise above.
+     * WS-4 default: 85 (prevents gate converging to pure exploitation).
+     */
+    maxThreshold: z.number().int().min(0).max(100).optional(),
+    /** Maximum adjustment magnitude (points) applied in one tune step. */
+    maxStep: positiveInt.optional(),
+    /** Minimum acted-on sample count required before any adjustment. */
+    minSamples: nonNegativeNumber.optional(),
+    /** Target realized accept rate in [0, 1]. Default 0.9. */
+    targetAcceptRate: z.number().finite().min(0).max(1).optional(),
+})
+    .strict();
+// WS-4 — exploration budget: a fixed fraction of proposals accepted per run
+// regardless of confidence. DEFAULT OFF.
+const ImproveExplorationSchema = z
+    .object({
+    /**
+     * Enable the exploration budget lane. Default false (parity).
+     * When true, a fraction of proposals are accepted regardless of confidence.
+     */
+    enabled: z.boolean().optional(),
+    /**
+     * Fraction of proposals per run to accept as exploration [0, 1].
+     * Default 0.05 (5%). Clamped to [0, 1] at read time.
+     */
+    budgetFraction: z.number().finite().min(0).max(1).optional(),
+})
+    .strict();
+const ImproveSalienceSchema = z
+    .object({
+    /**
+     * WS-2 Part-V gate: enable the outcome-weight term in the salience projection.
+     * Default false (parity — WS-1 weights w_e=0.30, w_r=0.70 until Part-V confirms
+     * no regression). Set to true after running scripts/akm-eval + health report.
+     */
+    outcomeWeightEnabled: z.boolean().optional(),
+    /**
+     * Minimum encoding salience score [0, 1] for a zero-feedback asset to be
+     * admitted to the high-salience improve lane (#608).
+     * Default 0.75. Set to 1.0 to disable the lane entirely.
+     */
+    salienceThreshold: z.number().min(0).max(1).optional(),
+    /**
+     * Per-run additive replay budget (#610). Up to this many top-salience refs are
+     * revisited even with no reactive signal and regardless of cooldown. Additive
+     * on top of --limit. Default 0 = no replay.
+     */
+    replayBudget: z.number().int().min(0).optional(),
+})
+    .strict();
 export const ImproveConfigSchema = z
     .object({
     utilityDecay: ImproveUtilityDecaySchema.optional(),
     eventRetentionDays: nonNegativeNumber.optional(),
+    calibration: ImproveCalibrationSchema.optional(),
+    exploration: ImproveExplorationSchema.optional(),
+    salience: ImproveSalienceSchema.optional(),
 })
     .strict();
 // ── Index / per-pass ────────────────────────────────────────────────────────
@@ -372,6 +641,7 @@ const GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED = [
     "lesson",
     "task",
     "wiki",
+    "fact",
 ];
 const INDEX_PASS_PROVIDER_KEYS = new Set([
     "endpoint",
@@ -388,6 +658,7 @@ const INDEX_PASS_KNOWN_KEYS = new Set([
     "graphExtractionBatchSize",
     "graphExtractionIncludeTypes",
     "memoryInferenceBatchSize",
+    "lazyGraphExtraction",
 ]);
 /**
  * Per-pass `index.<pass>` entry. Uses preprocess + manual validation so we can
@@ -414,8 +685,8 @@ export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: `Unknown key \`${[...(ctx.path ?? []), key].join(".")}\`. Per-pass entries support \`llm\` ` +
-                    "(boolean opt-out), `graphExtractionBatchSize`, `graphExtractionIncludeTypes`, and " +
-                    "`memoryInferenceBatchSize`.",
+                    "(boolean opt-out), `graphExtractionBatchSize`, `graphExtractionIncludeTypes`, " +
+                    "`memoryInferenceBatchSize`, and `lazyGraphExtraction`.",
             });
             return raw;
         }
@@ -434,6 +705,7 @@ export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
     graphExtractionBatchSize: positiveInt.optional(),
     graphExtractionIncludeTypes: z.array(z.enum(GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED)).nonempty().optional(),
     memoryInferenceBatchSize: positiveInt.optional(),
+    lazyGraphExtraction: z.boolean().optional(),
 })
     .passthrough());
 const MetadataEnhanceSchema = z.object({ enabled: z.boolean().optional() }).strict();

package/dist/core/config/config.js

@@ -249,8 +249,8 @@ function maybeAutoMigrateConfigFile(configPath, text) {
             "  to preview a dry-run diff:            akm config migrate --dry-run --print-diff",
             "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
         ].join("\n");
-        process.stderr.write(`${banner}\n`);
-        process.stdout.write(`${banner}\n`);
+        process.stderr?.write?.(`${banner}\n`);
+        process.stdout?.write?.(`${banner}\n`);
     }
     catch (err) {
         // #461: never return migrated bytes when disk write fails — that triggers

package/dist/core/logs-db.js

@@ -39,6 +39,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 import { getDataDir } from "./paths.js";
 import { getStateDbPath } from "./state-db.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
@@ -75,9 +76,9 @@ export function openLogsDatabase(dbPath) {
         fs.mkdirSync(dir, { recursive: true });
     }
     const db = openDatabase(resolvedPath);
-    // PRAGMAs must run before any DDL or DML.
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA busy_timeout = 30000");
+    // PRAGMAs must run before any DDL or DML. foreignKeys:false preserves this
+    // opener's historical behaviour — logs.db has never enforced foreign keys.
+    applyStandardPragmas(db, { dataDir: dir, foreignKeys: false });
     runMigrations(db);
     return db;
 }

package/dist/core/paths.js

@@ -215,6 +215,9 @@ export function getDataDir(env = process.env, platform = process.platform) {
 export function getDbPath() {
     return path.join(getDataDir(), "index.db");
 }
+export function getIndexWriterLockPath() {
+    return path.join(getDataDir(), "index.db.write.lock");
+}
 export function getWorkflowDbPath() {
     return path.join(getDataDir(), "workflow.db");
 }

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

@@ -0,0 +1,87 @@
+// 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/.
+/**
+ * Dispatch resolver for the standards prompt seam — selects which of the two
+ * standards features fires for a given write target, mutually exclusively:
+ *
+ *   - **Feature A — wiki schema**: the target is a wiki page (a ref/path under
+ *     `wikis/<name>/`, NOT a `raw/` file and NOT a wiki infra file
+ *     `schema.md`/`index.md`/`log.md`). Returns that wiki's `schema.md` body.
+ *   - **Feature B — stash standards**: the target is any non-wiki asset.
+ *     Returns the concatenated `category: convention`/`meta` fact bodies.
+ *   - **Neither fires**: a wiki `raw/` file or a wiki infra file. Returns `""`.
+ *
+ * The two NEVER both fire. Both underlying readers degrade to `""` on
+ * missing/malformed input and never throw, so this resolver never throws.
+ */
+import { extractWikiNameFromRef, INDEX_MD, LOG_MD, loadWikiSchema, SCHEMA_MD } from "../../wiki/wiki.js";
+import { resolveStashStandards } from "./resolve-stash-standards.js";
+import { resolveTypeConventions, typeConventionRef } from "./resolve-type-conventions.js";
+/** Wiki infra files that are not authored pages (relative to the wiki root). */
+const WIKI_INFRA_BASENAMES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
+/**
+ * Extract the asset type from a canonical ref (`[origin//]type:name`) without
+ * throwing. Returns `undefined` for refs that have no `type:` prefix. Kept local
+ * and lenient — the per-type resolver validates the result against
+ * `getAssetTypes()`, so a bogus prefix here simply yields no convention.
+ */
+function refType(ref) {
+    if (!ref)
+        return undefined;
+    const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
+    const colon = body.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    return body.slice(0, colon).trim() || undefined;
+}
+/**
+ * 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`,
+ *                  `wiki:research/topics/x`). When undefined, the target is a
+ *                  non-wiki authoring flow → stash standards.
+ * @param stashRoot Stash root directory.
+ */
+export function resolveStandardsContext(ref, stashRoot) {
+    const wikiName = ref ? extractWikiNameFromRef(ref) : undefined;
+    if (!wikiName) {
+        // Non-wiki asset target → Feature B (general stash standards) plus the
+        // per-type SOFT conventions layer (#646), type-scoped to the write target.
+        const general = resolveStashStandards(stashRoot);
+        const type = refType(ref);
+        // A non-empty body here guarantees `type` is a `getAssetTypes()`-validated
+        // string (the resolver returns "" otherwise).
+        const typeConventions = type ? resolveTypeConventions(stashRoot, type) : "";
+        if (!typeConventions || !type)
+            return general;
+        // Soft, type-scoped guidance — clearly labeled and kept separate from the
+        // HARD (validator-enforced) rules that `authoringRulesForType` injects
+        // downstream. These facts are advice only; they never weaken the gate.
+        const softSection = [
+            `# ${typeConventionRef(type)} (soft per-type conventions — guidance, not enforced)`,
+            typeConventions,
+        ].join("\n");
+        return general ? `${general}\n\n${softSection}` : softSection;
+    }
+    // Wiki target. Extract the page path after `wiki:<name>/`.
+    const prefix = `wiki:${wikiName}/`;
+    const pagePath = ref?.startsWith(prefix) ? ref.slice(prefix.length) : "";
+    // `wiki:<name>` with no page, a `raw/` file, or a wiki infra file → neither
+    // feature fires.
+    if (!pagePath)
+        return "";
+    if (pagePath === "raw" || pagePath.startsWith("raw/"))
+        return "";
+    // Infra files (`schema`/`index`/`log`) are only special at the WIKI ROOT.
+    // A nested page like `wiki:research/analysis/schema` is a genuine page and
+    // must NOT be suppressed, so only check when the page is at root depth.
+    if (!pagePath.includes("/")) {
+        // Refs drop the `.md` extension; compare against both forms defensively.
+        if (WIKI_INFRA_BASENAMES.has(pagePath) || WIKI_INFRA_BASENAMES.has(`${pagePath}.md`)) {
+            return "";
+        }
+    }
+    // A genuine wiki page → Feature A (that wiki's schema body).
+    return loadWikiSchema(stashRoot, wikiName).body;
+}

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

@@ -0,0 +1,99 @@
+// 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/.
+/**
+ * Resolve the stash-authoring "standards" context (Feature B of the standards
+ * plan): gather the bodies of `fact` assets whose `category` frontmatter is
+ * `convention` or `meta` so naming / tag / frontmatter conventions are surfaced
+ * to the agent when it creates or edits a non-wiki asset.
+ *
+ * Selection is by **frontmatter `category`**, never by path — flat
+ * (`facts/x.md`) and nested (`facts/conventions/x.md`) layouts resolve
+ * identically. The MVP does no parsing of fenced blocks, no rule objects, and
+ * no warnings: it concatenates the selected facts' bodies in stable enumeration
+ * order, each preceded by a one-line `# <ref>` provenance header. Returns `""`
+ * when no matching facts exist.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../asset/frontmatter.js";
+/** `category` values that mark a fact as an authoring standard. */
+const STANDARD_CATEGORIES = new Set(["convention", "meta"]);
+/** Directory (under the stash root) where `fact` assets live. */
+const FACTS_SUBDIR = "facts";
+/**
+ * Per-type SOFT convention facts (`facts/conventions/assets/<type>.md`, #646)
+ * are surfaced **type-scoped** through `resolveTypeConventions`, so they must
+ * NOT leak into this un-type-scoped general layer (authoring a `command` must
+ * not pull the `skill` convention). Excluded by relative path (POSIX form).
+ */
+const TYPE_CONVENTIONS_REL = "conventions/assets/";
+/**
+ * Recursively collect `.md` files under `dir` in stable (sorted) enumeration
+ * order. Returns absolute paths. Missing dir → `[]`.
+ */
+function collectMarkdownFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectMarkdownFiles(full));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Derive a fact ref (`fact: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}`;
+}
+export function resolveStashStandards(stashRoot) {
+    const factsRoot = path.join(stashRoot, FACTS_SUBDIR);
+    const sections = [];
+    for (const absPath of collectMarkdownFiles(factsRoot)) {
+        // Per-type SOFT conventions are delivered type-scoped (#646); skip them
+        // here so they never leak un-type-scoped into every authoring flow.
+        const relPosix = path.relative(factsRoot, absPath).split(path.sep).join("/");
+        if (relPosix.startsWith(TYPE_CONVENTIONS_REL))
+            continue;
+        let raw;
+        try {
+            raw = fs.readFileSync(absPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let category = "";
+        let body = "";
+        try {
+            const parsed = parseFrontmatter(raw);
+            category = typeof parsed.data.category === "string" ? parsed.data.category.trim() : "";
+            body = parsed.content;
+        }
+        catch {
+            continue;
+        }
+        if (!STANDARD_CATEGORIES.has(category))
+            continue;
+        const trimmed = body.trim();
+        if (!trimmed)
+            continue; // skip stub facts with frontmatter but no body
+        sections.push(`# ${toFactRef(factsRoot, absPath)}\n${trimmed}`);
+    }
+    return sections.join("\n\n");
+}

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

@@ -0,0 +1,66 @@
+// 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/.
+/**
+ * Resolve **per-type SOFT authoring conventions** (#646) — the third and final
+ * authoring-guidance layer:
+ *
+ *   1. HARD rules (validator-rejecting, code-sourced) → `authoringRulesForType()`
+ *      (`src/core/authoring-rules.ts`, #645). Never editable; the gate enforces them.
+ *   2. General stash standards (cross-type naming/tag conventions) →
+ *      `resolveStashStandards()` `category: convention|meta` facts (#642).
+ *   3. **Per-type SOFT conventions** (voice, structure, length *preference* for
+ *      *this* asset type) → user-editable `facts/conventions/assets/<type>.md`
+ *      (THIS module). Augments the built-in `TYPE_HINTS` fallback for display.
+ *
+ * These facts are **soft only** — advice, not contract. They MUST NOT carry
+ * hard, validator-rejecting rules: a user editing or deleting one must never be
+ * able to weaken the authoring contract the gate enforces (#645 boundary).
+ *
+ * Selection is by a `getAssetTypes()`-validated basename: only
+ * `facts/conventions/assets/<known-type>.md` resolves. Read directly from disk
+ * (no index rebuild); any missing dir/file, unknown type, or read error degrades
+ * to `""` and never throws.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getAssetTypes } from "../asset/asset-spec.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`. */
+export function typeConventionRef(type) {
+    return `fact:conventions/assets/${type}`;
+}
+/**
+ * Read the SOFT authoring-convention body for asset type `type`, if a stash
+ * owner has authored `facts/conventions/assets/<type>.md`.
+ *
+ * @returns the trimmed markdown body (frontmatter stripped), or `""` when the
+ *          type is unknown, the file is absent, or anything goes wrong.
+ */
+export function resolveTypeConventions(stashRoot, type) {
+    if (!stashRoot || !type)
+        return "";
+    // Basename MUST be a known asset type — never resolve an arbitrary file.
+    if (!getAssetTypes().includes(type))
+        return "";
+    const abs = path.join(stashRoot, TYPE_CONVENTIONS_SUBDIR, `${type}.md`);
+    let raw;
+    try {
+        raw = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return ""; // missing dir/file or read error → degrade to empty
+    }
+    let body = "";
+    try {
+        body = parseFrontmatter(raw).content;
+    }
+    catch {
+        // Malformed frontmatter: fall back to the whole file (parseFrontmatter
+        // normally returns whole content as body, but guard defensively).
+        body = raw;
+    }
+    return body.trim();
+}