unknown-knowledge 2.1.0

package/cli/kit.manifest.yaml

@@ -0,0 +1,256 @@
+# cli/kit.manifest.yaml — the payload manifest (KK-17, PRD §6/§9.2, D-007).
+#
+# The EXPLICIT allowlist of everything `npx unknown-knowledge init` seeds into
+# a client repo. Copy is manifest-driven ONLY: a file this manifest does not
+# name is never copied — nothing ships by omission (D-007). The copy engine
+# (cli/lib/copy-payload.js) enforces, by construction, that every `from` path
+# resolves INSIDE payload/ (the allowlist root, §9.2) and never at the kit's
+# acceptance fixtures/ or tests/ — an entry that tries is refused, not
+# trusted.
+#
+# Paths: `from` is relative to payload/; `to` is relative to the seeded root
+# (default unknown-knowledge/, caller-named, never dotted — §6/§9.1).
+# Directory entries vendor every file beneath them, sorted — payload/ is
+# "EXACTLY what init vendors" (§9.2), so a directory inside it is still the
+# allowlist speaking (kit CI pins payload/ ⊆ manifest expansion, so nothing
+# under payload/ can rot unshipped either).
+#
+# The seeded target gets its own generated kit.manifest.yaml (§9.1): manifest
+# echo (full seeded file list), kit version stamp, zone map. Its presence is
+# the §6 seed marker — init REFUSES any existing root, even a partial seed.
+schema-version: 1
+
+defaults:
+  root: unknown-knowledge # default seeded root dir — visible, never dotted (§6)
+
+# ------------------------------------------------------------- unconditional
+# Seeded for every stack selection, including config-only (no stacks).
+unconditional:
+  # ESM marker for the seeded engine. The engine is ESM (D-002, zero-build);
+  # without this Node re-parses every engine file to guess its module type and
+  # prints MODULE_TYPELESS_PACKAGE_JSON on stderr — the same stream the
+  # protocol tells agents to read for engine failures, so the noise is worse
+  # than cosmetic. It declares a module type and nothing else: dependency
+  # resolution still walks up to the client's own node_modules (js-yaml, §9.1).
+  module-type:
+    - { from: package.json, to: package.json }
+  schemas:
+    - { from: schemas, to: schemas }
+  engine:
+    - { from: engine, to: engine }
+  protocol:
+    # incl. AGENTS.md — the navigation contract + runtime loop (§7).
+    - { from: protocol/AGENTS.md, to: protocol/AGENTS.md }
+    - { from: protocol/new-kind-pipeline.md, to: protocol/new-kind-pipeline.md }
+    # Warrant-minting and suppression conduct for the governed vocabulary
+    # registries (UCS-1148) — the rules a steward follows before editing one.
+    - { from: protocol/registry-warrant.md, to: protocol/registry-warrant.md }
+    # The derived layer (UCS-1158) — what `engine/derive.js` generates, why
+    # deleting it loses nothing, and the two rules a reader must not break:
+    # never cite a synthesized call number, and never hand-edit a derived file.
+    # Also the declared position of embedding recall — a slot and a gate, with
+    # the implementation deliberately absent.
+    - { from: protocol/derived-layer.md, to: protocol/derived-layer.md }
+    # Protocol skills (D-019 names) — the phase-2 procedures agents run.
+    - { from: protocol/skills/knowledge-bootstrap.md, to: protocol/skills/knowledge-bootstrap.md }
+    - { from: protocol/skills/knowledge-reflect.md, to: protocol/skills/knowledge-reflect.md }
+    - { from: protocol/skills/kb-build.md, to: protocol/skills/kb-build.md }
+    - { from: protocol/skills/knowledge-audit.md, to: protocol/skills/knowledge-audit.md }
+  hooks:
+    # Git hooks that enforce the protocol mechanically (UCS-1157): blocking
+    # validation before a commit exists, and automatic reverse lookup over
+    # the staged diff. They are THIN WRAPPERS — each invokes one engine
+    # command and exits with its code, unchanged — so the tested surface is
+    # the wrapped command, and the wiring is reviewed the way the per-IDE
+    # wrappers are.
+    #
+    # They SEED but do not INSTALL. init never writes .git/ (the client's own
+    # config is the client's), so these land at <root>/hooks/ and the client
+    # symlinks or points core.hooksPath at them. That is the same boundary
+    # CI wiring keeps (D-006): the kit ships the gate, the client hangs it.
+    #
+    # The copy engine seeds BYTES, not modes, so a seeded hook arrives
+    # non-executable and git will not run it until the client chmods it. That
+    # is documented at the wiring step (README) rather than fixed here: a
+    # manifest that carried per-entry permissions would be a second thing to
+    # keep true, for one bit the client sets in the same breath as the symlink.
+    - { from: hooks/pre-commit, to: hooks/pre-commit }
+    - { from: hooks/reverse-lookup, to: hooks/reverse-lookup }
+  templates:
+    # The §5.2 new-kind authoring template — clients extend the extractor
+    # library themselves (D-001/D-009), so the template always ships.
+    - { from: templates/new-kind, to: templates/new-kind }
+    # The Decisions-entry template a steward copies when minting or suppressing
+    # a registry value (UCS-1148): every registry edit is a governed act with a
+    # written rationale, and this is the shape of that rationale.
+    - { from: templates/decisions/registry-minting.yaml, to: templates/decisions/registry-minting.yaml }
+    # The Decisions-entry template reflect copies when a corroborated cluster of
+    # residue/candidate findings warrants minting a term, alias, operation, or
+    # domain class (UCS-1160): every mint is a governed act carrying BOTH its
+    # literary warrant and the three-fragment evidence that raised it.
+    - { from: templates/decisions/reflect-mint-proposal.yaml, to: templates/decisions/reflect-mint-proposal.yaml }
+    # The Decisions-entry template a steward copies to record a phoenix event
+    # (UCS-1154): a bulk re-taxonomy is a governed act, and this is the shape of
+    # the rationale that sanctions the edition bump it carries.
+    - { from: templates/decisions/phoenix-event.yaml, to: templates/decisions/phoenix-event.yaml }
+    # The Decisions-entry templates a steward copies to move the trust boundary
+    # (UCS-1155): graduating a change category from full inspection to sampling,
+    # and revoking that graduation. Both ship, and the pair is the point —
+    # revocation must be no harder to reach for than graduation, or the boundary
+    # would only ever move one way.
+    - { from: templates/decisions/trust-graduation.yaml, to: templates/decisions/trust-graduation.yaml }
+    - { from: templates/decisions/trust-revocation.yaml, to: templates/decisions/trust-revocation.yaml }
+    # Stack-agnostic fixture authoring guide: ships even with no stack
+    # selected — a config-only client authoring its first pack starts here.
+    - { from: extractor-fixtures/README.md, to: engine/tests/fixtures/README.md }
+    # Format-adapter fixture pairs (UCS-1153). These ship UNCONDITIONALLY,
+    # where extractor fixtures ship per selected stack (D-009). The difference
+    # is real, not an oversight: an extractor kind is stack-specific (a Swift
+    # client has no use for ts-union), but a FORMAT is not — any client on any
+    # stack can be handed a PDF or a markdown spec. And the pairs are the
+    # authoring template for client-drafted adapters (D-005), so a client whose
+    # format is unsupported needs them present at the moment of the refusal,
+    # which is exactly when they have no vendor to return to (D-001).
+    - { from: adapter-fixtures, to: engine/tests/adapter-fixtures }
+  store-scaffolding:
+    # Empty seeds (§9.1): catalogs/rules the bootstrap skill fills. Decisions
+    # has no _rules.yaml by design (§9.1).
+    - { from: templates/ontology/_catalog.yaml, to: ontology/_catalog.yaml }
+    - { from: templates/ontology/_rules.yaml, to: ontology/_rules.yaml }
+    - { from: templates/knowledge/_catalog.yaml, to: knowledge/_catalog.yaml }
+    - { from: templates/knowledge/_rules.yaml, to: knowledge/_rules.yaml }
+    - { from: templates/decisions/_catalog.yaml, to: decisions/_catalog.yaml }
+    # Governed vocabulary registries (UCS-1148, extended by UCS-1149). All
+    # seeded EMPTY, like the catalogs: the bootstrap interview mints the first
+    # values from material that already exists, because a value minted ahead of
+    # its material is speculative shelving (protocol/registry-warrant.md). They
+    # ship as store scaffolding rather than as templates-to-copy because a
+    # registry is a LIVE governed file — the client edits this one, it is not a
+    # pattern.
+    #
+    # anchor/ and stage/ are empty for a SECOND reason worth stating: their
+    # vocabularies are fixed by the kit (D-003's anchors; the stages the shared
+    # pre-promotion predicate reads), so their headers name the exact values to
+    # mint. They still ship valueless because every value must cite a Decisions
+    # entry that resolves, and a seeded repo's decisions store is empty by
+    # design (D-001) — seeded values would hand every client a broken ref.
+    - { from: templates/knowledge/_registries/domains.yaml, to: knowledge/_registries/domains.yaml }
+    - { from: templates/knowledge/_registries/operations.yaml, to: knowledge/_registries/operations.yaml }
+    - { from: templates/knowledge/_registries/jurisdictions.yaml, to: knowledge/_registries/jurisdictions.yaml }
+    - { from: templates/knowledge/_registries/authority-tiers.yaml, to: knowledge/_registries/authority-tiers.yaml }
+    - { from: templates/knowledge/_registries/form.yaml, to: knowledge/_registries/form.yaml }
+    - { from: templates/knowledge/_registries/anchor.yaml, to: knowledge/_registries/anchor.yaml }
+    - { from: templates/knowledge/_registries/stage.yaml, to: knowledge/_registries/stage.yaml }
+    # The trust graduation category table (UCS-1155). Filed under decisions/
+    # because graduation governs the change PROCESS, not the knowledge — the
+    # truth anchor is the team (D-003). Seeded empty for the usual reason (every
+    # row cites a decision that must resolve) plus one of its own: whether a
+    # class of change is mechanical enough to sample is a judgment about THIS
+    # project's material, and shipping it pre-made would be the kit deciding how
+    # much someone else's work gets read.
+    - { from: templates/decisions/_registries/graduation-categories.yaml, to: decisions/_registries/graduation-categories.yaml }
+  docs:
+    # Client-facing docs (KK-24). The seeded README lands at the kit-dir
+    # root; the guides land under docs/.
+    - { from: docs/README.md, to: README.md }
+    - { from: docs/ci-wiring.md, to: docs/ci-wiring.md }
+    - { from: docs/steward-guide.md, to: docs/steward-guide.md }
+    - { from: docs/boundaries.md, to: docs/boundaries.md }
+
+# ------------------------------------------------------- stack-conditional
+# Extractor fixture packs ship ONLY for the stacks selected at init (D-009);
+# later stacks are client-authored from the shipped template, warned at init.
+# Target path per §9.1: engine/tests/fixtures/<stack>/.
+stacks:
+  ts:
+    - { from: extractor-fixtures/ts, to: engine/tests/fixtures/ts }
+  swift:
+    - { from: extractor-fixtures/swift, to: engine/tests/fixtures/swift }
+
+# ---------------------------------------------------------------- platforms
+# The agent-platform wrapper REGISTRY (KK-18, PRD §6): data, extensible —
+# adding a platform later = adding an entry here (+ a template if the
+# generic pointer doesn't fit). Wrappers are GENERATED per platform
+# selection by cli/lib/generate-wrappers.js, not copied: `template` is
+# relative to payload/ (same D-007 guards as `from` paths — refused at
+# load if it escapes), `target` is relative to the CLIENT REPO ROOT (the
+# one wrapper exception to the seeded-root scope: conventional paths are
+# the platforms' own, dotted dirs included — the §6 never-dotted rule
+# governs the seeded root only).
+#
+# `mode` is the §6 collision policy:
+#   shared    — an ecosystem-shared instruction file (root AGENTS.md,
+#               .github/copilot-instructions.md): appended between
+#               sentinel markers, never overwritten; an existing sentinel
+#               block is replaced within the sentinels (idempotent);
+#               malformed sentinels skip-and-report.
+#   dedicated — a single-tool file: created if absent; an existing file
+#               is skip-and-report, never clobbered.
+#
+# Path conventions (verified against current tool conventions, 2026-07):
+#   Claude Code → root CLAUDE.md (the simplest durable convention; .claude/
+#     holds settings/skills, not the primary instructions pointer). Treated
+#     as DEDICATED: it is the user's own tool file, not an ecosystem-shared
+#     one — an existing CLAUDE.md is theirs to edit.
+#   Cursor → .cursor/rules/unknown-knowledge.mdc (modern project-rules path;
+#     legacy .cursorrules is deprecated). Own template: .mdc frontmatter.
+#   Copilot → .github/copilot-instructions.md (SHARED per §6).
+#   Codex → root AGENTS.md (SHARED per §6 — the wrapper IS a sentinel
+#     section in the ecosystem's shared file).
+#   Gemini CLI → root GEMINI.md (its default context file). Dedicated.
+platforms:
+  claude-code:
+    name: Claude Code
+    template: wrappers/pointer.md
+    target: CLAUDE.md
+    mode: dedicated
+  codex:
+    name: Codex
+    template: wrappers/pointer.md
+    target: AGENTS.md
+    mode: shared
+  copilot:
+    name: GitHub Copilot
+    template: wrappers/pointer.md
+    target: .github/copilot-instructions.md
+    mode: shared
+  cursor:
+    name: Cursor
+    template: wrappers/cursor.mdc
+    target: .cursor/rules/unknown-knowledge.mdc
+    mode: dedicated
+  gemini:
+    name: Gemini CLI
+    template: wrappers/pointer.md
+    target: GEMINI.md
+    mode: dedicated
+
+# ---------------------------------------------------------------- create
+# Empty directories the engine creates with a .gitkeep — §6: init "ships
+# .gitkeep in empty log dirs" (a gitignored/absent findings log kills the
+# improvement loop silently). Fragment stores: one file per entry (D-010).
+create:
+  - decisions/entries
+  - logs/findings
+  - logs/misses
+  - logs/gaps
+
+# -------------------------------------------------------------- root-files
+# Kit-repo ROOT files (the one sanctioned exception to the payload/ boundary,
+# limited to this exact basename allowlist — the engine refuses anything
+# else). Required-at-publish: KK-28 adds LICENSE/NOTICE ("LICENSE/NOTICE in
+# payload manifest"); until they exist the engine treats them as required
+# only when present, so the two PRs compose. Kit CI must gate publish on
+# their presence (KK-28).
+root-files:
+  - LICENSE
+  - NOTICE
+
+# ---------------------------------------------------------------- zone map
+# Echoed into the seeded kit.manifest.yaml (§9.1) — which seeded paths are
+# kit-vendored code vs. client data. Everything is client-OWNED after seed
+# (D-001, seeded-once); the map tells an uninstall/audit what came from the
+# kit vs. what the client's own loop produced.
+zones:
+  seeded: [engine, protocol, schemas, templates, kit.manifest.yaml]
+  client: [ontology, knowledge, decisions, logs, survey-scope.yaml]

package/cli/lib/copy-payload.js

@@ -0,0 +1,334 @@
+/**
+ * Payload copy engine (KK-17, PRD §6 Phase 1 / §9.1-§9.2, D-007/D-009) — the
+ * manifest-driven library `npx unknown-knowledge init` (KK-19) drives. This
+ * is the ENGINE only: prompting UX is KK-19's; callers pass the answers
+ * (root name, stacks) as parameters.
+ *
+ * Copy is manifest-driven ONLY (cli/kit.manifest.yaml): a file the manifest
+ * does not name is never copied. Leakage of the kit's acceptance fixtures/
+ * and tests/ is impossible BY CONSTRUCTION, not by author discipline:
+ *
+ *   - every `from` must be relative, `..`-free, and resolve INSIDE payload/
+ *     (the §9.2 allowlist root); the loader refuses the manifest otherwise;
+ *   - even a hypothetically-contained path that lands under the kit's
+ *     fixtures/ or tests/ is refused by name — the engine distrusts
+ *     manifest authors (D-007: nothing ships by omission);
+ *   - the ONE exception is the `root-files` section, limited to an exact
+ *     basename allowlist (LICENSE, NOTICE — required-at-publish, KK-28);
+ *     until those files land they are required only when present, so the
+ *     parallel PRs compose.
+ *
+ * Seeding contract (§6):
+ *   - root dir defaults to `unknown-knowledge/`, caller-named, NEVER dotted
+ *     (a dot-root hides the knowledge base — refused);
+ *   - an existing target root — even a partial seed — REFUSES with guidance;
+ *     re-init/upgrade is deferred (§11.1);
+ *   - the seeded root gets a generated kit.manifest.yaml (§9.1): kit version
+ *     stamp (package version — semver semantics are KK-28's), selected
+ *     stacks, zone map, and the full sorted seeded-file list (the manifest
+ *     echo doubles as the §6 seed marker).
+ *
+ * Deterministic by construction: sorted expansion, byte-exact copies, no
+ * wall-clock reads — identical inputs seed byte-identical trees (A1).
+ */
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { load, YAMLException } from 'js-yaml';
+import { EngineRefusal } from '../../payload/engine/lib/engine-refusal.js';
+
+export const DEFAULT_ROOT = 'unknown-knowledge';
+export const MANIFEST_FILE = join('cli', 'kit.manifest.yaml');
+export const SEEDED_MANIFEST = 'kit.manifest.yaml';
+/** The one sanctioned exception to the payload/ boundary (KK-28 files). */
+export const ROOT_FILE_ALLOWLIST = Object.freeze(['LICENSE', 'NOTICE']);
+
+/** Refusals (existing seed, bad root name) — expected conditions, not bugs. */
+export class SeedRefusal extends EngineRefusal {
+  constructor(message) {
+    super(message);
+    this.name = 'SeedRefusal';
+    this.refused = true;
+  }
+}
+
+// --------------------------------------------------------------- validation
+
+/** A `from`/`to` path must be relative, non-empty, and free of `..`/`.` games. */
+function assertSanePath(value, field, entryDesc) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`manifest entry ${entryDesc}: ${field} must be a non-empty string`);
+  }
+  if (isAbsolute(value) || value.includes('\\')) {
+    throw new Error(`manifest entry ${entryDesc}: ${field} must be a relative /-separated path, got ${JSON.stringify(value)}`);
+  }
+  const segments = value.split('/');
+  if (segments.some((s) => s === '' || s === '.' || s === '..')) {
+    throw new Error(`manifest entry ${entryDesc}: ${field} may not contain empty, "." or ".." segments (got ${JSON.stringify(value)})`);
+  }
+}
+
+/** True when `path` is `parent` or lives beneath it (both pre-resolved). */
+function within(path, parent) {
+  return path === parent || path.startsWith(parent + sep);
+}
+
+/**
+ * The constructional D-007 guard: a manifest source must resolve inside
+ * payload/ and may never name the kit's acceptance fixtures/ or tests/ —
+ * the engine refuses such entries rather than trusting manifest authors.
+ */
+function assertInsidePayload(fromAbs, kitRoot, entryDesc) {
+  const payloadRoot = resolve(kitRoot, 'payload');
+  for (const forbidden of ['fixtures', 'tests']) {
+    if (within(fromAbs, resolve(kitRoot, forbidden))) {
+      throw new Error(`manifest entry ${entryDesc}: refuses to ship the kit's ${forbidden}/ (D-007 — acceptance fixtures and kit tests can never ship)`);
+    }
+  }
+  if (!within(fromAbs, payloadRoot)) {
+    throw new Error(`manifest entry ${entryDesc}: resolves outside payload/ (${fromAbs}) — the allowlist root is payload/ (D-007)`);
+  }
+}
+
+/**
+ * Root-dir name contract (§6): visible (never dotted), a single path
+ * segment, no traversal. The prompt lives in KK-19; the engine validates.
+ */
+export function validateRootName(rootName) {
+  if (typeof rootName !== 'string' || rootName.length === 0) {
+    throw new SeedRefusal('root dir name must be a non-empty string');
+  }
+  if (rootName.startsWith('.')) {
+    throw new SeedRefusal(`root dir name ${JSON.stringify(rootName)} is dotted — the knowledge base is always visible, never hidden (PRD §6)`);
+  }
+  if (/[/\\]/.test(rootName) || rootName === '..' || isAbsolute(rootName)) {
+    throw new SeedRefusal(`root dir name ${JSON.stringify(rootName)} must be a single path segment (no separators)`);
+  }
+  return rootName;
+}
+
+// ----------------------------------------------------------------- manifest
+
+/**
+ * Load + validate cli/kit.manifest.yaml. Every entry is checked against the
+ * D-007 constructional guards at LOAD time — an invalid manifest never
+ * reaches the copy phase. Returns the parsed manifest plus resolved roots.
+ */
+export function loadManifest(kitRoot, manifestPath = join(kitRoot, MANIFEST_FILE)) {
+  let doc;
+  try {
+    doc = load(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    const detail = error instanceof YAMLException ? error.message : error.message;
+    throw new Error(`cannot load payload manifest ${manifestPath}: ${detail}`);
+  }
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new Error(`payload manifest ${manifestPath}: top level must be a mapping`);
+  }
+  if (doc['schema-version'] !== 1) {
+    throw new Error(`payload manifest ${manifestPath}: unsupported schema-version ${JSON.stringify(doc['schema-version'])}`);
+  }
+
+  const payloadRoot = resolve(kitRoot, 'payload');
+  const sections = { unconditional: doc.unconditional ?? {}, stacks: doc.stacks ?? {} };
+  for (const [group, bySection] of Object.entries(sections)) {
+    if (typeof bySection !== 'object' || bySection === null || Array.isArray(bySection)) {
+      throw new Error(`payload manifest: ${group} must be a mapping of sections to entry lists`);
+    }
+    for (const [section, entries] of Object.entries(bySection)) {
+      if (!Array.isArray(entries)) throw new Error(`payload manifest: ${group}.${section} must be a list`);
+      entries.forEach((entry, i) => {
+        const desc = `${group}.${section}[${i}]`;
+        if (typeof entry !== 'object' || entry === null) throw new Error(`manifest entry ${desc}: must be a { from, to } mapping`);
+        assertSanePath(entry.from, 'from', desc);
+        assertSanePath(entry.to, 'to', desc);
+        assertInsidePayload(resolve(payloadRoot, entry.from), kitRoot, desc);
+      });
+    }
+  }
+
+  const create = doc.create ?? [];
+  if (!Array.isArray(create)) throw new Error('payload manifest: create must be a list of target dirs');
+  create.forEach((dir, i) => assertSanePath(dir, 'dir', `create[${i}]`));
+
+  // Platform wrapper registry (KK-18): data-driven and extensible, but held
+  // to the same D-007 construction as copy entries — a template that escapes
+  // payload/ (or names fixtures/tests) refuses the manifest at load time.
+  // Targets are CLIENT-REPO-ROOT-relative conventional paths; they only need
+  // path sanity (relative, ..-free), not payload containment.
+  const platforms = doc.platforms ?? {};
+  if (typeof platforms !== 'object' || platforms === null || Array.isArray(platforms)) {
+    throw new Error('payload manifest: platforms must be a mapping of platform ids to wrapper specs');
+  }
+  const wrapperTargets = new Set();
+  for (const [id, spec] of Object.entries(platforms)) {
+    const desc = `platforms.${id}`;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+      throw new Error(`payload manifest: ${desc}: platform ids are lowercase kebab-case`);
+    }
+    if (typeof spec !== 'object' || spec === null || Array.isArray(spec)) {
+      throw new Error(`payload manifest: ${desc}: must be a { name, template, target, mode } mapping`);
+    }
+    if (typeof spec.name !== 'string' || spec.name.length === 0) {
+      throw new Error(`payload manifest: ${desc}: name must be a non-empty string`);
+    }
+    assertSanePath(spec.template, 'template', desc);
+    assertInsidePayload(resolve(payloadRoot, spec.template), kitRoot, desc);
+    assertSanePath(spec.target, 'target', desc);
+    if (spec.mode !== 'shared' && spec.mode !== 'dedicated') {
+      throw new Error(`payload manifest: ${desc}: mode must be "shared" or "dedicated" (§6 collision policy), got ${JSON.stringify(spec.mode)}`);
+    }
+    if (wrapperTargets.has(spec.target)) {
+      throw new Error(`payload manifest: ${desc}: duplicate wrapper target ${JSON.stringify(spec.target)}`);
+    }
+    wrapperTargets.add(spec.target);
+  }
+
+  const rootFiles = doc['root-files'] ?? [];
+  if (!Array.isArray(rootFiles)) throw new Error('payload manifest: root-files must be a list');
+  for (const name of rootFiles) {
+    if (!ROOT_FILE_ALLOWLIST.includes(name)) {
+      throw new Error(`payload manifest: root-files entry ${JSON.stringify(name)} is not in the sanctioned allowlist [${ROOT_FILE_ALLOWLIST.join(', ')}] (D-007)`);
+    }
+  }
+
+  const zones = doc.zones ?? {};
+  const defaults = doc.defaults ?? {};
+  return { manifestPath, kitRoot, payloadRoot, sections, platforms, create, rootFiles, zones, defaults };
+}
+
+/** Every file beneath dir (relative /-joined paths), sorted; symlinks refused. */
+function walkFiles(dirAbs, relPrefix, entryDesc) {
+  const out = [];
+  for (const entry of readdirSync(dirAbs, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) {
+      throw new Error(`manifest entry ${entryDesc}: ${rel} is a symlink — payload sources must be regular files (D-007: a link could reach outside the allowlist)`);
+    }
+    if (entry.isDirectory()) out.push(...walkFiles(join(dirAbs, entry.name), rel, entryDesc));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * Expand the manifest for a stack selection into the exact copy plan:
+ * sorted [{ from (abs), to (seeded-root-relative) }]. Root-files are
+ * appended only when present at the kit root (required-at-publish, KK-28).
+ * Duplicate targets are a manifest bug and refuse.
+ */
+export function expandManifest(manifest, stacks = []) {
+  const { payloadRoot, kitRoot, sections } = manifest;
+  const known = Object.keys(sections.stacks).sort();
+  for (const stack of stacks) {
+    if (!known.includes(stack)) {
+      throw new Error(`unknown stack ${JSON.stringify(stack)} — manifest defines: ${known.join(', ') || '(none)'}`);
+    }
+  }
+
+  const entries = [
+    ...Object.values(sections.unconditional).flat(),
+    ...[...new Set(stacks)].sort().flatMap((s) => sections.stacks[s]),
+  ];
+
+  const plan = [];
+  for (const entry of entries) {
+    const fromAbs = resolve(payloadRoot, entry.from);
+    if (!existsSync(fromAbs)) throw new Error(`manifest entry ${entry.from}: missing from payload/ — the allowlist and the payload tree have drifted`);
+    const stat = lstatSync(fromAbs);
+    if (stat.isSymbolicLink()) throw new Error(`manifest entry ${entry.from}: symlink sources are refused (D-007)`);
+    if (stat.isDirectory()) {
+      for (const rel of walkFiles(fromAbs, '', entry.from)) {
+        plan.push({ from: join(fromAbs, rel), to: `${entry.to}/${rel}` });
+      }
+    } else {
+      plan.push({ from: fromAbs, to: entry.to });
+    }
+  }
+  for (const name of manifest.rootFiles) {
+    const fromAbs = join(kitRoot, name);
+    if (existsSync(fromAbs)) plan.push({ from: fromAbs, to: name }); // required-at-publish (KK-28)
+  }
+
+  plan.sort((a, b) => a.to.localeCompare(b.to));
+  for (let i = 1; i < plan.length; i += 1) {
+    if (plan[i].to === plan[i - 1].to) throw new Error(`manifest expands to duplicate target ${plan[i].to}`);
+  }
+  const seededManifestClash = plan.find((p) => p.to === SEEDED_MANIFEST);
+  if (seededManifestClash) throw new Error(`manifest entry targets ${SEEDED_MANIFEST} — that file is generated by the engine (§9.1)`);
+  return plan;
+}
+
+// ------------------------------------------------------------------ seeding
+
+/** Deterministic seeded kit.manifest.yaml (§9.1): stamp + zones + echo. */
+function renderSeededManifest({ version, stacks, zones, files }) {
+  const list = (xs) => (xs.length ? `[${xs.join(', ')}]` : '[]');
+  const lines = [
+    '# kit.manifest.yaml — seeded by `unknown-knowledge init` (PRD §9.1).',
+    '# Kit version stamp (semver semantics per kit CHANGELOG, KK-28), the',
+    '# stacks selected at init (D-009), the zone map (kit-vendored vs. client',
+    '# data — everything is client-owned after seed, D-001), and the exact',
+    '# seeded file list (the D-007 allowlist echo). Presence of this file',
+    '# marks a seeded repo: v1 init refuses to re-seed (PRD §6).',
+    'schema-version: 1',
+    `kit-version: "${version}"`,
+    `stacks: ${list(stacks)}`,
+    'zones:',
+    `  seeded: ${list(zones.seeded ?? [])}`,
+    `  client: ${list(zones.client ?? [])}`,
+    'files:',
+    ...files.map((f) => `  - ${f}`),
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Seed a target repo from the manifest. Refuses (SeedRefusal) on a dotted
+ * root name or an existing target root — even a partial seed (§6).
+ *
+ * @param {object} options
+ * @param {string} options.kitRoot   kit repo root (holds payload/ + cli/)
+ * @param {string} options.targetDir client repo root to seed into
+ * @param {string} [options.rootName] seeded dir name (default unknown-knowledge)
+ * @param {string[]} [options.stacks] selected stacks (manifest keys)
+ * @param {string} [options.manifestPath] override, for tests
+ * @returns {{ root: string, rootName: string, version: string, stacks: string[], files: string[] }}
+ */
+export function copyPayload({ kitRoot, targetDir, rootName = DEFAULT_ROOT, stacks = [], manifestPath }) {
+  validateRootName(rootName);
+  const manifest = loadManifest(kitRoot, manifestPath);
+  const selected = [...new Set(stacks)].sort();
+  const plan = expandManifest(manifest, selected);
+
+  const destRoot = resolve(targetDir, rootName);
+  if (existsSync(destRoot)) {
+    throw new SeedRefusal(
+      `${destRoot} already exists — refusing to seed over it, even a partial seed. `
+      + 'Re-init/upgrade is deferred (PRD §11.1): move or remove the directory, or pass a different root name, then re-run.');
+  }
+  if (!existsSync(resolve(targetDir))) {
+    throw new Error(`target dir ${resolve(targetDir)} does not exist`);
+  }
+
+  const version = JSON.parse(readFileSync(join(kitRoot, 'package.json'), 'utf8')).version;
+
+  mkdirSync(destRoot, { recursive: true });
+  const files = [];
+  for (const { from, to } of plan) {
+    const dest = join(destRoot, to);
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(from, dest);
+    files.push(to);
+  }
+  for (const dir of manifest.create) {
+    mkdirSync(join(destRoot, dir), { recursive: true });
+    writeFileSync(join(destRoot, dir, '.gitkeep'), '');
+    files.push(`${dir}/.gitkeep`);
+  }
+  files.push(SEEDED_MANIFEST);
+  files.sort();
+  writeFileSync(join(destRoot, SEEDED_MANIFEST),
+    renderSeededManifest({ version, stacks: selected, zones: manifest.zones, files }));
+
+  return { root: destRoot, rootName, version, stacks: selected, files };
+}