daftari 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-06-07
+
+### Added
+
+- **`daftari backfill` git-driven frontmatter migration** (cortex consolidation
+  loop §11.1). A CLI command that adopts an existing wiki into Daftari without a
+  manual migration sprint: it walks the vault, derives frontmatter defaults
+  deterministically (no LLM calls) from git history and body conventions, and
+  writes them per-folder on human ratification. Two-step plan/apply:
+  `daftari backfill --plan [--scope <folder>]` derives proposals and stages them
+  to `.daftari/backfill-plan.jsonl` (modifying no markdown), and
+  `daftari backfill --apply --scope <folder> [--yes]` writes the proposals for
+  one folder and commits them in a single commit (honoring the vault's
+  `auto_commit` setting — with `auto_commit: false` the files are written but
+  the caller owns git, matching the other write tools). `--scope` is required on
+  apply so a whole-vault write can never happen by accident. Derivation: `title`
+  from the first H1 (else the filename), `created`/`updated`/`updated_by` from
+  git (`--diff-filter=A` first-add, last-commit, author through an optional
+  `backfill.identity_map` in `.daftari/config.yaml`), `collection` from the
+  parent folder, and `status: canonical` / `confidence: medium` /
+  `provenance: direct` / `domain: accumulation` defaults — explicitly suggested,
+  ratified by a human, never asserted. Existing frontmatter is preserved
+  field-by-field; a doc whose frontmatter already validates is reported
+  conformant and skipped. The plan is transient: backfill never stages or
+  commits it (apply stages only the doc paths), the apply commit is the durable
+  audit trail, and `.daftari/backfill-plan.jsonl` is added to the `daftari
+  --init` .gitignore template (a `--plan` run also prints a reminder to gitignore
+  it on wikis not scaffolded by Daftari). CLI-only for v1 — no MCP tool. See
+  [docs/superpowers/specs/2026-06-06-cortex-consolidation-loop-design-direction.md](docs/superpowers/specs/2026-06-06-cortex-consolidation-loop-design-direction.md)
+  §11.1.
+- **Staged-action queue + `vault_ratify`** (cortex loop §11.2). A persistent
+  queue of proposed vault changes awaiting human ratification — the foundation
+  for the consolidation loop's "always-stage" tier. Two new MCP tools:
+  `vault_stage_action` (producer; normally the curation loop, exposed for
+  testing and future callers) records a proposed `promote` / `deprecate` /
+  `supersede` / `merge` / `confidence-up` action with a rationale, a proposed
+  diff, and a TTL (default 14 days); `vault_ratify` (consumer) lets a human
+  `approve` or `reject` one pending action. On approve, it dispatches to the
+  existing write path — `promote` → `vault_promote`, `deprecate` →
+  `vault_deprecate` (both auto-commit). `supersede` / `merge` / `confidence-up`
+  are staged only in v1 (their write tools are deferred to §11.4); approving
+  one returns `applied: false` with `deferred_to: "§11.4"` and a
+  `ratified-pending-tool` status. Storage mirrors the rest of Daftari: an
+  append-only canonical log at `.daftari/staged-actions.jsonl` (the source of
+  truth) plus a derived `staged_actions` table in the ephemeral
+  `.daftari/index.db`, rebuilt from the jsonl on reindex and startup.
+  `vault_lint` gains a "Staged actions" section listing pending actions
+  soonest-to-expire first, and expires actions past their TTL as a housekeeping
+  sweep on each invocation. See
+  [docs/superpowers/specs/2026-06-06-cortex-consolidation-loop-design-direction.md](docs/superpowers/specs/2026-06-06-cortex-consolidation-loop-design-direction.md)
+  §11.2.
+
 ## [1.16.0] - 2026-06-02
 
 ### Added

package/dist/backfill/apply.d.ts

@@ -0,0 +1,14 @@
+import { type Result } from "../frontmatter/types.js";
+export interface SkippedDoc {
+    path: string;
+    reason: string;
+}
+export interface ApplyResult {
+    scope: string;
+    applied: string[];
+    unchanged: string[];
+    skipped: SkippedDoc[];
+    commit: string | null;
+}
+export declare function applyPlan(vaultRoot: string, scope: string, agent: string): Promise<Result<ApplyResult, Error>>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/backfill/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/backfill/apply.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAM,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAU1D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IAEd,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,OAAO,EAAE,UAAU,EAAE,CAAC;IAEtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAkCD,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAwErC"}

package/dist/backfill/apply.js

@@ -0,0 +1,111 @@
+// Plan application for `daftari backfill` (§11.1).
+//
+// `applyPlan` reads the plan, takes only the entries under the given scope
+// (per-folder ratification), and writes each doc's proposed frontmatter through
+// the same primitives the write tools use: validate, serialize, then one git
+// commit for the whole scope. The body is taken from the file on disk at apply
+// time, so a body edited between plan and apply is preserved; only frontmatter
+// is filled.
+//
+// --scope is required (the CLI enforces it) so a whole-vault write can never
+// happen by accident. The run is idempotent: a doc whose on-disk content
+// already equals the proposed serialization is left untouched, so re-applying
+// an already-applied folder is a no-op (and never produces an empty commit).
+import { writeFile } from "node:fs/promises";
+import { recordProvenance } from "../curation/provenance.js";
+import { parseDocument } from "../frontmatter/parser.js";
+import { validateFrontmatter } from "../frontmatter/schema.js";
+import { ok } from "../frontmatter/types.js";
+import { readFile, resolveVaultPath } from "../storage/local.js";
+import { serializeDocument } from "../tools/write.js";
+import { loadConfig } from "../utils/config.js";
+import { commit } from "../utils/git.js";
+import { planPath, readPlan } from "./plan.js";
+// Serializes one plan entry against the file's current body. Returns the new
+// file text, or a reason it cannot be written.
+function renderEntry(entry, currentText, extensions) {
+    const parsed = parseDocument(currentText);
+    if (!parsed.ok)
+        return parsed;
+    // Guard: never write frontmatter the validator would reject. A non-conformant
+    // doc whose *present* field is itself malformed (so preservation carries the
+    // bad value through) is reported, not written.
+    const { report } = validateFrontmatter(entry.proposed);
+    if (!report.valid) {
+        const summary = report.issues.map((i) => `${i.field}: ${i.message}`).join("; ");
+        return { ok: false, error: new Error(`proposed frontmatter is invalid: ${summary}`) };
+    }
+    // Preserve any config-extension fields present on disk by passing the current
+    // raw frontmatter through to the serializer.
+    const text = serializeDocument(entry.proposed, parsed.value.content, extensions, parsed.value.raw);
+    return ok(text);
+}
+// Applies all plan entries under `scope`. Writes only changed docs and commits
+// them in a single commit authored by `agent`.
+export async function applyPlan(vaultRoot, scope, agent) {
+    const plan = await readPlan(planPath(vaultRoot));
+    if (!plan.ok)
+        return plan;
+    const config = loadConfig(vaultRoot);
+    if (!config.ok)
+        return config;
+    const extensions = config.value.schemaExtensions;
+    const inScope = plan.value.filter((e) => e.scope === scope);
+    const applied = [];
+    const unchanged = [];
+    const skipped = [];
+    for (const entry of inScope) {
+        const resolved = resolveVaultPath(vaultRoot, entry.path);
+        if (!resolved.ok) {
+            skipped.push({ path: entry.path, reason: resolved.error.message });
+            continue;
+        }
+        const existing = await readFile(resolved.value);
+        if (!existing.ok) {
+            skipped.push({ path: entry.path, reason: existing.error.message });
+            continue;
+        }
+        const rendered = renderEntry(entry, existing.value, extensions);
+        if (!rendered.ok) {
+            skipped.push({ path: entry.path, reason: rendered.error.message });
+            continue;
+        }
+        // Idempotence: identical bytes → no write, no stage, no commit churn.
+        if (rendered.value === existing.value) {
+            unchanged.push(entry.path);
+            continue;
+        }
+        try {
+            await writeFile(resolved.value, rendered.value, "utf-8");
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            skipped.push({ path: entry.path, reason: `write failed: ${reason}` });
+            continue;
+        }
+        applied.push(entry.path);
+    }
+    // One commit for the whole scope. Skipped entirely when nothing changed (no
+    // empty commits) or when the vault is configured with auto_commit: false.
+    let commitHash = null;
+    if (applied.length > 0 && config.value.autoCommit) {
+        const message = `vault_backfill: ${scope} — ${applied.length} ` +
+            `${applied.length === 1 ? "doc" : "docs"} frontmatter backfilled by ${agent}`;
+        const committed = await commit(vaultRoot, applied, message, agent);
+        if (!committed.ok)
+            return committed;
+        commitHash = committed.value.hash;
+    }
+    // Advisory provenance, per applied doc. Best-effort: a log failure does not
+    // fail the backfill (the commit is the durable record).
+    for (const path of applied) {
+        await recordProvenance(vaultRoot, {
+            tool: "vault_backfill",
+            file: path,
+            agent,
+            action: "backfill",
+        });
+    }
+    return ok({ scope, applied, unchanged, skipped, commit: commitHash });
+}
+//# sourceMappingURL=apply.js.map

package/dist/backfill/apply.js.map

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

package/dist/backfill/derive.d.ts

@@ -0,0 +1,25 @@
+import type { Frontmatter } from "../frontmatter/types.js";
+import type { FileGitMeta } from "../utils/git.js";
+import type { DerivationMap, DocClassification } from "./types.js";
+export declare function slugify(value: string): string;
+export declare function firstH1(body: string): string | null;
+export declare function titleFromFilename(relPath: string): string;
+export declare function parseQuestionSection(body: string, heading: string): string[];
+export declare function mapIdentity(author: string, identityMap: Record<string, string>): string;
+export declare function classifyDoc(raw: Record<string, unknown>): DocClassification;
+export interface DeriveInputs {
+    relPath: string;
+    body: string;
+    raw: Record<string, unknown>;
+    coerced: Frontmatter;
+    git: FileGitMeta;
+    mtimeDate: string;
+    identityMap: Record<string, string>;
+    invoker: string;
+}
+export interface DerivedFrontmatter {
+    proposed: Frontmatter;
+    derivation: DerivationMap;
+}
+export declare function deriveProposed(input: DeriveInputs): DerivedFrontmatter;
+//# sourceMappingURL=derive.d.ts.map

package/dist/backfill/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/backfill/derive.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAInE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7C;AAID,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMnD;AAID,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzD;AAKD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAqB5E;AAID,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAIvF;AAeD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAG3E;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IAEb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAG7B,OAAO,EAAE,WAAW,CAAC;IACrB,GAAG,EAAE,WAAW,CAAC;IAEjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,aAAa,CAAC;CAC3B;AAKD,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,kBAAkB,CA6EtE"}

package/dist/backfill/derive.js

@@ -0,0 +1,142 @@
+// Deterministic frontmatter derivation for `daftari backfill` (§11.1).
+//
+// No LLM calls: every value comes from git metadata, body conventions, the
+// path, or a fixed default. The contract is "suggest, don't assert" — adopted
+// docs are proposed as canonical/medium/direct, but a human ratifies per folder
+// before anything is written. Existing frontmatter is never overwritten: a
+// present field is preserved verbatim, only missing fields are filled.
+import { validateFrontmatter } from "../frontmatter/schema.js";
+// kebab-case a free-form string: lowercase, non-alphanumerics → single hyphen,
+// trimmed. Used for collection names and the identity fallback slug.
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+// The first ATX H1 (`# Title`) in the body, or null. Only a single leading `#`
+// counts — `##` and deeper are sub-headings, not the document title.
+export function firstH1(body) {
+    for (const line of body.split(/\r?\n/)) {
+        const m = line.match(/^#\s+(.+?)\s*#*\s*$/);
+        if (m)
+            return m[1].trim();
+    }
+    return null;
+}
+// Title-cased title derived from a filename when the body has no H1. Strips the
+// `.md`, splits the basename on `-`/`_`, and capitalizes each word.
+export function titleFromFilename(relPath) {
+    const base = (relPath.split("/").pop() ?? relPath).replace(/\.md$/i, "");
+    const words = base.split(/[-_]+/).filter((w) => w.length > 0);
+    if (words.length === 0)
+        return base;
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+// Bullet items under a `## <heading>` section, in order. Collection stops at the
+// next heading of any level. Placeholder bullets (empty, or fully parenthical
+// like "(none yet)") are dropped — they are scaffolding, not real questions.
+export function parseQuestionSection(body, heading) {
+    const lines = body.split(/\r?\n/);
+    const target = heading.toLowerCase();
+    const out = [];
+    let inSection = false;
+    for (const line of lines) {
+        const headingMatch = line.match(/^#{1,6}\s+(.+?)\s*#*\s*$/);
+        if (headingMatch) {
+            const text = headingMatch[1].trim().toLowerCase();
+            inSection = text === target;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const bullet = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+        if (!bullet)
+            continue;
+        const item = bullet[1].trim();
+        if (item.length === 0)
+            continue;
+        if (item.startsWith("(") && item.endsWith(")"))
+            continue;
+        out.push(item);
+    }
+    return out;
+}
+// Maps a git author name to a Daftari identity: an explicit identity_map entry
+// wins; otherwise the default `human:<slug>` fallback.
+export function mapIdentity(author, identityMap) {
+    const mapped = identityMap[author];
+    if (mapped)
+        return mapped;
+    return `human:${slugify(author) || "unknown"}`;
+}
+// A frontmatter field is "present" — and therefore preserved — when the raw
+// YAML carries a non-null, non-empty-string value for it. Empty arrays count as
+// present (the author wrote `[]` deliberately).
+function isPresent(raw, field) {
+    const v = raw[field];
+    if (v === undefined || v === null)
+        return false;
+    if (typeof v === "string" && v.length === 0)
+        return false;
+    return true;
+}
+// Whether a document needs backfilling. A doc whose existing frontmatter
+// already validates against the built-in schema is conformant and skipped;
+// otherwise it is `missing` (no frontmatter at all) or `partial`.
+export function classifyDoc(raw) {
+    if (validateFrontmatter(raw).report.valid)
+        return "conformant";
+    return Object.keys(raw).length === 0 ? "missing" : "partial";
+}
+// Builds the full proposed frontmatter for a non-conformant doc plus a per-field
+// derivation map. Present fields are preserved (coerced value, label
+// "preserved"); missing fields are derived from git / body / path / defaults.
+export function deriveProposed(input) {
+    const { relPath, body, raw, coerced, git, mtimeDate, identityMap, invoker } = input;
+    const derivation = {};
+    // Resolves one field: if present in raw, preserve the coerced value; else use
+    // the derived value. Records the chosen source label either way.
+    function resolve(field, derivedValue, derivedLabel) {
+        if (isPresent(raw, field)) {
+            derivation[field] = "preserved";
+            return coerced[field];
+        }
+        derivation[field] = derivedLabel;
+        return derivedValue;
+    }
+    // title ← H1, else filename.
+    const h1 = firstH1(body);
+    const title = resolve("title", h1 ?? titleFromFilename(relPath), h1 ? "body-h1" : "filename");
+    // collection ← first path component, kebab-cased.
+    const folder = relPath.split("/")[0] ?? "";
+    const collection = resolve("collection", slugify(folder), "parent-folder");
+    // created/updated ← git, else file mtime.
+    const created = resolve("created", git.created ?? mtimeDate, git.created ? "git-first-commit" : "file-mtime");
+    const updated = resolve("updated", git.updated ?? mtimeDate, git.updated ? "git-last-commit" : "file-mtime");
+    // updated_by ← git author mapped through identity config, else invoker.
+    const updatedBy = resolve("updated_by", git.author ? mapIdentity(git.author, identityMap) : invoker, git.author ? "git-author + identity-map" : "invoker-fallback");
+    // questions ← body sections, else empty.
+    const qAnswered = parseQuestionSection(body, "Questions Answered");
+    const qRaised = parseQuestionSection(body, "Questions Raised");
+    const proposed = {
+        title,
+        domain: resolve("domain", "accumulation", "default"),
+        collection,
+        status: resolve("status", "canonical", "default"),
+        confidence: resolve("confidence", "medium", "default"),
+        created,
+        updated,
+        updated_by: updatedBy,
+        provenance: resolve("provenance", "direct", "default"),
+        sources: resolve("sources", [], "empty"),
+        superseded_by: resolve("superseded_by", null, "null"),
+        ttl_days: resolve("ttl_days", null, "null"),
+        tags: resolve("tags", [], "empty"),
+        questions_answered: resolve("questions_answered", qAnswered, qAnswered.length > 0 ? "body-section" : "empty"),
+        questions_raised: resolve("questions_raised", qRaised, qRaised.length > 0 ? "body-section" : "empty"),
+    };
+    return { proposed, derivation };
+}
+//# sourceMappingURL=derive.js.map

package/dist/backfill/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../src/backfill/derive.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,gFAAgF;AAChF,2EAA2E;AAC3E,uEAAuE;AAEvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAK/D,+EAA+E;AAC/E,qEAAqE;AACrE,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,+EAA+E;AAC/E,qEAAqE;AACrE,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;QAC5C,IAAI,CAAC;YAAE,OAAQ,CAAC,CAAC,CAAC,CAAY,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,oEAAoE;AACpE,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5E,CAAC;AAED,iFAAiF;AACjF,8EAA8E;AAC9E,6EAA6E;AAC7E,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,OAAe;IAChE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC5D,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,IAAI,GAAI,YAAY,CAAC,CAAC,CAAY,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC9D,SAAS,GAAG,IAAI,KAAK,MAAM,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,SAAS;YAAE,SAAS;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,IAAI,GAAI,MAAM,CAAC,CAAC,CAAY,CAAC,IAAI,EAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,SAAS;QACzD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,WAAmC;IAC7E,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,OAAO,SAAS,OAAO,CAAC,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;AACjD,CAAC;AAED,4EAA4E;AAC5E,gFAAgF;AAChF,gDAAgD;AAChD,SAAS,SAAS,CAAC,GAA4B,EAAE,KAAa;IAC5D,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IACrB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yEAAyE;AACzE,2EAA2E;AAC3E,kEAAkE;AAClE,MAAM,UAAU,WAAW,CAAC,GAA4B;IACtD,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,YAAY,CAAC;IAC/D,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC;AAwBD,iFAAiF;AACjF,qEAAqE;AACrE,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IACpF,MAAM,UAAU,GAAkB,EAAE,CAAC;IAErC,8EAA8E;IAC9E,iEAAiE;IACjE,SAAS,OAAO,CACd,KAAQ,EACR,YAA4B,EAC5B,YAAoB;QAEpB,IAAI,SAAS,CAAC,GAAG,EAAE,KAAe,CAAC,EAAE,CAAC;YACpC,UAAU,CAAC,KAAe,CAAC,GAAG,WAAW,CAAC;YAC1C,OAAO,OAAO,CAAC,KAAK,CAAmB,CAAC;QAC1C,CAAC;QACD,UAAU,CAAC,KAAe,CAAC,GAAG,YAAY,CAAC;QAC3C,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,6BAA6B;IAC7B,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,iBAAiB,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAE9F,kDAAkD;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC;IAE3E,0CAA0C;IAC1C,MAAM,OAAO,GAAG,OAAO,CACrB,SAAS,EACT,GAAG,CAAC,OAAO,IAAI,SAAS,EACxB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,YAAY,CAChD,CAAC;IACF,MAAM,OAAO,GAAG,OAAO,CACrB,SAAS,EACT,GAAG,CAAC,OAAO,IAAI,SAAS,EACxB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,YAAY,CAC/C,CAAC;IAEF,wEAAwE;IACxE,MAAM,SAAS,GAAG,OAAO,CACvB,YAAY,EACZ,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,EAC3D,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,kBAAkB,CAC9D,CAAC;IAEF,yCAAyC;IACzC,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAE/D,MAAM,QAAQ,GAAgB;QAC5B,KAAK;QACL,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,CAAC;QACpD,UAAU;QACV,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC;QACjD,UAAU,EAAE,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,SAAS,CAAC;QACtD,OAAO;QACP,OAAO;QACP,UAAU,EAAE,SAAS;QACrB,UAAU,EAAE,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,SAAS,CAAC;QACtD,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,EAAE,OAAO,CAAC;QACxC,aAAa,EAAE,OAAO,CAAC,eAAe,EAAE,IAAI,EAAE,MAAM,CAAC;QACrD,QAAQ,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC;QAC3C,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,OAAO,CAAC;QAClC,kBAAkB,EAAE,OAAO,CACzB,oBAAoB,EACpB,SAAS,EACT,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAChD;QACD,gBAAgB,EAAE,OAAO,CACvB,kBAAkB,EAClB,OAAO,EACP,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAC9C;KACF,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAClC,CAAC"}

package/dist/backfill/index.d.ts

@@ -0,0 +1,2 @@
+export declare function runBackfill(argv: string[]): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/backfill/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backfill/index.ts"],"names":[],"mappings":"AA+IA,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8GjE"}

package/dist/backfill/index.js

@@ -0,0 +1,232 @@
+// Top-level entry for `daftari backfill` (§11.1) — git-driven frontmatter
+// migration for adopting an existing wiki into Daftari.
+//
+// Two-step, plan/apply:
+//   daftari backfill --plan [--scope <folder>]   derive + stage to a plan file
+//   daftari backfill --apply --scope <folder>    write the plan under one folder
+//
+// --scope is REQUIRED on --apply so a whole-vault write can never happen by
+// accident. The plan does not modify any markdown; the apply commits one folder
+// at a time (per-folder human ratification).
+//
+// Exit codes:
+//   0 — success
+//   1 — usage error (bad flags, missing --scope on apply, no mode)
+//   2 — runtime / config error
+import { userInfo } from "node:os";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { loadConfig } from "../utils/config.js";
+import { applyPlan } from "./apply.js";
+import { slugify } from "./derive.js";
+import { generatePlan } from "./plan.js";
+const HELP = `daftari backfill — derive frontmatter for an existing wiki from git history.
+
+Usage:
+  daftari backfill --plan [--scope <folder>] [--vault <path>]
+  daftari backfill --apply --scope <folder> [--yes] [--vault <path>]
+
+Modes:
+  --plan                 Walk the vault (or one folder), derive proposed
+                         frontmatter, and write .daftari/backfill-plan.jsonl.
+                         Modifies no markdown file. Idempotent — overwrites the
+                         plan on each run.
+  --apply                Write the plan's proposals for docs under --scope only,
+                         then auto-commit them in one commit. --scope is
+                         REQUIRED. Prompts for confirmation unless --yes.
+
+Flags:
+  --scope <folder>       First path component to act on (e.g. specs). Optional
+                         on --plan (filters the walk), required on --apply.
+  --vault <path>         Vault root (default: current directory).
+  --agent <identity>     Acting identity for the apply COMMIT and provenance —
+                         the migrator running the adoption (default:
+                         human:<your-username>). Distinct from each doc's
+                         'updated_by' FIELD, which is derived from the doc's git
+                         author through backfill.identity_map (original
+                         authorship, not the migrator).
+  --yes                  Skip the apply confirmation prompt.
+  --help, -h             Show this help.
+
+The frontmatter 'updated_by' field records who originally authored a doc (its
+git author, mapped via .daftari/config.yaml backfill.identity_map). The --agent
+identity records who ran the migration — it authors the commit, not the field.
+`;
+function readArg(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === flag)
+            return argv[i + 1];
+        const prefix = `${flag}=`;
+        const a = argv[i];
+        if (a?.startsWith(prefix))
+            return a.slice(prefix.length);
+    }
+    return undefined;
+}
+// Default acting identity: human:<os-username>, slugified. Falls back to
+// human:cli when the username is unavailable.
+function defaultAgent() {
+    try {
+        const name = userInfo().username;
+        const slug = slugify(name);
+        return `human:${slug || "cli"}`;
+    }
+    catch {
+        return "human:cli";
+    }
+}
+function renderSummary(summary, planFile) {
+    const lines = [];
+    lines.push(`Backfill plan written to ${planFile}`);
+    lines.push("");
+    lines.push(`  missing frontmatter:    ${summary.missing}`);
+    lines.push(`  partial frontmatter:    ${summary.partial}`);
+    lines.push(`  already conformant:     ${summary.conformant}`);
+    if (summary.rootSkipped > 0) {
+        lines.push(`  root-level (no folder): ${summary.rootSkipped} (skipped — backfill is per-folder)`);
+    }
+    lines.push("");
+    lines.push(`  ${summary.planned} doc(s) planned across ${Object.keys(summary.byScope).length} folder(s):`);
+    for (const scope of Object.keys(summary.byScope).sort()) {
+        lines.push(`    ${scope}: ${summary.byScope[scope]}`);
+    }
+    lines.push("");
+    if (summary.planned > 0) {
+        lines.push("Ratify a folder with:");
+        for (const scope of Object.keys(summary.byScope).sort()) {
+            lines.push(`  daftari backfill --apply --scope ${scope}`);
+        }
+        lines.push("");
+        lines.push("The plan is transient — backfill never commits it (the apply commit is the");
+        lines.push("audit trail). If this vault wasn't scaffolded by `daftari --init`, add");
+        lines.push("`.daftari/backfill-plan.jsonl` to .gitignore so it can't be committed by hand.");
+    }
+    else {
+        lines.push("Nothing to backfill.");
+    }
+    return `${lines.join("\n")}\n`;
+}
+// Throttled stderr progress for the plan walk: a heartbeat every 50 docs (and a
+// final newline) when the vault is large enough to matter. Returns the
+// onProgress callback, or undefined to stay silent on small vaults.
+function planProgress() {
+    let lastShown = 0;
+    return (done, total) => {
+        if (total < 50)
+            return;
+        if (done === total) {
+            process.stderr.write(`\rbackfill: scanned ${total}/${total} docs\n`);
+            return;
+        }
+        if (done - lastShown >= 50) {
+            lastShown = done;
+            process.stderr.write(`\rbackfill: scanned ${done}/${total} docs`);
+        }
+    };
+}
+async function confirm(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await rl.question(prompt);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runBackfill(argv) {
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(HELP);
+        return argv.length === 0 ? 1 : 0;
+    }
+    const wantPlan = argv.includes("--plan");
+    const wantApply = argv.includes("--apply");
+    if (wantPlan === wantApply) {
+        process.stderr.write("daftari backfill: pass exactly one of --plan or --apply\n");
+        return 1;
+    }
+    const vaultRoot = resolve(readArg(argv, "--vault") ?? ".");
+    const scope = readArg(argv, "--scope");
+    const agent = readArg(argv, "--agent") ?? defaultAgent();
+    // An explicitly-passed empty --scope ("" or `--scope=`) is a user error in
+    // either mode — reject it at parse time rather than letting it slip through as
+    // a no-match filter (plan) or fall to the required-scope check (apply). An
+    // omitted --scope (undefined) stays valid: optional on plan, caught below on
+    // apply.
+    if (scope !== undefined && scope.length === 0) {
+        process.stderr.write("daftari backfill: --scope cannot be empty\n");
+        return 1;
+    }
+    const config = loadConfig(vaultRoot);
+    if (!config.ok) {
+        process.stderr.write(`daftari backfill: ${config.error.message}\n`);
+        return 2;
+    }
+    const identityMap = config.value.backfillIdentityMap;
+    if (wantPlan) {
+        const result = await generatePlan(vaultRoot, {
+            scope,
+            identityMap,
+            invoker: agent,
+            onProgress: planProgress(),
+        });
+        if (!result.ok) {
+            process.stderr.write(`daftari backfill: ${result.error.message}\n`);
+            return 2;
+        }
+        process.stdout.write(renderSummary(result.value.summary, result.value.planPath));
+        return 0;
+    }
+    // --apply
+    if (scope === undefined || scope.length === 0) {
+        process.stderr.write("daftari backfill: --apply requires --scope <folder> (per-folder ratification; " +
+            "whole-vault apply is intentionally not supported)\n");
+        return 1;
+    }
+    if (!argv.includes("--yes")) {
+        // A non-interactive apply (piped stdin, CI) would block forever on the
+        // prompt. Refuse with an actionable message instead of hanging.
+        if (!process.stdin.isTTY) {
+            process.stderr.write("daftari backfill: --apply needs confirmation but stdin is not a TTY — " +
+                "re-run with --yes to apply non-interactively\n");
+            return 1;
+        }
+        const proceed = await confirm(`Apply backfilled frontmatter to docs under '${scope}' and commit as ${agent}? [y/N] `);
+        if (!proceed) {
+            process.stderr.write("daftari backfill: aborted\n");
+            return 0;
+        }
+    }
+    const result = await applyPlan(vaultRoot, scope, agent);
+    if (!result.ok) {
+        process.stderr.write(`daftari backfill: ${result.error.message}\n`);
+        return 2;
+    }
+    const r = result.value;
+    // No applied, no unchanged, no skipped means the plan had no entry under this
+    // scope — either a mistyped folder or a folder already fully backfilled (a
+    // re-plan drops conformant docs). Either way nothing was written, so this is
+    // an idempotent no-op: exit 0 (a CI loop re-applying every folder must not
+    // fail here) with a message that names the likely typo case.
+    if (r.applied.length === 0 && r.unchanged.length === 0 && r.skipped.length === 0) {
+        process.stdout.write(`No planned docs under '${scope}' — nothing to apply ` +
+            "(already backfilled, or check the folder name against the plan summary).\n");
+        return 0;
+    }
+    const out = [];
+    out.push(`Backfill applied to '${scope}':`);
+    out.push(`  written:   ${r.applied.length}`);
+    out.push(`  unchanged: ${r.unchanged.length}`);
+    if (r.skipped.length > 0) {
+        out.push(`  skipped:   ${r.skipped.length}`);
+        for (const s of r.skipped)
+            out.push(`    ${s.path}: ${s.reason}`);
+    }
+    if (r.commit)
+        out.push(`  commit:    ${r.commit}`);
+    else if (r.applied.length === 0)
+        out.push("  (no changes — already applied)");
+    process.stdout.write(`${out.join("\n")}\n`);
+    return 0;
+}
+//# sourceMappingURL=index.js.map

package/dist/backfill/index.js.map

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