crewly 1.20.398 → 1.20.400

package/dist/backend/backend/src/services/memory/knowledge-similarity.js

@@ -0,0 +1,319 @@
+/**
+ * Near-duplicate detection and evidence merge for role knowledge (#914 P1).
+ *
+ * `addRoleKnowledge` used to dedupe by exact match or substring containment
+ * only, so the same fact written twice with a different id, count or date
+ * in it ("Refresh standing answer … (1 newer)" / "… (6 newer)") became two
+ * entries, and recall surfaced both. This module replaces that check with
+ * a cheap nearest-neighbour over token sets:
+ *
+ * - `knowledgeTokens` lowercases, splits on non-alphanumerics and drops the
+ *   tokens that vary between restatements of one fact (uuids, hex ids,
+ *   long digit runs, single letters);
+ * - `jaccard` is the set overlap of two token sets;
+ * - `numbersCompatible` keeps two texts apart when they disagree on a
+ *   number (ticket, count, version): the frame may be identical, the fact
+ *   is not;
+ * - `findNearestKnowledge` returns the best candidate in the same scope
+ *   (same category; overlapping tags when both sides have tags), an exact
+ *   or substring match first, else the highest Jaccard at or above the
+ *   threshold among number-compatible entries. Superseded and expired
+ *   entries are never candidates, so a new write cannot reinforce a dead
+ *   fact. Short texts (fewer than `MIN_TOKENS_FOR_NEAR` tokens) match
+ *   exactly or not at all.
+ * - `mergeKnowledgeEvidence` folds the incoming entry's provenance into the
+ *   existing one (exact match): evidence union, importance max,
+ *   verification timestamp. The existing content stays.
+ * - `restateKnowledge` handles a near match: the newest wording becomes a
+ *   new entry with the old provenance and reinforcement, the old entry is
+ *   marked superseded by it and kept for audit. The LLM adjudication the
+ *   issue describes (keep / modify / supersede by judgment) is a later,
+ *   possibly Pro, step; this is the deterministic rule.
+ * - `evictionIndex` picks what a full store drops: superseded first.
+ *
+ * Pure functions only; the threshold was set by replaying the owner's
+ * 3.7k real entries (see spec `2026-10-25-knowledge-evidence-merge.md`).
+ *
+ * @module services/memory/knowledge-similarity
+ */
+import { MEMORY_CONSTANTS } from '../../constants.js';
+import { isHiddenFromDefaultRecall } from './role-knowledge-eligibility.js';
+/** A uuid anywhere in the text (work item, claim and task ids). */
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+/**
+ * Hex runs of four or more characters with at least one digit: partial ids
+ * (`WI d3416d29`), commit shas, hashes. Plain words that happen to be hex
+ * letters (`face`, `bead`) have no digit and stay.
+ */
+const HEX_ID = /^(?=.*\d)[0-9a-f]{4,}$/;
+/** Digit runs of six or more: epoch values, compact dates, random suffixes. */
+const LONG_NUMBER = /^\d{6,}$/;
+/** A number that survived: ticket numbers, counts, versions, years. */
+const NUMBER = /^\d+$/;
+/** Anything that is not a letter or digit splits tokens. */
+const NON_ALNUM = /[^\p{L}\p{N}]+/u;
+/**
+ * Tokens of a knowledge text that survive a restatement: lowercase words
+ * and numbers up to five digits, without uuids, hex ids, long digit runs or
+ * single letters. Single digits stay: "entry 0" and "entry 1" are two
+ * facts.
+ *
+ * @param text - Entry content
+ * @returns Distinct tokens
+ *
+ * @example
+ * ```typescript
+ * knowledgeTokens('Claimed WorkItem X (id: 51851ddb-3e5f-48b4-b73a-fccbc6a79abb) at 2026-10-25, 3 newer')
+ * // Set { 'claimed', 'workitem', 'id', 'at', '2026', '10', '25', '3', 'newer' }
+ * ```
+ */
+export function knowledgeTokens(text) {
+    const out = new Set();
+    for (const raw of text.toLowerCase().replace(UUID, ' ').split(NON_ALNUM)) {
+        if (raw.length === 0)
+            continue;
+        if (NUMBER.test(raw)) {
+            if (!LONG_NUMBER.test(raw))
+                out.add(raw);
+            continue;
+        }
+        if (raw.length === 1 || HEX_ID.test(raw))
+            continue;
+        out.add(raw);
+    }
+    return out;
+}
+/**
+ * Whether two token sets agree on their numbers: one side's numbers must
+ * all appear on the other. "verify CE-140" and "verify CE-196" share every
+ * word and differ in one number — two facts, however alike the frame.
+ * "snapshot 10/13 03:40Z" and "snapshot 10/13" are one fact, the second
+ * just shorter. Disagreeing counts ("1 newer" / "6 newer") are kept apart
+ * on purpose: a false merge loses knowledge, a missed one only leaves a
+ * duplicate.
+ *
+ * @param a - First token set
+ * @param b - Second token set
+ * @returns true when the numbers of one set are a subset of the other's
+ */
+export function numbersCompatible(a, b) {
+    const na = [...a].filter((t) => NUMBER.test(t));
+    const nb = [...b].filter((t) => NUMBER.test(t));
+    return na.every((t) => b.has(t)) || nb.every((t) => a.has(t));
+}
+/**
+ * Jaccard overlap of two token sets: |A ∩ B| / |A ∪ B|.
+ *
+ * @param a - First set
+ * @param b - Second set
+ * @returns 0 when either set is empty, else the overlap in [0, 1]
+ */
+export function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let shared = 0;
+    for (const t of a)
+        if (b.has(t))
+            shared++;
+    return shared / (a.size + b.size - shared);
+}
+/**
+ * Whether an existing entry is in the incoming entry's scope: the same
+ * category when the incoming one names a category, and at least one shared
+ * tag when both carry tags.
+ *
+ * @param existing - Existing entry
+ * @param incoming - Incoming entry
+ * @returns true when the two may be compared
+ */
+export function sameScope(existing, incoming) {
+    if (incoming.category && existing.category && incoming.category !== existing.category)
+        return false;
+    const a = incoming.tags ?? [];
+    const b = existing.tags ?? [];
+    if (a.length > 0 && b.length > 0 && !a.some((t) => b.includes(t)))
+        return false;
+    return true;
+}
+/**
+ * Equal after trim and lowercase.
+ *
+ * @param existing - Existing content
+ * @param incoming - Incoming content
+ * @returns true when the two texts are the same
+ */
+export function isSameText(existing, incoming) {
+    return existing.toLowerCase().trim() === incoming.toLowerCase().trim();
+}
+/**
+ * One text contains the other, when the incoming text is longer than the
+ * substring floor (the legacy containment rule).
+ *
+ * @param existing - Existing content
+ * @param incoming - Incoming content
+ * @returns true for a containment match
+ */
+export function containsText(existing, incoming) {
+    const a = existing.toLowerCase().trim();
+    const b = incoming.toLowerCase().trim();
+    return b.length > MEMORY_CONSTANTS.DEDUP.SUBSTRING_MIN_CHARS && (a.includes(b) || b.includes(a));
+}
+/**
+ * The legacy rule: {@link isSameText} or {@link containsText}.
+ *
+ * @param existing - Existing content
+ * @param incoming - Incoming content
+ * @returns true for an exact or containment match
+ */
+export function isExactMatch(existing, incoming) {
+    return isSameText(existing, incoming) || containsText(existing, incoming);
+}
+/**
+ * The existing entry the incoming one duplicates, if any: an exact match
+ * first, else the highest token overlap at or above the threshold, among
+ * entries in scope that recall still shows.
+ *
+ * @param knowledge - Existing entries
+ * @param incoming - Entry about to be written
+ * @param options - Threshold and reference time
+ * @returns The nearest match, or null when nothing is close enough
+ *
+ * @example
+ * ```typescript
+ * const hit = findNearestKnowledge(memory.roleKnowledge, { content, category });
+ * if (hit) merge(hit.entry); else append(content);
+ * ```
+ */
+export function findNearestKnowledge(knowledge, incoming, options = {}) {
+    const threshold = options.threshold ?? MEMORY_CONSTANTS.DEDUP.NEAR_DUPLICATE_JACCARD;
+    const now = options.now ?? new Date();
+    const incomingTokens = knowledgeTokens(incoming.content);
+    const nearAllowed = incomingTokens.size >= MEMORY_CONSTANTS.DEDUP.MIN_TOKENS_FOR_NEAR;
+    // Same text wins outright; a containment match beats any near match; among
+    // near matches the highest overlap wins.
+    let contained = null;
+    let near = null;
+    for (const entry of knowledge) {
+        if (isHiddenFromDefaultRecall(entry, now))
+            continue;
+        if (!sameScope(entry, incoming))
+            continue;
+        if (isSameText(entry.content, incoming.content))
+            return { entry, score: 1, kind: 'exact' };
+        if (contained === null && containsText(entry.content, incoming.content)) {
+            contained = { entry, score: 1, kind: 'exact' };
+            continue;
+        }
+        if (!nearAllowed)
+            continue;
+        const entryTokens = knowledgeTokens(entry.content);
+        if (!numbersCompatible(entryTokens, incomingTokens))
+            continue;
+        const score = jaccard(entryTokens, incomingTokens);
+        if (score >= threshold && (near === null || score > near.score))
+            near = { entry, score, kind: 'near' };
+    }
+    return contained ?? near;
+}
+/**
+ * Folds an incoming duplicate's provenance into the existing entry, in
+ * place: evidence becomes the union (legacy `learnedFrom` and
+ * `sourceTaskId` count as evidence), importance the max, and the entry is
+ * marked verified and used now. Content, confidence and ids are left to the
+ * caller.
+ *
+ * @param existing - Entry that stays (mutated)
+ * @param incoming - Duplicate that is not written
+ * @param now - Timestamp for `lastVerifiedAt` / `lastUsed`
+ * @returns What changed
+ */
+export function mergeKnowledgeEvidence(existing, incoming, now = new Date()) {
+    const evidence = [...(existing.evidence ?? (existing.learnedFrom ? [existing.learnedFrom] : []))];
+    const addedEvidence = [];
+    for (const ref of [...(incoming.evidence ?? []), incoming.learnedFrom, incoming.sourceTaskId]) {
+        if (!ref || evidence.includes(ref))
+            continue;
+        evidence.push(ref);
+        addedEvidence.push(ref);
+    }
+    if (evidence.length > 0)
+        existing.evidence = evidence;
+    let importanceRaised = false;
+    if (incoming.importance !== undefined && incoming.importance > (existing.importance ?? 0)) {
+        existing.importance = incoming.importance;
+        importanceRaised = true;
+    }
+    const iso = now.toISOString();
+    existing.lastVerifiedAt = iso;
+    existing.lastUsed = iso;
+    return { addedEvidence, importanceRaised };
+}
+/** Prefix of the evidence ref a superseded entry gets when a restatement replaced it. */
+export const RESTATEMENT_REASON_PREFIX = 'supersession-reason:restated';
+/**
+ * A near-duplicate is the same fact said again, often with a correction
+ * ("I asserted X is a working symlink" → "X is a DANGLING symlink"), so the
+ * newest wording wins: the incoming entry becomes a new entry carrying the
+ * old one's provenance and reinforcement, and the old entry is marked
+ * superseded by it — hidden from recall, kept for audit, the same way
+ * `MemorySupersessionService.supersede` records an explicit supersession.
+ *
+ * @param old - Existing near-duplicate (mutated: superseded, evidence reason appended)
+ * @param incoming - Entry being written
+ * @param ids - The new entry's id and timestamp, and the match score for the audit ref
+ * @returns The new entry to store
+ *
+ * @example
+ * ```typescript
+ * const fresh = restateKnowledge(match.entry, entry, { id: uuidv4(), now: new Date(), score: match.score });
+ * memory.roleKnowledge.push(fresh);
+ * ```
+ */
+export function restateKnowledge(old, incoming, ids) {
+    const iso = ids.now.toISOString();
+    const fresh = {
+        ...incoming,
+        id: ids.id,
+        createdAt: iso,
+        confidence: Math.min(Math.max(old.confidence, incoming.confidence ?? MEMORY_CONSTANTS.DEFAULTS.INITIAL_CONFIDENCE) + MEMORY_CONSTANTS.DEFAULTS.CONFIDENCE_REINFORCEMENT, MEMORY_CONSTANTS.DEFAULTS.MAX_CONFIDENCE),
+        lastVerifiedAt: iso,
+    };
+    // The new entry inherits the old provenance, then its own.
+    const inherited = { ...fresh, evidence: [...(old.evidence ?? (old.learnedFrom ? [old.learnedFrom] : []))], importance: old.importance };
+    mergeKnowledgeEvidence(inherited, incoming, ids.now);
+    if (inherited.evidence && inherited.evidence.length > 0)
+        fresh.evidence = inherited.evidence;
+    if (inherited.importance !== undefined)
+        fresh.importance = inherited.importance;
+    old.superseded = true;
+    old.supersededBy = fresh.id;
+    old.evidence = [...(old.evidence ?? (old.learnedFrom ? [old.learnedFrom] : [])), `${RESTATEMENT_REASON_PREFIX} (jaccard ${ids.score.toFixed(2)})`];
+    return fresh;
+}
+/**
+ * Which entry to evict when a store is full: the oldest superseded entry
+ * first (recall no longer shows it), else the lowest-confidence live one.
+ *
+ * @param knowledge - Entries
+ * @returns Index to remove, or -1 for an empty list
+ */
+export function evictionIndex(knowledge) {
+    if (knowledge.length === 0)
+        return -1;
+    let pick = -1;
+    for (let i = 0; i < knowledge.length; i++) {
+        const e = knowledge[i];
+        if (!(e.superseded === true || e.supersededBy))
+            continue;
+        if (pick === -1 || e.createdAt < knowledge[pick].createdAt)
+            pick = i;
+    }
+    if (pick !== -1)
+        return pick;
+    for (let i = 0; i < knowledge.length; i++) {
+        if (pick === -1 || knowledge[i].confidence < knowledge[pick].confidence)
+            pick = i;
+    }
+    return pick;
+}
+//# sourceMappingURL=knowledge-similarity.js.map

package/dist/backend/backend/src/services/memory/knowledge-similarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-similarity.js","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/knowledge-similarity.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/memory/standing-answers.service.d.ts

@@ -33,6 +33,10 @@
  *   is no longer in force (superseded, expired, resolved). The watermark
  *   does not move for these, so they are checked on every read
  *   ({@link findInvalidatedSections}) and also make the page need a refresh.
+ * - Edits are per section (keep / modify / remove / add), so a refresh never
+ *   rewrites what it did not touch. Before a content change the page as it
+ *   was is snapshotted and the write is logged (`changes.log`), so every
+ *   change is auditable (#914 P1).
  * - No LLM runs here. The only writer is an agent working a refresh
  *   WorkItem (see standing-refresh.service.ts), raised only when the
  *   watermark moves.
@@ -128,8 +132,19 @@ export interface WriteSectionInput extends StandingLocation {
     /** Citations (`dec:<id>` …); at least one unless removing. */
     cites: string[];
 }
+/** What a section write did to the page. */
+export type SectionWriteOp = 'added' | 'modified' | 'removed' | 'unchanged';
 /** Result of a section write. */
 export interface WriteSectionResult {
+    /**
+     * What changed: `added` (new heading), `modified` (body or citations
+     * differ), `removed` (empty body on an existing section) or `unchanged`
+     * (the same body and citations again — only `last_refreshed` and the
+     * watermark move; use it to confirm a section after a refresh).
+     */
+    op: SectionWriteOp;
+    /** Snapshot of the page as it was before this write, null when nothing changed or the page is new. */
+    snapshot: string | null;
     filePath: string;
     watermark: string | null;
     removed: boolean;
@@ -244,9 +259,31 @@ export declare class StandingAnswersService {
     /**
      * @param options - `crewlyHome` overrides {@link getCrewlyHomePath} (tests)
      */
+    private readonly historyKeep;
+    /**
+     * @param options - `crewlyHome` overrides {@link getCrewlyHomePath} (tests);
+     *   `historyKeep` overrides {@link STANDING_ANSWERS_CONSTANTS.HISTORY_KEEP}
+     */
     constructor(options?: {
         crewlyHome?: string;
+        historyKeep?: number;
     });
+    /**
+     * Directory holding a page's snapshots and `changes.log`.
+     *
+     * @param def - Page definition
+     * @param loc - Location
+     * @returns Absolute path, or null when the location lacks what the scope needs
+     */
+    historyDir(def: StandingPageDef, loc: StandingLocation): string | null;
+    /**
+     * Snapshots of a page, oldest first (absolute paths).
+     *
+     * @param def - Page definition
+     * @param loc - Location
+     * @returns Snapshot files; empty when there is no history
+     */
+    listSnapshots(def: StandingPageDef, loc: StandingLocation): Promise<string[]>;
     /**
      * File path of a page for a location.
      *
@@ -281,7 +318,10 @@ export declare class StandingAnswersService {
      */
     listPageStatuses(loc: StandingLocation): Promise<StandingPageStatus[]>;
     /**
-     * Write one section of a page (section-level edit).
+     * Write one section of a page (section-level edit): keep the rest, replace
+     * or add this heading, or remove it (empty body). Before a content change
+     * the previous page is snapshotted under {@link historyDir} and every write
+     * appends a `changes.log` line, so each change is auditable (#914 P1).
      *
      * Validates the heading and body, requires every citation to name an
      * entry in the page's sources, masks secrets, then stamps
@@ -306,6 +346,14 @@ export declare class StandingAnswersService {
      */
     buildRefreshBrief(status: StandingPageStatus, loc: StandingLocation, agentSkillsPath: string): Promise<string>;
 }
+/**
+ * What writing `section` would do to `page`.
+ *
+ * @param page - Page as it stands
+ * @param section - Incoming section (empty body = remove)
+ * @returns The op
+ */
+export declare function sectionWriteOp(page: StandingPage, section: StandingSection): SectionWriteOp;
 /**
  * Pairs of in-force entries from the same UTC day that share a topic: the
  * later one may replace the earlier one without a supersede link (#884).

package/dist/backend/backend/src/services/memory/standing-answers.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"standing-answers.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/standing-answers.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"standing-answers.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/standing-answers.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/memory/standing-answers.service.js

@@ -33,6 +33,10 @@
  *   is no longer in force (superseded, expired, resolved). The watermark
  *   does not move for these, so they are checked on every read
  *   ({@link findInvalidatedSections}) and also make the page need a refresh.
+ * - Edits are per section (keep / modify / remove / add), so a refresh never
+ *   rewrites what it did not touch. Before a content change the page as it
+ *   was is snapshotted and the write is logged (`changes.log`), so every
+ *   change is auditable (#914 P1).
  * - No LLM runs here. The only writer is an agent working a refresh
  *   WorkItem (see standing-refresh.service.ts), raised only when the
  *   watermark moves.
@@ -322,8 +326,50 @@ export class StandingAnswersService {
     /**
      * @param options - `crewlyHome` overrides {@link getCrewlyHomePath} (tests)
      */
+    historyKeep;
+    /**
+     * @param options - `crewlyHome` overrides {@link getCrewlyHomePath} (tests);
+     *   `historyKeep` overrides {@link STANDING_ANSWERS_CONSTANTS.HISTORY_KEEP}
+     */
     constructor(options = {}) {
         this.crewlyHome = options.crewlyHome ?? getCrewlyHomePath();
+        this.historyKeep = options.historyKeep ?? STANDING_ANSWERS_CONSTANTS.HISTORY_KEEP;
+    }
+    /**
+     * Directory holding a page's snapshots and `changes.log`.
+     *
+     * @param def - Page definition
+     * @param loc - Location
+     * @returns Absolute path, or null when the location lacks what the scope needs
+     */
+    historyDir(def, loc) {
+        if (def.scope === 'project') {
+            if (!loc.projectPath)
+                return null;
+            return path.join(resolveProjectDataDir(loc.projectPath), STANDING_ANSWERS_CONSTANTS.HISTORY_DIR, def.id);
+        }
+        if (!loc.sessionName || !isSafeSegment(loc.sessionName))
+            return null;
+        return path.join(this.crewlyHome, MEMORY_CONSTANTS.PATHS.AGENTS_DIR, loc.sessionName, STANDING_ANSWERS_CONSTANTS.HISTORY_DIR);
+    }
+    /**
+     * Snapshots of a page, oldest first (absolute paths).
+     *
+     * @param def - Page definition
+     * @param loc - Location
+     * @returns Snapshot files; empty when there is no history
+     */
+    async listSnapshots(def, loc) {
+        const dir = this.historyDir(def, loc);
+        if (!dir)
+            return [];
+        try {
+            const names = await fs.readdir(dir);
+            return names.filter((n) => n.endsWith('.md')).sort().map((n) => path.join(dir, n));
+        }
+        catch {
+            return [];
+        }
     }
     /**
      * File path of a page for a location.
@@ -439,7 +485,10 @@ export class StandingAnswersService {
         return all.filter((s) => s !== null);
     }
     /**
-     * Write one section of a page (section-level edit).
+     * Write one section of a page (section-level edit): keep the rest, replace
+     * or add this heading, or remove it (empty body). Before a content change
+     * the previous page is snapshotted under {@link historyDir} and every write
+     * appends a `changes.log` line, so each change is auditable (#914 P1).
      *
      * Validates the heading and body, requires every citation to name an
      * entry in the page's sources, masks secrets, then stamps
@@ -491,17 +540,36 @@ export class StandingAnswersService {
         const maskedHeading = redactSensitive(heading);
         const raw = await readText(filePath);
         const existing = raw === null ? { sections: [] } : parseStandingPage(raw);
-        const { page, removed } = upsertSection(existing, { heading: maskedHeading, body: maskedBody, cites: body ? cites : [] });
+        const section = { heading: maskedHeading, body: maskedBody, cites: body ? cites : [] };
+        const op = sectionWriteOp(existing, section);
+        const { page, removed } = upsertSection(existing, section);
         const watermark = computeWatermark(entries);
+        const now = new Date().toISOString();
         const next = {
             ...page,
             question: existing.question ?? def.question,
-            lastRefreshed: new Date().toISOString(),
+            lastRefreshed: now,
             watermark: watermark ?? undefined,
         };
+        const historyDir = this.historyDir(def, loc);
+        let snapshot = null;
+        if (historyDir) {
+            try {
+                await ensureDir(historyDir);
+                if (op !== 'unchanged' && raw !== null) {
+                    snapshot = await writeSnapshot(historyDir, now, raw);
+                    await pruneSnapshots(historyDir, this.historyKeep);
+                }
+                await appendChangeLog(historyDir, `${now}\t${op}\t${maskedHeading}\t${section.cites.length} cite${section.cites.length === 1 ? '' : 's'}\t${snapshot ? path.basename(snapshot) : '-'}`);
+            }
+            catch {
+                // History is an audit aid; a failure there must not block the page write.
+                snapshot = null;
+            }
+        }
         await ensureDir(path.dirname(filePath));
         await atomicWriteFile(filePath, serializeStandingPage(next));
-        return { filePath, watermark, removed, masked: maskedBody !== body || maskedHeading !== heading };
+        return { filePath, watermark, op, snapshot, removed, masked: maskedBody !== body || maskedHeading !== heading };
     }
     /**
      * The brief for a refresh WorkItem: the question, the current sections,
@@ -538,6 +606,7 @@ export class StandingAnswersService {
             ...possibleSupersedeLines(shown),
             '',
             '## Write each changed section (do not edit the file by hand — the skill checks citations and masks secrets)',
+            'Sections you do not write are kept as they are. A section that is still right: write it again unchanged so the watermark moves (the skill reports `unchanged`; nothing is rewritten). Each change is snapshotted and logged.',
             '```bash',
             `bash ${agentSkillsPath}/core/standing-update/execute.sh --page ${status.def.id} ${where} --heading "<section heading>" --body-file <file> --cites "<cite>,<cite>"`,
             '```',
@@ -546,9 +615,59 @@ export class StandingAnswersService {
         return lines.join('\n');
     }
 }
+/**
+ * What writing `section` would do to `page`.
+ *
+ * @param page - Page as it stands
+ * @param section - Incoming section (empty body = remove)
+ * @returns The op
+ */
+export function sectionWriteOp(page, section) {
+    const key = section.heading.trim().toLowerCase();
+    const prior = page.sections.find((s) => s.heading.trim().toLowerCase() === key);
+    if (!section.body.trim())
+        return prior ? 'removed' : 'unchanged';
+    if (!prior)
+        return 'added';
+    const sameCites = prior.cites.length === section.cites.length && prior.cites.every((c, i) => c === section.cites[i]);
+    return prior.body === section.body && sameCites ? 'unchanged' : 'modified';
+}
 // ---------------------------------------------------------------------------
 // File helpers
 // ---------------------------------------------------------------------------
+/**
+ * Save the previous page under `<dir>/<timestamp>.md` (a numeric suffix
+ * keeps two snapshots in the same millisecond apart).
+ *
+ * @returns The snapshot path
+ */
+async function writeSnapshot(dir, now, raw) {
+    const stem = now.replace(/[:.]/g, '-');
+    for (let n = 0;; n++) {
+        const file = path.join(dir, `${stem}${n ? `-${n}` : ''}.md`);
+        try {
+            await fs.writeFile(file, raw, { encoding: 'utf8', flag: 'wx' });
+            return file;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+}
+/** Delete the oldest snapshots beyond `keep`. */
+async function pruneSnapshots(dir, keep) {
+    const names = (await fs.readdir(dir)).filter((n) => n.endsWith('.md')).sort();
+    const excess = names.slice(0, Math.max(0, names.length - keep));
+    await Promise.all(excess.map((n) => fs.rm(path.join(dir, n), { force: true })));
+}
+/** Append one line to `changes.log`, keeping the last HISTORY_LOG_KEEP lines. */
+async function appendChangeLog(dir, line) {
+    const file = path.join(dir, 'changes.log');
+    const prior = (await readText(file))?.split('\n').filter(Boolean) ?? [];
+    const lines = [...prior, line].slice(-STANDING_ANSWERS_CONSTANTS.HISTORY_LOG_KEEP);
+    await atomicWriteFile(file, `${lines.join('\n')}\n`);
+}
 /** Words too common to signal a shared topic. */
 const TOPIC_STOPWORDS = new Set(['that', 'this', 'with', 'from', 'have', 'will', 'were', 'been', 'into', 'than', 'then', 'they', 'them', 'their', 'there', 'what', 'when', 'which', 'would', 'should', 'could', 'about', 'after', 'before', 'still', 'only', 'also', 'more', 'some', 'does', 'done', 'just', 'over', 'each', 'very']);
 /** Lower-case topic words (4+ letters, not stopwords) of an entry. */