@lmzhen/dsh-evolution-core 0.17.1 → 0.18.0

package/lib/types/errors.d.ts

@@ -33,7 +33,6 @@ export declare const EVOLUTION_ERRORS: Readonly<{
     readonly 'e-309-revision-conflict-you-sent': "E-309: revision conflict — you sent %a1%, the document stands at %a2%. Re-read with /evolution params --json and retry.";
     readonly 'e-309-revision-conflict-message-Re': "E-309: revision conflict — %a1%. Re-read with /evolution params --json and retry.";
     readonly 'e-310-the-settings-service-refused': "E-310: the settings service refused the write: %a1% — the owning plugin's rule stands (a cross-field pair, or a cap that may only be tightened). /evolution params shows the current value.";
-    readonly 'e-305-this-invocation-carries-no-2': "E-305: this invocation carries no agent — `%a1%` needs a session-backed call (run it from a session in the GUI or the CLI).";
     readonly 'e-317-skill-write-not-confirmed': "E-317: skill \"%a1%\" was not %a2% — the confirmation prompt was declined or dismissed, so nothing was written. The prompt appears on every create and bare delete; repeat the call only if the operator asks for it.";
     readonly 'e-318-skill-write-without-a-read': "E-318: skill \"%a1%\" was not read in this session, so this write is refused. Read it with the `skill` tool first (a read that failed does not count), then repeat the write.";
     readonly 'e-320-the-profile-home-is-not': "E-320: the profile home is not reported by this host, so the legacy settings document cannot be located. /evolution migrate reads `<profile home>/settings.yaml.imported`; run it from a profile-launched session.";

package/lib/types/events.d.ts

@@ -85,14 +85,39 @@ interface EvolutionReviewErrorEvent {
 }
 declare module '@deepseek-ai/cordis' {
     interface Events {
+        /**
+         * A review was scheduled and delivered on some channel. An ANNOUNCEMENT: consumers observe
+         * that the cadence fired, they do not decide anything (A98 / O-1).
+         * @param event - the scheduled review: owning session, kind, the turn's counts, delivery channel.
+         * @mode emit
+         */
         'evolution/review-scheduled'(event: EvolutionReviewScheduledEvent): void;
+        /**
+         * A reviewed plan finished its write leg, with the counts that describe what landed. An
+         * ANNOUNCEMENT: the family's own ledger of plan outcomes (A98 / O-1).
+         * @param event - the outcome counts, the first failure message, and the policy fingerprint.
+         * @mode emit
+         */
         'evolution/plan-applied'(event: EvolutionPlanAppliedEvent): void;
+        /**
+         * One skill mutation landed (the cache-invalidation signal every catalog consumer reads). An
+         * ANNOUNCEMENT: it names what changed, it decides nothing (A98 / O-1).
+         * @param event - the action, the skill name, and the file for support-file operations.
+         * @mode emit
+         */
         'evolution/skill-mutated'(event: EvolutionSkillMutatedEvent): void;
         /** 0.3.18 (E-71): explicit catalog refresh request (`/evolution skills
          * refresh`). Out-of-band tree edits (manual, git) may bypass the mutation
          * event; listeners drop caches and invalidate downstream catalogs. No
-         * payload — it is a bare "re-read" signal, never a mutation record. */
+         * payload — it is a bare "re-read" signal, never a mutation record.
+         * @mode emit */
         'evolution/skills-refresh'(): void;
+        /**
+         * A review pipeline failure was caught (never an unhandled rejection). An ANNOUNCEMENT for
+         * operators and observability — the reason is already logged by the emitter (A98 / O-1).
+         * @param event - the session whose review pipeline failed.
+         * @mode emit
+         */
         'evolution/review-error'(event: EvolutionReviewErrorEvent): void;
     }
 }

package/lib/types/fold-untrusted.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Untrusted text rendered as prompt lines (T3-03/A31) — ONE folding rule.
+ *
+ * The background-review digest embeds conversation text and tool output into a
+ * plain-text prompt whose PRODUCT is a plan with write permission. Anything the
+ * session ingested (a fetched page, a file body, command output) can therefore
+ * carry a newline plus a line shaped like the prompt's own structure — a
+ * `SYSTEM:`/`Review kind:` header, a `[result]` evidence line, a second copy
+ * of the closing instruction — and forge structure or inject instructions.
+ *
+ * FOLDING, not deleting: the reader (the model) must still SEE what the data
+ * said, it just must never become structure. Line separators become a visible
+ * `⏎`, and a line that would read as a role/evidence header gets a visible
+ * marker in front of it. Every original character stays in place.
+ *
+ * The boundary is the separator itself, not only a real newline: a payload can
+ * paste the separator verbatim, so neutralization matches after `⏎` whether it
+ * came from the fold or from the data. Both edits are idempotent (a second pass
+ * cannot add a second marker).
+ *
+ * Scope: text rendered as its OWN line(s) of a prompt. `render-facts`'
+ * sanitizer (evolution-maintenance) is the same posture for `key=value` fields
+ * and additionally escapes its block delimiter; it is not superseded here.
+ * @module @lmzhen/dsh-evolution-core
+ */
+/** Visible stand-in for a folded line separator: one character that cannot be read as line structure. */
+export declare const UNTRUSTED_LINE_BREAK = " \u23CE ";
+/** Visible marker prefixed to a line that would otherwise read as a role/structure header. */
+export declare const UNTRUSTED_LINE_MARK = "\u00B7 ";
+/**
+ * Fold untrusted `text` so it cannot become structure, then bound it to `limit`
+ * visible characters. A non-positive `limit` means "no truncation".
+ */
+export declare function foldUntrustedLines(text: string, limit: number): string;
+//# sourceMappingURL=fold-untrusted.d.ts.map

package/lib/types/index.d.ts

@@ -14,9 +14,11 @@
  *
  * - **Cross-cutting basics** — `state-store.ts` (env roots — the single
  *   source of DSH-home semantics), `serial.ts`, `numeric.ts`, `constants.ts`,
- *   `mutations.ts`, `events.ts`, `gates.ts`, `errors.ts` (the error-code table).
+ *   `mutations.ts`, `events.ts`, `gates.ts`, `errors.ts` (the error-code table),
+ *   `payload.ts` (which of `facts`/`content` is the payload — one rule for the whole family).
  * - **Security primitives** — `threats.ts` (content threat scanner),
- *   `redact.ts` (credential masking at model boundaries). Consumers:
+ *   `redact.ts` (credential masking at model boundaries),
+ *   `fold-untrusted.ts` (untrusted text must not become prompt structure). Consumers:
  *   evolution-policy/threat, both stores, review, maintenance.
  * - **Core domain stores/logic** — `skill-store.ts` (skill tree engine +
  *   IO-seam consumer), `memory-store.ts`, `usage.ts`, `curator.ts`,
@@ -51,6 +53,7 @@ export * from './redact.ts';
 export * from './review-channel.ts';
 export * from './serial.ts';
 export * from './probe.ts';
+export * from './platform-services.ts';
 export * from './instance-scope.ts';
 export * from './write-inventory.ts';
 export * from './scope.ts';
@@ -73,4 +76,6 @@ export * from './params.ts';
 export * from './namespace-migration.ts';
 export * from './numeric.ts';
 export * from './opt-in.ts';
+export * from './payload.ts';
+export * from './fold-untrusted.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/memory-store.d.ts

@@ -9,8 +9,9 @@ export interface MemoryOperation {
     action: 'add' | 'replace' | 'remove';
     facts?: string | undefined;
     /** PLAN-R2 P2-6 (2026-09-16): the dsh-memory contract's alias. applyBatchCore
-     * reads `facts ?? content`, so a provider reusing this store directly can
-     * write the tool-memory schema shape without a normalization shim. */
+     * resolves the pair through core's `payloadText` (T3-06/A34), so a provider
+     * reusing this store directly can write the tool-memory schema shape without
+     * a normalization shim. */
     content?: string | undefined;
     old_text?: string | undefined;
 }

package/lib/types/namespace-migration.d.ts

@@ -98,7 +98,6 @@ export interface NamespaceMigrationDeps {
      */
     warn(message: string): void;
 }
-/**
 /** One row's pending write: the keys that row does not carry yet. */
 export interface NamespaceMigrationWrite {
     /** The row id. */

package/lib/types/numeric.d.ts

@@ -35,4 +35,24 @@ export declare function clampedNumber(value: number | undefined, fallback: numbe
     min?: number;
     max?: number;
 }): number;
+/**
+ * Clamp one numeric knob and warn ONCE per key.
+ *
+ * S2.9 (T3-10): `evolution-review` and `evolution-curator` each carried their own copy of this
+ * helper — their own once-per-key set and their own message — so the two settings readers of ONE
+ * policy row could drift apart. The logic lives here; each caller passes its own sink (and its own
+ * package prefix). A live field is read at every use, so the warning cannot be per-read.
+ *
+ * @param warned - the keys this caller already warned about.
+ * @param warn - the warning sink (each package prefixes its own name).
+ * @param name - the config key, for the warning.
+ * @param value - the value as supplied, or its volatile reference.
+ * @param fallback - the package default a corrected value falls back to.
+ * @param min - the smallest value the engine can act on.
+ * @param max - the largest value the carrier can hold, when bounded.
+ * @returns the value the engine may use.
+ */
+export declare function clampOnce(warned: Set<string>, warn: (message: string) => void, name: string, value: number | {
+    get(): number | undefined;
+} | undefined, fallback: number, min: number, max?: number): number;
 //# sourceMappingURL=numeric.d.ts.map

package/lib/types/params.d.ts

@@ -5,8 +5,9 @@
  * the SAME name in two carriers (reviewMode, staleAfterDays, archiveAfterDays —
  * resolved by the existing policy-shadows-row rule) and six use DIFFERENT names.
  * This module owns the six: the policy/snapshot name is the canonical id, the
- * plugin-row name is a deprecated alias kept readable for one minor version
- * (0.6.x) and removable in 0.7.0.
+ * plugin-row name is a deprecated alias kept readable since 0.6.x. Removal was
+ * planned for 0.7.0 and is deferred: the aliases still ship, so no later version
+ * is claimed here.
  *
  * Reading stays compatible (a carrier still spelling the legacy name resolves),
  * writing is strict (the write path accepts canonical ids only, so no new
@@ -163,6 +164,31 @@ export declare function paramSettingsId(owner: string): string | undefined;
  * @returns the entry id the platform reports for that row.
  * @throws when the owner publishes no user layer.
  */
+/** The keys the USER set in one row's settings namespace (G1 §8.4-A).
+ *
+ * The settings user layer is read in exactly ONE place, and it reads KEY NAMES, never values: the
+ * platform resolves the user layer into the row's live fields, so a value always comes from the
+ * row. The precedence rule (user > policy) needs to know WHICH keys the user set, or a deployment
+ * policy would silently override the user. S2.9 (T3-10): review and curator each had their own
+ * reader, so one key could be resolved two ways.
+ * @param ctx - the plugin context (a `get(name)` view is enough).
+ * @param rowId - the row's registry namespace (`paramRowId(<package>)`).
+ * @returns the keys present in that row's user layer.
+ */
+export declare function userSetKeys(ctx: {
+    get(name: string): unknown;
+}, rowId: string): ReadonlySet<string>;
+/** ONE key's effective value, in the design's precedence (G1 §8.4-A): the user layer (whose value
+ * already arrived through the row's live field) → the deployment policy snapshot → the row itself.
+ * S2.9 (T3-10): both readers of the policy row resolve through this, so a new key cannot get one
+ * answer on the review side and another on the curator side.
+ * @param userSet - the keys the user set (see {@link userSetKeys}).
+ * @param row - the row's live fields.
+ * @param snapshot - the deployment policy snapshot, when a policy row is mounted.
+ * @param key - the key being resolved.
+ * @returns the effective value.
+ */
+export declare function pickWithPolicy<R extends object, K extends keyof R & string>(userSet: ReadonlySet<string>, row: R, snapshot: Partial<Record<K, R[K]>> | undefined, key: K): R[K];
 export declare function paramRowId(owner: string): string;
 /**
  * Structural view of the platform settings provider: only the members the family

package/lib/types/payload.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The memory op's payload field, resolved in ONE place (T3-06/A34).
+ *
+ * A memory op carries its body under two names — `facts` (the original) and
+ * `content` (the schema alias) — and every reader used to resolve the pair with
+ * `op.facts ?? op.content`. `??` only skips null/undefined, so
+ * `{ facts: '', content: '正文' }` counted as "has facts": the plan validator
+ * refused the op as empty (a FALSE refusal of a payload that is right there),
+ * and the writers that normalized the pair dropped the body to `''`.
+ *
+ * The payload is the first field whose TRIMMED value is non-empty — a blank
+ * string carries no payload, so it yields to its alias. Both blank (or absent)
+ * ⇒ `''`, the one shape every caller already reads as "no payload".
+ *
+ * Non-string values are SKIPPED, never trimmed: a truthy non-string `facts`
+ * used to reach `.trim()` and throw a TypeError out of callers that promise to
+ * be deterministic (the E-60 / P2-1 class). The field-type gates reject such an
+ * op on their own; this helper must not be the one that throws.
+ *
+ * The union posture matches evolution-threat's E-28a scan (BOTH fields are
+ * scanned, not only the first truthy one); the two agree on what counts as
+ * provided.
+ * @module @lmzhen/dsh-evolution-core
+ */
+/** Anything carrying the two payload aliases; `null` (a persisted or garbage op) resolves to `''`. */
+export interface PayloadFields {
+    facts?: unknown;
+    content?: unknown;
+}
+/** The op's payload text: the first of `facts`/`content` whose trim is non-empty, trimmed; `''` when neither carries one. */
+export declare function payloadText(op: PayloadFields | null | undefined): string;
+//# sourceMappingURL=payload.d.ts.map

package/lib/types/platform-services.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Every platform service the family reaches for with `ctx.get`, and what degrades without it.
+ *
+ * O-2 (v46 audit): the family probes 26 platform services optionally — the platform has no
+ * formalized "optional dependency", so an ABSENT service is a silent downgrade and the diagnostic
+ * surface is the only place a reader can learn about it. `/evolution doctor` used to judge six of
+ * them; this table is the single source it judges the rest from, and the arch guard cross-checks it
+ * against the actual probe sites so a new `ctx.get` cannot stay undeclared.
+ *
+ * `side` decides who can judge it: `host` probes run in the plugin process (doctor judges those),
+ * `client` probes run in the browser half, where the host has no view of the seats.
+ * @module @lmzhen/dsh-evolution-core
+ */
+/** One platform service the family probes, with the feature that goes quiet without it. */
+export interface PlatformServiceProbe {
+    /** The service key as `ctx.get` spells it. */
+    readonly service: string;
+    /** The family feature that silently degrades when the service is absent. */
+    readonly feature: string;
+    /** Where the probe runs. */
+    readonly side: 'host' | 'client';
+}
+/** The 26 probes, in service-name order (the guard checks this list against the tree). */
+export declare const PLATFORM_SERVICE_PROBES: readonly PlatformServiceProbe[];
+/**
+ * The HOST-side probes that do not resolve in this runtime — what `/evolution doctor` prints as
+ * "capability absence". Empty is the normal, healthy answer: every capability the family can use
+ * is mounted, and the section stays away.
+ * @param has - a `ctx.get(name) !== undefined` probe of the running context.
+ * @returns the absent host-side probes, in declaration order.
+ */
+export declare function absentHostServices(has: (name: string) => boolean): PlatformServiceProbe[];
+//# sourceMappingURL=platform-services.d.ts.map

package/lib/types/probe.d.ts

@@ -52,10 +52,38 @@ export declare function isMissingPath(error: unknown): boolean;
  * `catch { return [] }` served a broken store as an empty one (the N14 class).
  */
 export declare function probeList(io: EvolutionIoLike, dir: string): Promise<Probe<string[]>>;
+/**
+ * Three-state TEXT read of one file. A missing path (ENOENT/ENOTDIR, or a backend whose read
+ * answers null) is `absent`; every other failure is `unknown` with its reason. The distinction is
+ * the whole point (N14/O-7): "I could not read this file" and "this file is not there" lead to
+ * opposite decisions once a write is about to replace the bytes — treating the first as the
+ * second is how a broken store reads as empty and a rescue copy never happens.
+ * @param io - the IO seam.
+ * @param path - the file to read.
+ * @returns the probe.
+ */
+export declare function probeText(io: EvolutionIoLike, path: string): Promise<Probe<string>>;
 /**
  * Three-state mtime read. Absent covers both "the path is missing" and "this
  * backend has no mtime probe" — the seam cannot tell those apart, so consumers
  * that must know say so in their own log line. A stat that FAILS is unknown.
  */
 export declare function probeMtime(io: EvolutionIoLike, path: string): Promise<Probe<number>>;
+/** The timestamp a curator run report DECLARES: `startedAt` (the run's own start), then `at` (the
+ * stamp the error writer sets on every report — F-327/P2-4).
+ * @param parsed - the parsed report, or anything else.
+ * @returns epoch milliseconds, or null when neither field carries a parseable time.
+ */
+export declare function declaredReportStamp(parsed: unknown): number | null;
+/** The time one curator run report is ordered by — ONE口径 for every reader (S2.9/T3-12): the
+ * declared stamp above, then the optional mtime probe as the fallback. `null` means "no usable
+ * time", and that single answer serves both consumers: such a report is never the LATEST (the
+ * panel) and is never DELETED (the retention sweep), which is exactly the pair of answers the two
+ * readers disagreed on when one ordered by the declared stamp and the other by mtime alone.
+ * @param io - the IO seam; a backend without `mtime` simply has no fallback.
+ * @param path - the report file the probe reads.
+ * @param parsed - the already-parsed report.
+ * @returns epoch milliseconds, or null.
+ */
+export declare function reportTime(io: EvolutionIoLike, path: string, parsed: unknown): Promise<number | null>;
 //# sourceMappingURL=probe.d.ts.map

package/lib/types/prompts.d.ts

@@ -3,8 +3,8 @@
  * changes semantically: the bundle digest is the fail-closed signal for
  * review workers, so a stale id across deployments must be distinguishable.
  */
-export declare const PROMPT_BUNDLE_VERSION = 20;
-export declare const PROMPT_BUNDLE_ID = "dsh-evolution@20";
+export declare const PROMPT_BUNDLE_VERSION = 21;
+export declare const PROMPT_BUNDLE_ID = "dsh-evolution@21";
 export declare const MEMORY_REVIEW_PROMPT = "[Auto-review \u2014 Memory]\nReview the conversation above and consider saving to memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?\n\nIf something stands out, save it using the memory tool.\nIf nothing is worth saving, just say \"Nothing to save.\" and stop.";
 export declare const SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills]\nReview the conversation above and update the skill library. Be ACTIVE \u2014 most sessions produce at least one skill update, even if small. A pass that does nothing is a missed learning opportunity, not a neutral outcome.\n\nTarget shape of the library: CLASS-LEVEL skills, each with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. This shapes HOW you update, not WHETHER you update.\n\nSignals to look for (any one of these warrants action):\n  \u2022 User corrected your style, tone, format, legibility, or verbosity. Frustration signals like 'stop doing X', 'this is too verbose', 'don't format like this', 'why are you explaining', 'just give me the answer', 'you always do Y and I hate it', or an explicit 'remember this' are FIRST-CLASS skill signals, not just memory signals. Update the relevant skill(s) to embed the preference so the next session starts already knowing.\n  \u2022 User corrected your workflow, approach, or sequence of steps. Encode the correction as a pitfall or explicit step in the skill that governs that class of task.\n  \u2022 Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.\n  \u2022 A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.\n\nRead-before-write: update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session. On the plan channel ops on unread skills are rejected; direct writes have no such guard, so treat the rule as binding. CREATE of a brand-new umbrella is the only exception.\n\nPreference order \u2014 prefer the earliest action that fits, but do pick one when a signal above fired:\n  1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded or you read. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.\n  2. UPDATE AN EXISTING UMBRELLA. If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger.\n  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files \u2014 use the right directory per kind:\n     \u2022 references/<topic>.md \u2014 session-specific detail (error transcripts, reproduction recipes, provider quirks) AND condensed knowledge banks: quoted research, API docs, external authoritative excerpts, or domain notes you found while working on the problem. Write it concise and for the value of the task, not as a full mirror of upstream docs.\n     \u2022 templates/<name>.<ext> \u2014 starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can reproduce with modifications).\n     \u2022 scripts/<name>.<ext> \u2014 statically re-runnable actions the skill can invoke directly (verification scripts, fixture generators, deterministic probes, anything the agent should run rather than hand-type each time).\n     Add support files via skill_manage action=write_file with file_path starting 'references/', 'templates/', or 'scripts/'. The umbrella's SKILL.md should gain a one-line pointer to any new support file so future agents know it exists.\n  4. RESTRUCTURE a loaded skill whose body grew log-like \u2014 rc/sha/date-dense sections, session-detail spirals, or a fat body with no support files. Use skill_manage action=restructure with restructure: [{\"heading\": \"<the exact ## heading text>\", \"to_file\": \"references/<topic>.md\"}] \u2014 the ENTIRE ## section (from that heading to the next heading) moves into the support file and its position becomes a pointer line. The skill's name and directory never change. Only propose headings that exist verbatim in the body; never invent one, and never restructure a healthy small skill.\n  5. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class. The name MUST be at the class level. The name MUST NOT be a specific PR number, error string, feature codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' session artifact. If the proposed name only makes sense for today's task, it's wrong \u2014 fall back to (1), (2), or (3).\n\nUser-preference embedding (important): when the user expressed a style/format/workflow preference, the update belongs in the SKILL.md body, not just in memory. Memory captures 'who the user is and what the current situation and state of your operations are'; skills capture 'how to do this class of task for this user'. When they complain about how you handled a task, the skill that governs that task needs to carry the lesson.\n\nIf you notice two existing skills that overlap, note it in your reply \u2014 the background curator handles consolidation at scale.\n\nTwo-tier deposition discipline (DSH addition, same spirit as the umbrella rule): before writing, classify the knowledge:\n  \u2022 PATTERN (reusable \u2014 symptom \u2192 mechanism \u2192 fix \u2192 verification, still valuable next session) belongs in the SKILL.md body.\n  \u2022 LOG (one-off \u2014 commit SHAs, npm/profile states, what this release changed, this session's process narrative) belongs in a references/ file, never the body. Body density IS reuse rate. Keep new entries tight: a pattern fits in 2-8 physical lines; prefer changing the current-state pointer over appending history.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so this pass may not update them. They also cannot be archived by any writer (the foreground included): remove the .pinned marker first. Foreground and delegated-subagent update/patch writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.\n\nIf a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill \u2014 never 'this tool does not work' as a standalone constraint.\n\n'Nothing to save.' is a real option but should NOT be the default. If the session ran smoothly with no corrections and produced no new technique, just say 'Nothing to save.' and stop. Otherwise, act.";
 export declare const COMBINED_REVIEW_PROMPT = "[Auto-review]\nReview the conversation above and update two things:\n\n**Memory**: who the user is. Did the user reveal persona, desires, preferences, personal details, or expectations about how you should behave? Save facts about the user and durable preferences with the memory tool.\n\n**Skills**: how to do this class of task. Be ACTIVE \u2014 most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome.\n\nTarget shape of the skill library: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries.\n\nSignals that warrant a skill update (any one is enough):\n  \u2022 User corrected your style, tone, format, legibility, verbosity, or approach. Frustration is a FIRST-CLASS skill signal, not just a memory signal. 'stop doing X', 'don't format like this', 'I hate when you Y' \u2014 embed the lesson in the skill that governs that task so the next session starts fixed.\n  \u2022 Non-trivial technique, fix, workaround, or debugging path emerged.\n  \u2022 A skill that was loaded or consulted turned out wrong, missing, or outdated \u2014 patch it now.\n\nRead-before-write: update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session. On the plan channel ops on unread skills are rejected; direct writes have no such guard, so treat the rule as binding. CREATE of a brand-new umbrella is the only exception.\n\nPreference order for skills \u2014 pick the earliest that fits:\n  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded or read in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.\n  2. UPDATE AN EXISTING UMBRELLA. Patch it.\n  3. ADD A SUPPORT FILE under an existing umbrella via skill_manage action=write_file. Three kinds: references/<topic>.md for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes) written concise and task-focused; templates/<name>.<ext> for starter files meant to be copied and modified; scripts/<name>.<ext> for statically re-runnable actions (verification, fixture generators, probes). Add a one-line pointer in SKILL.md so future agents find them.\n  4. RESTRUCTURE a loaded skill whose body grew log-like (rc/sha/date-dense sections, session-detail spirals, fat body with no support files) via skill_manage action=restructure with restructure: [{\"heading\": \"<the exact ## heading text>\", \"to_file\": \"references/<topic>.md\"}] \u2014 the ENTIRE ## section moves into the support file and its position becomes a pointer line; the skill's name and directory never change. Only propose headings that exist verbatim in the body.\n  5. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level \u2014 NOT a PR number, error string, codename, library-alone name, or 'fix-X / debug-Y' session artifact. If the name only fits today's task, fall back to (1), (2), or (3).\n\nTwo-tier deposition discipline (DSH addition): classify before writing \u2014 PATTERN (symptom \u2192 mechanism \u2192 fix \u2192 verification) goes in the SKILL.md body; LOG (commit SHAs, npm/profile states, this release's change list, this session's narrative) goes in a references/ file. Body density IS reuse rate; a pattern fits in 2-8 physical lines.\n\nUser-preference embedding: when the user complains about how you handled a task, update the skill that governs that task \u2014 memory alone isn't enough. Memory says 'who the user is and what the current situation and state of your operations are'; skills say 'how to do this class of task for this user'. Both should carry user-preference lessons when relevant.\n\nIf you notice overlapping existing skills, mention it \u2014 the background curator handles consolidation.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so this pass may not update them. They also cannot be archived by any writer (the foreground included): remove the .pinned marker first. Foreground and delegated-subagent update/patch writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.\n\nIf a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill \u2014 never 'this tool does not work' as a standalone constraint.\n\nAct on whichever of the two dimensions has real signal. If genuinely nothing stands out on either, say 'Nothing to save.' and stop \u2014 but don't reach for that conclusion as a default.";

package/lib/types/skill-reads.d.ts

@@ -13,7 +13,8 @@
  * path's gate, whose exec view may be a bare stub): it answers "which accessor, and what does an
  * unreadable session mean" — `undefined`, so the gate keeps its previous behavior instead of
  * refusing every write. The review path reads a real platform `Session` and calls the reader
- * directly; a fallback there would be dead code for an impossible case.
+ * directly; a fallback there would be dead code for an impossible case. The structural accessor is
+ * the family's OWN `readEvents` (A69): production reads no deprecated platform log accessor.
  *
  * v32 REV-06(a) is preserved by the dispatch normalizer: a skill counts as READ only when its read
  * did not fail, so a failed/timeout read cannot pass the gate and let a writer blind-overwrite
@@ -23,10 +24,18 @@
  * @module @lmzhen/dsh-evolution-core
  */
 import type { Context } from '@deepseek-ai/cordis';
-/** The session-log accessor the platform exposes (0.1.5 on; `session.events` before it). */
+/**
+ * The family's OWN structural view of a session log, for a caller that holds no platform `Session`
+ * (the tool path's exec view may be a bare stub). The CALLER supplies it — the family reads no
+ * deprecated platform accessor (`snapshotEvents`/`eventAt`/`ownEvents`): those are the platform's own
+ * migration debt, and a family that reads them keeps the deprecated surface alive in every
+ * composition (A69 / 6-2). A platform `Session` does not carry this member and therefore takes the
+ * projection path below; this view exists so the fallback still has a basis instead of being deleted
+ * (deleting it would leave a stub session's read-before-write gate with nothing to fold).
+ */
 export interface EvolutionSessionLogView {
-    /** @returns the session's events, oldest first. */
-    snapshotEvents?: () => Iterable<{
+    /** @returns the events this view can see, oldest first; absent when the caller has no log. */
+    readEvents?: () => Iterable<{
         type: string;
         data?: unknown;
     }>;

package/lib/types/skill-store.d.ts

@@ -64,6 +64,13 @@ export interface SkillSummary {
      * drift scans) saves the second per-skill read; the default stays body-free so
      * the common listing does not hold a whole tree in memory. */
     content?: string;
+    /** T2-07/A22: the parsed frontmatter record, present only for
+     * {@link SkillLibrary.list} calls that pass `{ withFrontmatter: true }`. The
+     * listing parses the file it already read, so a consumer that derives a policy
+     * from frontmatter (the catalog’s invocation map) shares that ONE read instead
+     * of paying a second per-skill read. Absent when the file carries no parseable
+     * frontmatter — the same posture as its description. */
+    frontmatter?: Record<string, unknown>;
 }
 /**
  * Stage-time anchor for a full-content write (v35 C9): the sha256 the caller read
@@ -326,12 +333,20 @@ export declare class SkillLibrary {
     /**
      * Summarize the skill tree.
      * @param options - `withContent` attaches each skill's whole SKILL.md body to
-     * its summary (v35 C11): the read this listing already performs is the one the
-     * body would cost again, so a content-consuming caller pays no second pass.
+     * its summary (v35 C11), `withFrontmatter` its parsed frontmatter record
+     * (T2-07/A22): the read this listing already performs is the one either would
+     * cost again, so a caller pays no second pass over the tree.
      * @returns one summary per readable skill directory.
      */
+    /** T2-V2/A27: the skill names the TREE holds — the same listing rule {@link list} applies (dot
+     * entries skipped, a SKILL.md must exist), WITHOUT reading any SKILL.md. A consumer that needs the
+     * member set rather than the summaries (the learning graph's node set) pays one directory listing
+     * instead of a whole-tree read pass.
+     * @returns the sorted skill directory names. */
+    treeNames(): Promise<string[]>;
     list(options?: {
         withContent?: boolean;
+        withFrontmatter?: boolean;
     }): Promise<SkillSummary[]>;
     read(rawName: string): Promise<string | null>;
     /**
@@ -390,6 +405,13 @@ export declare class SkillLibrary {
      * @returns path -> character count (possibly empty), or null when the listing or
      *   a size probe cannot answer — unknown is never an empty map.
      */
+    /** A plan-time read whose bytes become a tree change's CAS baseline (`expected`). A failed read is
+     * NAMED and answers `null`, which is FAIL-CLOSED at commit: the baseline is then "absent", so an
+     * existing file counts as drift and the commit refuses instead of overwriting bytes nobody read
+     * (N36: the failure is not silently "the file is not there").
+     * @param target - the file a tree change is about to write.
+     * @returns its bytes, or `null` for both "absent" and "could not read". */
+    private readForCas;
     supportFileChars(rawName: string): Promise<Record<string, number> | null>;
     /**
      * Structure-health facts for one skill (rc.73 A1, 008 design): body

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "publishConfig": {
     "access": "public"
   },

package/persisted-write-inventory.json

@@ -50,12 +50,8 @@
     "writer": "evolution-state-json/src/index.ts",
     "serializedBy": "transact",
     "marker": "transactIo(io(), join(root, file)",
-    "state": [
-      "evolution-state-json/src/index.ts :: recordGateWarned",
-      "evolution-state-json/src/index.ts :: corruptWritten",
-      "evolution-state-json/src/index.ts :: corruptWriteWarned"
-    ],
-    "note": "The durable state stack (review/curator/pending). Its three warn sets are per-process de-duplication and are registered under N12."
+    "state": [],
+    "note": "The durable state stack (review/curator/pending). S4.4/O-6 moved its three warn/rewrite sets into the provider instance (QuarantineMemory), so no module-scope N12 store remains here."
   },
   {
     "id": "curator-reports",
@@ -74,5 +70,50 @@
     "marker": "LOCK_SUFFIX",
     "state": [],
     "note": "The skill tree itself. Per-target `<path>.lock` claims (pid:token body) guard every byte writer; destructive movers refuse a live lock."
+  },
+  {
+    "id": "activity-log",
+    "path": "<evolutionRoot>/activity.json",
+    "writer": "evolution-activity/src/index.ts",
+    "serializedBy": "transact",
+    "marker": "transactIo(io, activityFile(root)",
+    "state": [],
+    "note": "The plan-applied activity sidecar. Declared by v46 S1.12: the file carried a transactional write that no inventory row vouched for, and the N20 reverse scan is what named it."
+  },
+  {
+    "id": "skill-history-index",
+    "path": "<historyRoot>/skills/<name>/index.json",
+    "writer": "evolution-core/src/skill-history.ts",
+    "serializedBy": "transact",
+    "marker": "transactIo(io, file,",
+    "state": [],
+    "note": "One skill's recorded-version index (content chain + blob references). Declared by v46 S1.12: the replace path was already transactional but undeclared, so a regression to a plain write would have been invisible."
+  },
+  {
+    "id": "skill-store-transact-primitive",
+    "path": "<caller-supplied>",
+    "writer": "evolution-core/src/skill-store.ts",
+    "serializedBy": "transact",
+    "marker": "transactIo(ioLike, path, task)",
+    "state": [],
+    "note": "The store's transaction helper: it prefers the backend's own transact and falls back to the seam's transactIo. The target is the caller's path — each durable target has its own row above; this row vouches for the primitive itself."
+  },
+  {
+    "id": "feedback-events",
+    "path": "<dshHome>/evolution/events.json",
+    "writer": "evolution-feedback/src/index.ts",
+    "serializedBy": "transact",
+    "marker": "transactIo(io, eventsPath,",
+    "state": [],
+    "note": "Feedback appends to the family event log under the cross-process lock. Declared by v46 S1.12 (N20 reverse)."
+  },
+  {
+    "id": "pending-archive",
+    "path": "<stateHome>/pending-state-archive.json",
+    "writer": "evolution-state-json/src/index.ts",
+    "serializedBy": "transact",
+    "marker": "transactIo(io(), pathOf(PENDING_ARCHIVE_FILE)",
+    "state": [],
+    "note": "The resolved-pending archive (the legacy merge target). The store already declared its record map; v46 S1.12 declared the archive append as well — the second site in one file is exactly what the reverse scan exists to find."
   }
 ]