@iamem/amem 0.1.2 → 0.2.0

package/README.md

@@ -184,7 +184,8 @@ Tabs after setup:
 
 1. **Setup** — scan/select repos, platforms, login auto-start, bootstrap proposal  
 2. **Memory** — facts by file, scored drafts (approve / replace older / dismiss / reject noisy), edit/pin/delete, search, recent hits/misses  
-3. **Stats** — estimated tokens saved per LLM, plus JSON / markdown / PDF export (proxies, not a bill)
+3. **Tasks** — per-project Kanban for deferred agent work (Backlog → Next → Doing → Blocked → Done). MCP: `amem_task_add` / `amem_task_update` / `amem_task_complete`. Open tasks appear in `amem_context`. Use Memory for durable facts; Tasks for “do later.”  
+4. **Stats** — estimated tokens saved per LLM, plus JSON / markdown / PDF export (proxies, not a bill)
 
 Server-only (no browser open):
 
@@ -253,6 +254,8 @@ Memory is a small local graph in SQLite:
 | **Claim** | A durable fact with file anchors (may be `active` or `superseded`; optional pin) |
 | **Edge** | Links (claim → flow → component); `kind: "supersedes"` archives the target claim |
 | **Draft** | Pending session / miss→learn proposals waiting for Memory approve |
+| **Task** | Deferred work on the project Kanban (Backlog / Next / Doing / Blocked / Done) — not a durable fact |
+| **Skill** | A reusable multi-step procedure, stored as a `SKILL.md` file (see below) |
 | **Usage event** | Each `amem context` hit + token estimate |
 
 Claims are the retrieval unit. Ranking combines:
@@ -280,6 +283,60 @@ Example claim:
 
 ---
 
+## Skills (procedural memory)
+
+Claims answer *what is true*. Skills answer *how we do this here* — a deploy sequence, a
+migration dance, a debugging path someone already walked. They are too long to sit in every
+prompt, so they load on demand.
+
+Skills live as `SKILL.md` files under `~/.amem/skills/`, indexed in SQLite for ranking:
+
+```
+~/.amem/skills/deploy-staging/SKILL.md
+~/.amem/skills/deploy-staging/references/runbook.md
+```
+
+**Progressive disclosure.** A context packet carries only names and descriptions. The agent
+calls `amem_skill_view` to pull a body once it decides the procedure applies, so an unused
+library of skills costs almost no tokens.
+
+**The learning loop.** amem ships no model, so it never writes a skill itself. At session end
+it looks for the shape of a hard-won procedure — enumerated steps or real commands, plus an
+error it recovered from or a correction you gave. When several signals line up it queues one
+suggestion, which reaches your agent as a nudge in the next context packet. The agent writes
+the skill; you approve it. If a skill was loaded during a session that still went sideways,
+amem queues a revision instead of a duplicate.
+
+The bar is deliberately high, and a session can queue at most one suggestion.
+
+```bash
+amem skills list                # index of what is stored
+amem skills show deploy-staging # full body
+amem skills new deploy-staging --desc "Deploy staging and verify health"
+amem skills import ./some-skill # bring in an agentskills.io skill
+amem skills drafts              # pending suggestions and staged writes
+amem skills approve <draft-id>
+```
+
+Skills are also a Skills tab in `amem ui`.
+
+**Safety.** Skills are instructions an agent will follow, so content is scanned for
+credentials and prompt-injection patterns before any write. Three policy keys control them:
+
+| Key | Default | Effect |
+| --- | --- | --- |
+| `skills_enabled` | `true` | Master switch for storage, ranking, and injection |
+| `skill_write_approval` | `false` | Stage agent writes for review instead of writing to disk |
+| `skill_capture` | `true` | Allow session-end skill suggestions |
+
+An unreadable `policy.toml` forces `skill_write_approval` on. `amem doctor --attest` reports
+every installed skill with a content hash, so you can diff what agents are being told to do.
+
+> Backups currently copy the database only — `~/.amem/skills/` is not included yet. Keep
+> skills you care about in version control until that lands.
+
+---
+
 ## Token savings (estimates)
 
 Every `amem context` logs a usage event. The UI **Stats** tab breaks this down by platform (`cursor`, `claude`, …).
@@ -380,6 +437,9 @@ MCP tools (stdio or HTTP):
 | `amem_context` | Ranked memory packet for the current question |
 | `amem_remember` | Store a durable fact after an outcome |
 | `amem_recipe` | Generic read-then-write contract (any MCP host) |
+| `amem_skill_list` | Cheap index of stored procedures (names + descriptions only) |
+| `amem_skill_view` | Load one skill body, after the index says it applies |
+| `amem_skill_save` | Store a multi-step procedure you just worked out |
 | `amem_repos` | What is monitored (git repos + named workspaces) |
 | `amem_stats` | Lookup time, estimated tokens/ms saved, hit rate |
 | `amem_graph` | Claims / components / flows stored for a workspace or repo |
@@ -400,6 +460,8 @@ amem doctor [--attest] [--json]
 amem context "<query>" [--workspace <name>] [--platform …]
 amem remember "<text>" [--workspace <name>] [--kind …] [--anchor <path>]
 amem recipe [--json]
+amem skills list|show <name>|new <name> [--desc <text>]|rm <name>|sync|import <path>
+amem skills drafts|approve <draft-id>|dismiss <draft-id>
 amem mcp [--print-config] [--workspace <name>]
 amem propose validate|diff|apply <file.json>
 amem export [--out <file.json>]
@@ -428,6 +490,7 @@ amem service install|uninstall|status
 | `context` | Retrieve a Markdown packet; log usage |
 | `remember` | Store one local fact |
 | `mcp` | Stdio MCP tools; HTTP MCP at `http://127.0.0.1:7843/mcp` while UI runs |
+| `skills` | Manage procedural memory (`list`, `show`, `new`, `import`, `drafts`, `approve`) |
 | `propose diff` | Preview claim/component/flow changes before apply |
 | `propose apply` | Upsert structured memory locally |
 | `lock` / `unlock` | Optional AES-256-GCM encrypt-at-rest for `graph.db` |

package/dist/api/routes.js

@@ -1,14 +1,31 @@
 import { existsSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { createHash } from "node:crypto";
-import { estimateUsdSaved, metricsFromPacket, USD_PER_MILLION_INPUT_TOKENS } from "../estimate.js";
+import { estimateUsdSaved, metricsFromPacket, savingsBasis, USD_PER_MILLION_INPUT_TOKENS, } from "../estimate.js";
 import { buildActivityGraph, speedForEvent } from "../activity.js";
-import { getRepoByCwd, getRepoById, getRepoByName, renameWorkspace, getSetupState, insertUsageEvent, listClaims, listClaimsAll, listComponents, listComponentsAll, listEdges, listEdgesAll, listFlows, listFlowsAll, listRepos, listSessions, listSessionsAll, listUsageEvents, listProposalDrafts, listProposalDraftsAll, countProposalDrafts, countProposalDraftsAll, getProposalDraft, setProposalDraftStatus, updateClaim, setClaimPinned, deleteClaim, setReportedOnLatest, setReportedTokensSaved, upsertRepo, upsertSetupState, wipeRepo, openDb, closeDb, } from "../db.js";
+import { getRepoByCwd, getRepoById, getRepoByName, renameWorkspace, getSetupState, insertUsageEvent, listClaims, listClaimsAll, listComponents, listComponentsAll, listEdges, listEdgesAll, listFlows, listFlowsAll, listRepos, listSessions, listSessionsAll, listUsageEvents, listProposalDrafts, listProposalDraftsAll, countProposalDrafts, countProposalDraftsAll, getProposalDraft, setProposalDraftStatus, listTasks, listTasksAll, getSkillDraft, insertSkillDraft, listSkillDrafts, recordSkillUse, setSkillDraftStatus, setSkillRepo, findTaskAnyRepo, getTask, insertTask, updateTask, completeTask, deleteTask, countTasks, countTasksAll, normalizeTaskStatus, updateClaim, setClaimPinned, deleteClaim, setReportedOnLatest, setReportedTokensSaved, upsertRepo, upsertSetupState, wipeRepo, openDb, closeDb, } from "../db.js";
+import { deleteSkill, findSkillOnDisk, isValidSkillName, listIndexedSkills, listSkillAssets, rankSkills, readSkillAsset, readSkillBody, renderSkillMarkdown, scanSkillContent, skillsDir, slugifySkillName, syncSkillIndex, writeSkill, } from "../skills.js";
 import { buildContext, buildRetrievalShowdown, decorateUsageEvents, renderContextMarkdown } from "../context.js";
 import { installClaude, claudeInstallHealth } from "../install/claude.js";
 import { installCursor, cursorInstallHealth } from "../install/cursor.js";
 import { hostInstallHealth, installHost } from "../install/hosts.js";
 import { decorateDraft, decorateDrafts } from "../draft-quality.js";
+/**
+ * Which repo owns a task. Scoped requests may only touch the current repo; an
+ * all-memory request resolves the task's real owner so a board that shows every
+ * memory can also edit what it shows.
+ */
+function taskOwnerRepoId(id, currentRepoId, all) {
+    if (currentRepoId) {
+        const direct = getTask(currentRepoId, id);
+        if (direct)
+            return currentRepoId;
+    }
+    if (all) {
+        return findTaskAnyRepo(id)?.repo_id ?? null;
+    }
+    return null;
+}
 import { isUsefulRememberText } from "../capture.js";
 import { buildSavingsExport, formatSavingsMarkdown, savingsPdf, } from "../savings-export.js";
 import { assertPlatformAllowed, assertRemoteAllowed, loadPolicy, } from "../policy.js";
@@ -58,6 +75,40 @@ function ok(body) {
 function err(status, message) {
     return { status, body: { error: message } };
 }
+function safeJsonArray(raw) {
+    try {
+        const list = JSON.parse(raw);
+        return Array.isArray(list) ? list.filter((v) => typeof v === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Once a skill is saved, the nudge that prompted it has done its job. */
+function resolveSuggestionFor(repoId, sessionId) {
+    if (!repoId)
+        return;
+    for (const draft of listSkillDrafts({ status: "pending", repoId, limit: 20 })) {
+        if (draft.kind !== "suggestion")
+            continue;
+        if (sessionId && draft.session_id && draft.session_id !== sessionId)
+            continue;
+        setSkillDraftStatus(draft.id, "applied");
+        return;
+    }
+}
+/** Level-0 view of a skill: enough to decide whether to load it, without the body. */
+function skillSummary(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        version: skill.version,
+        tags: skill.tags,
+        source: skill.source,
+        repo_id: skill.repoId ?? null,
+        uses: skill.uses ?? 0,
+    };
+}
 function bodyField(body, key) {
     if (!body || typeof body !== "object")
         return undefined;
@@ -307,10 +358,14 @@ function aggregateUsage(events, windowDays = 30) {
     }
     const queries = events.length;
     const estimatedTokensSaved = events.reduce((s, e) => s + e.estimated_tokens_saved, 0);
+    const reportedTokensSaved = events.reduce((s, e) => s + (e.reported_tokens_saved ?? 0), 0);
     return {
         pricing: {
             usdPerMillionInputTokens: USD_PER_MILLION_INPUT_TOKENS,
             basis: "input",
+            // How much to trust the numbers below. Until reported savings exist,
+            // every "saved" figure is a model, and callers must say so.
+            ...savingsBasis(reportedTokensSaved),
         },
         byPlatform: Object.values(byPlatform).map((p) => ({
             ...p,
@@ -327,7 +382,7 @@ function aggregateUsage(events, windowDays = 30) {
             queries,
             estimatedTokensSaved,
             estimatedUsdSaved: estimateUsdSaved(estimatedTokensSaved),
-            reportedTokensSaved: events.reduce((s, e) => s + (e.reported_tokens_saved ?? 0), 0),
+            reportedTokensSaved,
             estimatedMsSaved,
             localHits,
             serverTrips,
@@ -1242,6 +1297,285 @@ export function handleApi(req) {
             return err(404, "Claim not found");
         return ok({ deleted: id });
     }
+    // Skills are a global library, not repo-scoped like claims and tasks — no `repo` guard.
+    if (method === "GET" && pathname === "/api/skills") {
+        const query = searchParams.get("q") || "";
+        const skills = listIndexedSkills();
+        const ranked = query ? rankSkills(skills, query, Number(searchParams.get("limit") || 10)) : [];
+        return ok({
+            skills: skills.map(skillSummary),
+            matches: ranked.map((s) => ({ ...skillSummary(s), score: s.score, reasons: s.reasons })),
+            dir: skillsDir(),
+        });
+    }
+    if (method === "GET" && pathname === "/api/skills/view") {
+        const name = searchParams.get("name");
+        if (!name)
+            return err(400, "name required");
+        const file = searchParams.get("file");
+        if (file) {
+            const asset = readSkillAsset(name, file);
+            if (asset === null)
+                return err(404, "Skill file not found");
+            return ok({ name, file, content: asset });
+        }
+        const meta = findSkillOnDisk(name);
+        if (!meta)
+            return err(404, "Skill not found");
+        const content = readSkillBody(name);
+        if (content === null)
+            return err(404, "Skill not found");
+        // A skill can be viewed before anything indexed it, and the usage counter lives in
+        // the index — reconcile first or the increment silently updates zero rows.
+        syncSkillIndex();
+        recordSkillUse(meta.name, {
+            repoId: repo ? repo.id : null,
+            sessionId: searchParams.get("session_id"),
+        });
+        return ok({ ...skillSummary(meta), content, files: listSkillAssets(meta.name) });
+    }
+    if (method === "POST" && pathname === "/api/skills") {
+        const name = bodyField(body, "name");
+        if (!name)
+            return err(400, "name required");
+        const slug = slugifySkillName(name);
+        if (!isValidSkillName(slug))
+            return err(400, "Invalid skill name");
+        const content = bodyField(body, "content");
+        const description = bodyField(body, "description") || "";
+        // Accept either a full SKILL.md or the parts, so agents can save without templating.
+        const markdown = content && content.includes("---")
+            ? content
+            : renderSkillMarkdown({
+                name: slug,
+                description,
+                body: content || "",
+                version: bodyField(body, "version"),
+            });
+        const scan = scanSkillContent(markdown);
+        if (!scan.ok)
+            return err(400, `Rejected: ${scan.reason}`);
+        const policy = loadPolicy().policy;
+        if (!policy.skills_enabled)
+            return err(403, "Skills are disabled by policy");
+        // A SKILL.md is too long to review inline, so an approval gate stages rather than
+        // blocks — the agent keeps working and a human decides later.
+        if (policy.skill_write_approval) {
+            const draft = insertSkillDraft({
+                repoId: repo ? repo.id : null,
+                name: slug,
+                title: description || slug,
+                summary: description,
+                content: markdown,
+                kind: findSkillOnDisk(slug) ? "revision" : "create",
+                targetSkill: findSkillOnDisk(slug) ? slug : null,
+                source: `agent-save:${slug}:${Date.now()}`,
+                sessionId: bodyField(body, "session_id") ?? null,
+                reasons: ["staged by skill_write_approval"],
+            });
+            return ok({
+                staged: draft.id,
+                name: slug,
+                pending: true,
+                message: "Skill staged for review — approve it in the Skills tab or `amem skills drafts`.",
+            });
+        }
+        const written = writeSkill(slug, markdown);
+        syncSkillIndex();
+        const repoId = bodyField(body, "repo_id") ?? (repo ? repo.id : null);
+        if (repoId)
+            setSkillRepo(slug, repoId);
+        resolveSuggestionFor(repo?.id, bodyField(body, "session_id"));
+        return ok({ saved: written.name, path: written.path, hash: written.hash });
+    }
+    if (method === "GET" && pathname === "/api/skills/drafts") {
+        const drafts = listSkillDrafts({
+            status: searchParams.get("status") || "pending",
+            limit: Number(searchParams.get("limit") || 50),
+        });
+        const repoNames = new Map(listRepos().map((r) => [r.id, r.repo_name]));
+        return ok({
+            drafts: drafts.map((d) => ({
+                ...d,
+                reasons: safeJsonArray(d.reasons),
+                repo_name: d.repo_id ? (repoNames.get(d.repo_id) ?? null) : null,
+                // A suggestion has no content yet — only an agent can write the body.
+                has_content: Boolean(d.content),
+            })),
+            counts: { pending: listSkillDrafts({ status: "pending", limit: 200 }).length },
+        });
+    }
+    if (method === "POST" && pathname === "/api/skills/drafts/apply") {
+        const id = bodyField(body, "id");
+        if (!id)
+            return err(400, "id required");
+        const draft = getSkillDraft(id);
+        if (!draft)
+            return err(404, "Draft not found");
+        if (!draft.content || !draft.name) {
+            return err(400, "This is a suggestion, not a staged skill — an agent must write it first");
+        }
+        const scan = scanSkillContent(draft.content);
+        if (!scan.ok)
+            return err(400, `Rejected: ${scan.reason}`);
+        const written = writeSkill(draft.name, draft.content);
+        syncSkillIndex();
+        if (draft.repo_id)
+            setSkillRepo(draft.name, draft.repo_id);
+        setSkillDraftStatus(id, "applied");
+        return ok({ applied: id, name: written.name, path: written.path });
+    }
+    if (method === "POST" && pathname === "/api/skills/drafts/dismiss") {
+        const id = bodyField(body, "id");
+        if (!id)
+            return err(400, "id required");
+        if (!getSkillDraft(id))
+            return err(404, "Draft not found");
+        setSkillDraftStatus(id, "dismissed");
+        return ok({ dismissed: id });
+    }
+    if (method === "DELETE" && pathname === "/api/skills") {
+        const name = searchParams.get("name") || bodyField(body, "name");
+        if (!name)
+            return err(400, "name required");
+        const removed = deleteSkill(name);
+        if (!removed)
+            return err(404, "Skill not found");
+        syncSkillIndex();
+        return ok({ deleted: slugifySkillName(name) });
+    }
+    if (method === "GET" && pathname === "/api/tasks") {
+        const all = searchParams.get("scope") === "all" ||
+            bodyField(body, "scope") === "all" ||
+            searchParams.get("repo") === "all";
+        if (!all && !repo)
+            return err(400, "Repo not initialized");
+        const statusRaw = searchParams.get("status") || bodyField(body, "status");
+        const status = statusRaw ? normalizeTaskStatus(statusRaw) : null;
+        if (statusRaw && !status)
+            return err(400, "invalid status");
+        const includeDone = searchParams.get("include_done") === "1" ||
+            searchParams.get("include_done") === "true" ||
+            bodyField(body, "include_done") === "1" ||
+            bodyField(body, "include_done") === "true";
+        const listOpts = {
+            status: status || undefined,
+            includeDone: includeDone || Boolean(status === "done"),
+            limit: Number(searchParams.get("limit") || (all ? 200 : 100)),
+        };
+        const tasks = all ? listTasksAll(listOpts) : listTasks(repo.id, listOpts);
+        const count = (o) => all ? countTasksAll(o) : countTasks(repo.id, o);
+        // Name the owning memory so an all-memory board can say where each task lives.
+        const repoNames = all
+            ? new Map(listRepos().map((r) => [r.id, r.repo_name]))
+            : new Map();
+        return ok({
+            scope: all ? "all" : "current",
+            tasks: all
+                ? tasks.map((t) => ({ ...t, repo_name: repoNames.get(t.repo_id) ?? null }))
+                : tasks,
+            counts: {
+                open: count({ openOnly: true }),
+                backlog: count({ status: "backlog" }),
+                next: count({ status: "next" }),
+                doing: count({ status: "doing" }),
+                blocked: count({ status: "blocked" }),
+                done: count({ status: "done" }),
+            },
+        });
+    }
+    if (method === "POST" && pathname === "/api/tasks") {
+        const targetRepo = repo || ensurePersonalWorkspace();
+        const payload = body && typeof body === "object" ? body : {};
+        const title = typeof payload.title === "string" ? payload.title : "";
+        if (!title.trim())
+            return err(400, "title required");
+        let anchors;
+        if (Array.isArray(payload.anchors)) {
+            anchors = payload.anchors.filter((a) => typeof a === "string");
+        }
+        try {
+            const task = insertTask({
+                repoId: targetRepo.id,
+                title,
+                body: typeof payload.body === "string" ? payload.body : "",
+                status: typeof payload.status === "string" ? payload.status : "backlog",
+                anchors,
+                source: typeof payload.source === "string" ? payload.source : "ui",
+            });
+            return ok({ task });
+        }
+        catch (error) {
+            return err(400, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (method === "PATCH" && pathname === "/api/tasks") {
+        const all = searchParams.get("scope") === "all" ||
+            bodyField(body, "scope") === "all" ||
+            searchParams.get("repo") === "all";
+        if (!all && !repo)
+            return err(400, "Repo not initialized");
+        const payload = body && typeof body === "object" ? body : {};
+        const id = bodyField(body, "id");
+        if (!id)
+            return err(400, "id required");
+        // In all-memory scope the card may belong to any repo, so find its real owner.
+        const ownerId = taskOwnerRepoId(id, repo?.id, all);
+        if (!ownerId)
+            return err(404, "Task not found");
+        let anchors;
+        if (Array.isArray(payload.anchors)) {
+            anchors = payload.anchors.filter((a) => typeof a === "string");
+        }
+        try {
+            const task = updateTask(ownerId, id, {
+                title: typeof payload.title === "string" ? payload.title : undefined,
+                body: typeof payload.body === "string" ? payload.body : undefined,
+                status: typeof payload.status === "string" ? payload.status : undefined,
+                anchors,
+            });
+            if (!task)
+                return err(404, "Task not found");
+            return ok({ task });
+        }
+        catch (error) {
+            return err(400, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (method === "POST" && pathname === "/api/tasks/complete") {
+        const all = searchParams.get("scope") === "all" ||
+            bodyField(body, "scope") === "all" ||
+            searchParams.get("repo") === "all";
+        if (!all && !repo)
+            return err(400, "Repo not initialized");
+        const id = bodyField(body, "id");
+        if (!id)
+            return err(400, "id required");
+        const ownerId = taskOwnerRepoId(id, repo?.id, all);
+        if (!ownerId)
+            return err(404, "Task not found");
+        const task = completeTask(ownerId, id);
+        if (!task)
+            return err(404, "Task not found");
+        return ok({ task });
+    }
+    if (method === "DELETE" && pathname === "/api/tasks") {
+        const all = searchParams.get("scope") === "all" ||
+            bodyField(body, "scope") === "all" ||
+            searchParams.get("repo") === "all";
+        if (!all && !repo)
+            return err(400, "Repo not initialized");
+        const id = searchParams.get("id") || bodyField(body, "id");
+        if (!id)
+            return err(400, "id required");
+        const ownerId = taskOwnerRepoId(id, repo?.id, all);
+        if (!ownerId)
+            return err(404, "Task not found");
+        const removed = deleteTask(ownerId, id);
+        if (!removed)
+            return err(404, "Task not found");
+        return ok({ deleted: id });
+    }
     if (method === "GET" && pathname === "/api/usage/export") {
         const scope = searchParams.get("scope") ?? "current";
         const days = Number(searchParams.get("days") ?? "30");

package/dist/attest.d.ts

@@ -38,6 +38,19 @@ export type AttestReport = {
     };
     license: ReturnType<typeof licenseStatus>;
     embed: ReturnType<typeof embedStatus>;
+    /** Procedural memory an auditor should be able to review: what agents may be told to do. */
+    skills: {
+        dir: string;
+        enabled: boolean;
+        write_approval: boolean;
+        pending_drafts: number;
+        installed: Array<{
+            name: string;
+            description: string;
+            source: string;
+            hash: string;
+        }>;
+    };
     sku?: {
         tier: string;
         airgap: true;

package/dist/attest.js

@@ -12,6 +12,8 @@ import { FEATURE_ATTEST_SKU, hasFeature, licenseStatus } from "./license.js";
 import { embedIndexIssues, embedStatus } from "./embed.js";
 import { vaultStatus } from "./vault.js";
 import { hostInstallHealth } from "./install/hosts.js";
+import { listSkillDrafts } from "./db.js";
+import { scanSkills, skillsDir } from "./skills.js";
 function packageRoot() {
     const here = fileURLToPath(new URL(".", import.meta.url));
     // dist/ -> package root
@@ -104,6 +106,8 @@ export function buildAttestReport(cwd = process.cwd()) {
     catch {
         // Locked vault: the vault section already reports that.
     }
+    const skills = skillsAttestSection();
+    issues.push(...skillIssues(skills));
     const pkgPath = join(packageRoot(), "package.json");
     const sku = hasFeature(FEATURE_ATTEST_SKU)
         ? {
@@ -154,11 +158,51 @@ export function buildAttestReport(cwd = process.cwd()) {
         },
         license,
         embed,
+        skills,
         sku,
         ok: issues.length === 0,
         issues,
     };
 }
+/**
+ * Inventory of procedural memory. Hashes let an auditor diff what agents are being told to
+ * do between two machines, which a bare list of names would not support.
+ */
+function skillsAttestSection() {
+    const policy = loadPolicy().policy;
+    const base = {
+        dir: skillsDir(),
+        enabled: policy.skills_enabled,
+        write_approval: policy.skill_write_approval,
+    };
+    try {
+        return {
+            ...base,
+            pending_drafts: listSkillDrafts({ status: "pending", limit: 200 }).length,
+            installed: scanSkills().map((s) => ({
+                name: s.name,
+                description: s.description,
+                source: s.source,
+                hash: s.hash,
+            })),
+        };
+    }
+    catch {
+        return { ...base, pending_drafts: 0, installed: [] };
+    }
+}
+function skillIssues(skills) {
+    const issues = [];
+    for (const skill of skills.installed) {
+        if (!skill.description.trim()) {
+            issues.push(`skill ${skill.name} has no description — agents cannot rank it`);
+        }
+    }
+    if (skills.pending_drafts > 0 && skills.write_approval) {
+        issues.push(`${skills.pending_drafts} skill write(s) awaiting approval`);
+    }
+    return issues;
+}
 export function formatAttestHuman(report) {
     const lines = [
         `amem attest ${report.ok ? "OK" : "ISSUES"} · v${report.version}`,

package/dist/capture.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { PLACEHOLDER_ANCHOR } from "./freshness.js";
 import { insertProposalDraft, listProposalDrafts, listProposalDraftsAll, listUsageEvents, setProposalDraftStatus, } from "./db.js";
-import { compactClaimText, compactFromNotes, inferClaimKind, isDurableCapture } from "./kinds.js";
+import { compactClaimText, compactFromNotes, inferClaimKind, isDurableCapture, isFactLike, } from "./kinds.js";
 import { loadPolicy } from "./policy.js";
 import { applyProposal } from "./proposal.js";
 import { scoreProposal } from "./draft-quality.js";
@@ -49,12 +50,20 @@ function buildClaimDraft(input) {
     }
     const anchors = extractCaptureAnchors(`${input.prompt}\n${input.answer ?? ""}`, input.repoRoot);
     const kind = input.forceKind ?? inferClaimKind(input.prompt, input.answer ?? "");
-    const usableAnchors = anchors.length > 0 ? anchors : kind === "constraint" || kind === "gotcha" ? ["README.md"] : [];
+    const usableAnchors = anchors.length > 0
+        ? anchors
+        : kind === "constraint" || kind === "gotcha"
+            ? [PLACEHOLDER_ANCHOR]
+            : [];
     if (!isDurableCapture(input.prompt, input.answer, usableAnchors.length)) {
         if (usableAnchors.length === 0)
             return null;
     }
     const text = compactClaimText(input.prompt, input.answer);
+    // Single choke point for every capture path. Conversational residue never
+    // becomes a durable claim, however many file paths it happens to mention.
+    if (!isFactLike(text))
+        return null;
     const id = `${input.idPrefix}_${createHash("sha256").update(text).digest("hex").slice(0, 12)}`;
     return {
         id,
@@ -85,7 +94,7 @@ export function shouldAutoApplyProposal(proposal) {
         return false;
     if (!DURABLE_AUTO_KINDS.has((claim.kind || "").toLowerCase()))
         return false;
-    const anchors = (claim.code_anchors ?? []).filter((a) => a && a !== "README.md");
+    const anchors = (claim.code_anchors ?? []).filter((a) => a && a !== PLACEHOLDER_ANCHOR);
     return anchors.length > 0;
 }
 function maybeAutoApplyDraft(repoId, draft, proposal) {
@@ -195,7 +204,7 @@ function extraSessionFacts(input, skipId) {
     const sentences = answer
         .split(/(?<=[.!?])\s+/)
         .map((s) => s.replace(/\s+/g, " ").trim())
-        .filter((s) => s.length >= 48 && [...s.matchAll(PATH_RE)].length > 0);
+        .filter((s) => s.length >= 48 && [...s.matchAll(PATH_RE)].length > 0 && isFactLike(s));
     const out = [];
     for (const sentence of sentences.slice(0, 3)) {
         const built = buildClaimDraft({
@@ -251,7 +260,7 @@ export function captureMissLearnDraft(input) {
     });
     if (!built)
         return null;
-    const realAnchors = built.anchors.filter((a) => a !== "README.md");
+    const realAnchors = built.anchors.filter((a) => a !== PLACEHOLDER_ANCHOR);
     if (realAnchors.length === 0)
         return null;
     built.proposal.claims[0].code_anchors = realAnchors;