@miller-tech/uap 1.27.0 → 1.29.0

package/dist/delivery/practice.js

@@ -0,0 +1,185 @@
+/**
+ * Practice Store (Phase 4)
+ *
+ * Best-practice "cards" learned from past deliveries and injected into future
+ * prompts for similar tasks. A card records guidance distilled from a
+ * *successful* run — the winning strategy seed and how many turns it took —
+ * keyed by task keywords.
+ *
+ * Provenance matters: cards are derived from the harness's own strategy seeds
+ * and gate outcomes, never from raw model output. This keeps the long-term
+ * store free of model-authored text (a stored-prompt-injection vector).
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+/** Strategy ids are harness-owned seed labels; this guards the template
+ * against injection if a tampered store supplies an arbitrary string. */
+const STRATEGY_RE = /^[a-z][a-z0-9-]{0,31}$/;
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'to', 'of', 'and', 'or', 'in', 'on', 'for', 'with', 'that',
+    'returns', 'return', 'create', 'add', 'make', 'write', 'into', 'from', 'as',
+    'is', 'it', 'be', 'should', 'when', 'this', 'each', 'two', 'using',
+]);
+/** Extract lowercased keyword tokens from a task instruction. */
+export function extractKeywords(text, max = 12) {
+    const seen = new Set();
+    const tokens = [];
+    for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 3 || STOP_WORDS.has(raw) || seen.has(raw))
+            continue;
+        seen.add(raw);
+        tokens.push(raw);
+        if (tokens.length >= max)
+            break;
+    }
+    return tokens;
+}
+/** Jaccard-ish overlap: shared keywords / query keywords. */
+function relevance(card, queryKeywords) {
+    if (queryKeywords.length === 0)
+        return 0;
+    const cardSet = new Set(card.keywords);
+    const shared = queryKeywords.filter((k) => cardSet.has(k)).length;
+    return shared / queryKeywords.length;
+}
+const MIN_RELEVANCE = 0.25;
+/** In-memory store — the base implementation; the file store persists it. */
+export class InMemoryPracticeStore {
+    cards;
+    constructor(cards = []) {
+        this.cards = cards;
+    }
+    retrieve(instruction, limit = 3) {
+        const keywords = extractKeywords(instruction);
+        return this.cards
+            .map((card) => ({ card, score: relevance(card, keywords) }))
+            .filter(({ score }) => score >= MIN_RELEVANCE)
+            .sort((a, b) => {
+            if (b.score !== a.score)
+                return b.score - a.score;
+            if (b.card.successCount !== a.card.successCount)
+                return b.card.successCount - a.card.successCount;
+            return a.card.bestTurns - b.card.bestTurns;
+        })
+            .slice(0, limit)
+            .map(({ card }) => card);
+    }
+    record(input) {
+        const strategy = STRATEGY_RE.test(input.strategy) ? input.strategy : 'direct';
+        // Dedup on strategy, not rendered guidance (which varies by turn count).
+        const existing = this.cards.find((c) => c.strategy === strategy);
+        if (existing) {
+            existing.successCount += 1;
+            existing.bestTurns = Math.min(existing.bestTurns, input.turns);
+            existing.keywords = [...new Set([...existing.keywords, ...input.keywords])];
+            existing.guidance = distillPractice(strategy, existing.bestTurns);
+            return;
+        }
+        this.cards.push({
+            id: this.nextId(),
+            strategy,
+            keywords: input.keywords,
+            guidance: distillPractice(strategy, input.turns),
+            successCount: 1,
+            bestTurns: input.turns,
+        });
+    }
+    /** Smallest unused pN id — robust to merges and dropped (corrupt) cards. */
+    nextId() {
+        const used = new Set(this.cards.map((c) => c.id));
+        for (let i = 1;; i++) {
+            const id = `p${i}`;
+            if (!used.has(id))
+                return id;
+        }
+    }
+    all() {
+        return this.cards;
+    }
+}
+/** File-backed practice store (JSON). Self-heals on missing/corrupt files. */
+export class FilePracticeStore extends InMemoryPracticeStore {
+    path;
+    constructor(path) {
+        super(FilePracticeStore.load(path));
+        this.path = path;
+    }
+    /**
+     * Load cards from disk, validating every field. The on-disk file is NOT
+     * trusted to supply guidance text — guidance is regenerated from the
+     * validated strategy + bestTurns via distillPractice, so a tampered file
+     * cannot inject prompt text (the read path enforces the same provenance
+     * the write path guarantees). Structurally-invalid cards are dropped.
+     */
+    static load(path) {
+        if (!existsSync(path))
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            return [];
+        }
+        if (!Array.isArray(parsed))
+            return [];
+        const cards = [];
+        for (const raw of parsed) {
+            if (typeof raw !== 'object' || raw === null)
+                continue;
+            const c = raw;
+            if (typeof c.strategy !== 'string' || !STRATEGY_RE.test(c.strategy))
+                continue;
+            if (!Array.isArray(c.keywords) || !c.keywords.every((k) => typeof k === 'string'))
+                continue;
+            const successCount = Number(c.successCount);
+            const bestTurns = Number(c.bestTurns);
+            if (!Number.isFinite(successCount) || successCount < 1)
+                continue;
+            if (!Number.isFinite(bestTurns) || bestTurns < 1)
+                continue;
+            cards.push({
+                id: typeof c.id === 'string' ? c.id : `p${cards.length + 1}`,
+                strategy: c.strategy,
+                keywords: c.keywords,
+                guidance: distillPractice(c.strategy, bestTurns), // regenerated, never trusted from disk
+                successCount: Math.floor(successCount),
+                bestTurns: Math.floor(bestTurns),
+            });
+        }
+        return cards;
+    }
+    record(input) {
+        super.record(input);
+        this.persist();
+    }
+    persist() {
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            // Atomic write: temp file + rename, so a crash mid-write cannot corrupt
+            // the store and we never follow a pre-planted symlink at the final path.
+            const tmp = `${this.path}.tmp`;
+            writeFileSync(tmp, JSON.stringify(this.all(), null, 2), 'utf-8');
+            renameSync(tmp, this.path);
+        }
+        catch {
+            // Persistence is best-effort; in-memory state remains valid
+        }
+    }
+}
+/** Default on-disk location for a project's learned practices. */
+export function defaultPracticePath(projectRoot) {
+    return join(projectRoot, '.uap', 'delivery-practices.json');
+}
+/**
+ * Distill a one-line practice from a successful delivery. Provenance-safe:
+ * built only from the winning strategy and turn count, not model output.
+ */
+export function distillPractice(winningStrategy, turns) {
+    const strategy = winningStrategy ?? 'direct';
+    if (turns === 1) {
+        return `A '${strategy}' approach solved a similar task on the first attempt — lead with it.`;
+    }
+    return `A '${strategy}' approach converged on a similar task in ${turns} turns — prefer it and verify against the gates early.`;
+}
+//# sourceMappingURL=practice.js.map

package/dist/delivery/practice.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",