@ctxr/skill-llm-wiki 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Cross-harness support (Claude Code + OpenAI Codex CLI)
+
+- **SKILL.md prose neutralised so the wiki-runner sub-agent dispatch works under both Claude Code (via the `Agent` tool) and Codex CLI (via its equivalent).** The Tier 2 envelope shape is now the open `subagent.dispatch.v1` contract: top-level `kind: "subagent.dispatch.v1"`, `role: "wiki-tier2-<kind>"`, the per-Tier-2-request kind moved to the `tier2_kind` extension field. The deprecated `model_hint` / `effort_hint` aliases continue to be emitted for one release so existing wiki-runner consumers keep working; new code should consume `effort` (and optional `model` override) instead. See `https://github.com/ctxr-dev/kit/blob/main/docs/subagent-dispatch-v1.md` for the full envelope spec.
+- Replaced hardcoded Claude model names (`opus` / `sonnet` / `haiku`) in default-model documentation with provider-neutral effort hints (`heavy` / `balanced` / `light`). Each host harness maps `effort` to its own lineup; `model` overrides remain available for explicit pinning.
+- Repositioned package.json description from "Claude Code skill" to "Agent Skills (Claude Code, Codex CLI)".
+- Reordered package.json keywords to lead with `agent-skills`, `agents-md`, `codex`, `claude-code`.
+- Updated git-submodule install path in README from `.claude/skills/` to `.agents/skills/` to match the canonical install topology used by `@ctxr/kit`.
+- Fixed three broken cross-references in `guide/correctness/safety.md` and `guide/layout/in-place-mode.md` (relative paths that resolved outside their target subdir).
+- Declared `publishConfig.access: "public"` for scoped npm publish; added `prepublishOnly` lint+test gate.
+
 ### Performance
 
 - **Large-corpus pairwise-sweep speedup (~50-100× on I/O-bound paths).** A 596-leaf deterministic build previously took 2h15m; this release targets the three I/O antipatterns responsible for most of that wall time. Surfaced during a live Phase X.6 rebuild attempt on `skill-code-review/reviewers.src`.

package/README.md

@@ -3,9 +3,12 @@
 [![npm](https://img.shields.io/npm/v/@ctxr/skill-llm-wiki)](https://www.npmjs.com/package/@ctxr/skill-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![CI](https://img.shields.io/badge/CI-Ubuntu%20%2B%20Windows-green)](.github/workflows/ci.yml)
+[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Claude%20Code%20%7C%20Codex%20CLI-blue)](https://agentskills.io)
 
 > **Turn any folder of markdown, docs, or source into a deterministic, token-efficient knowledge base your AI agent reads the way you'd want it to — once, and only the parts it needs.**
 
+Supports Claude Code and OpenAI Codex CLI via the open Agent Skills standard. Tier 2 sub-agent dispatch follows the [`subagent-dispatch-v1`](https://github.com/ctxr-dev/kit/blob/main/docs/subagent-dispatch-v1.md) envelope.
+
 ## The problem every AI-heavy workflow eventually hits
 
 You want your AI pair — Claude, Cursor, an agent loop, whatever — to *know things*. Architecture decisions. Runbooks. API contracts. Prior postmortems. Team conventions. The messy folder of `.md` notes you've been keeping for eighteen months.
@@ -91,8 +94,8 @@ Merge my docs and runbooks wikis into a handbook
 
 This skill has two hard requirements. If either is missing, the skill will refuse to run and print a clear message explaining why and how to fix it.
 
-1. **[Claude Code](https://claude.ai/code) CLI or IDE extension.**
-2. **Node.js ≥ 18.0.0.** The skill's deterministic CLI (`scripts/cli.mjs`) is a Node.js program, so Node must be available in the shell Claude Code uses to run Bash commands. If Node.js is missing or below the minimum version, Claude will stop the operation before making any changes and relay platform-specific install instructions.
+1. **An Agent Skills-compatible harness** ([Claude Code](https://claude.ai/code) CLI/IDE, OpenAI Codex CLI, or another harness implementing the [open Agent Skills standard](https://agentskills.io)).
+2. **Node.js ≥ 18.0.0.** The skill's deterministic CLI (`scripts/cli.mjs`) is a Node.js program, so Node must be available in the shell the host harness uses to run Bash commands. If Node.js is missing or below the minimum version, the harness will stop the operation before making any changes and relay platform-specific install instructions.
 
 ### Verify your environment before invoking the skill
 
@@ -172,7 +175,7 @@ npx @ctxr/kit install @ctxr/skill-llm-wiki            # project-local
 npx @ctxr/kit install @ctxr/skill-llm-wiki --user     # user-global
 ```
 
-Installs to `.claude/skills/ctxr-skill-llm-wiki/` (or `~/.claude/skills/…` with `--user`). No post-install wiring, no automatic hooks, no filesystem watchers — the skill is pure standby until you explicitly ask Claude to run an operation against a specific directory.
+Installs canonically to `.agents/skills/ctxr-skill-llm-wiki/` (or `~/.agents/skills/…` with `--user`); `@ctxr/kit` auto-creates discovery-mirror symlinks at `.claude/skills/` (and `~/.codex/skills/` for user-scope) so Claude Code, Codex CLI, and other Agent Skills harnesses all find the artefact. No post-install wiring, no automatic hooks, no filesystem watchers; the skill is pure standby until you explicitly ask the host harness to run an operation against a specific directory.
 
 The installed package contains `SKILL.md` (the routing entry point Claude reads at activation), `LICENSE`, `README.md`, `scripts/` (invoked via `node scripts/cli.mjs <subcommand>`, never read as source), and `guide/` (context-specific routing leaves loaded on keyword activation — `hidden-git.md` when the user asks about history or diff, `user-intent.md` when the request is ambiguous, `tiered-ai.md` when the user asks about quality modes, etc.). The internal design doc `methodology.md` is deliberately excluded from the installed package (`files[]` in `package.json` does not list it) so it is never copied into any user environment and never loaded during a session.
 
@@ -180,15 +183,15 @@ The installed package contains `SKILL.md` (the routing entry point Claude reads
 
 ```bash
 git clone https://github.com/ctxr-dev/skill-llm-wiki.git /tmp/skill-llm-wiki
-mkdir -p .claude/skills
-cp -r /tmp/skill-llm-wiki .claude/skills/skill-llm-wiki
+mkdir -p .agents/skills
+cp -r /tmp/skill-llm-wiki .agents/skills/skill-llm-wiki
 ```
 
 ### Git Submodule
 
 ```bash
 git submodule add https://github.com/ctxr-dev/skill-llm-wiki.git \
-    .claude/skills/skill-llm-wiki
+    .agents/skills/skill-llm-wiki
 ```
 
 ## Usage

package/SKILL.md

@@ -62,18 +62,18 @@ When the user asks for any of the six operations (Build, Extend, Validate, Rebui
 
 1. **Resolve the ask** — pin down the operation, source, target, layout mode, and any constraints. Prompt the user to disambiguate where needed (see `guide/ux/user-intent.md`).
 2. **Run the Node.js preflight** in the main session — this is cheap, produces a tiny output, and must happen before any agent is spawned so the user sees the detailed install/upgrade message on failure. Preflight failures stop the operation; do not spawn an agent.
-3. **Spawn a dedicated "wiki-runner" sub-agent** via the `Agent` tool with a self-contained prompt describing: the operation, the resolved CLI invocation, the activated `guide/` leaves by filename, any quality-mode / layout-mode flags, and the completion criterion. The sub-agent runs the CLI, handles Tier 2 sub-delegations, manages its own context, and reports back a summary when done.
+3. **Spawn a dedicated "wiki-runner" sub-agent** via the host harness's sub-agent dispatch primitive (Claude Code: `Agent` tool; Codex CLI: equivalent; see the [`subagent-dispatch-v1`](https://github.com/ctxr-dev/kit/blob/main/docs/subagent-dispatch-v1.md) spec) with a self-contained prompt describing: the operation, the resolved CLI invocation, the activated `guide/` leaves by filename, any quality-mode / layout-mode flags, and the completion criterion. The sub-agent runs the CLI, handles Tier 2 sub-delegations, manages its own context, and reports back a summary when done.
 4. **Relay the sub-agent's summary** to the user. The main session never loads the wiki's content into its own context window.
 
 ### Why
 
-Wikis can be any size — a 10-entry notes folder or a 10,000-entry knowledge base. A Build that drafts frontmatter for a prose-heavy 10k corpus can run Claude against thousands of entries in Tier 2. Running all of that inline in the main session would consume the user's context budget on content they never asked to see, and would leave no room for continued conversation. The wiki-runner sub-agent has its own context window; the main session's budget stays lean for the user's ongoing chat.
+Wikis can be any size: a 10-entry notes folder or a 10,000-entry knowledge base. A Build that drafts frontmatter for a prose-heavy 10k corpus can run the host LLM against thousands of entries in Tier 2. Running all of that inline in the main session would consume the user's context budget on content they never asked to see, and would leave no room for continued conversation. The wiki-runner sub-agent has its own context window; the main session's budget stays lean for the user's ongoing chat.
 
 ### What the wiki-runner sub-agent is responsible for
 
 - **Executing the CLI subcommand** and streaming progress back periodically (don't spam every phase — one line per phase is plenty).
 - **Its own context-window hygiene.** The sub-agent monitors its remaining budget and auto-compacts when it approaches the limit. See `guide/isolation/scale.md` "Context-window management in the wiki-runner" for the protocol — the short version is: phase commits in the private git are the durable checkpoint, so the sub-agent can safely drop its conversation history of prior phases and re-read only what the next phase needs.
-- **Handling the Tier 2 exit-7 handshake.** The skill's CLI runs under Node and cannot spawn sub-agents directly. When the operator-convergence phase accumulates Tier 2 requests (cluster naming, mid-band merge decisions, `propose_structure` whole-directory asks, `nest_decision` gate decisions, …) the CLI writes them to `<wiki>/.work/tier2/pending-<batch-id>.json` and exits with code **7** (`NEEDS_TIER2`). Exit 7 is **not a failure** — it is the suspend-and-resume signal. The wiki-runner must:
+- **Handling the Tier 2 exit-7 handshake.** The skill's CLI runs under Node and cannot spawn sub-agents directly. When the operator-convergence phase accumulates Tier 2 requests (cluster naming, mid-band merge decisions, `propose_structure` whole-directory asks, `nest_decision` gate decisions, …) the CLI writes them to `<wiki>/.work/tier2/pending-<batch-id>.json` and exits with code **7** (`NEEDS_TIER2`). Each pending request follows the [`subagent.dispatch.v1`](https://github.com/ctxr-dev/kit/blob/main/docs/subagent-dispatch-v1.md) shape (`prompt`, `inputs`, `effort`, optional `model`, `response_schema`, `outputs_path`) so any Agent Skills harness can service it. Exit 7 is **not a failure**, it is the suspend-and-resume signal. The wiki-runner must:
     1. Detect exit 7 from the CLI.
     2. Read every `pending-*.json` file under `<wiki>/.work/tier2/`.
     3. Service each request (see "Inline servicing vs fan-out" below).
@@ -86,9 +86,9 @@ Wikis can be any size — a 10-entry notes folder or a 10,000-entry knowledge ba
 
 The wiki-runner chooses **inline** or **fan-out** servicing based on the batch size. The skill CLI's wire protocol is identical either way — pending files in, response files out, exit 7 between — so the choice is entirely a context-budget and throughput call that the wiki-runner makes at runtime:
 
-- **Inline (≤ ~50 requests per batch).** The wiki-runner answers every request directly, reasoning as the Tier 2 worker itself. No child `Agent` spawn per request. Each request's `prompt`, `inputs`, `response_schema`, `model_hint`, and `effort_hint` are visible to the wiki-runner, which writes the JSON response inline. This is the right choice for a typical `build`/`rebuild` against a ~10-50 leaf corpus: batch sizes stay small, fan-out overhead would dwarf the work, and the wiki-runner's own context is plenty for a few dozen frontmatter-blob comparisons. Environment constraint: general-purpose sub-agents in the current Claude Code harness cannot spawn further `Agent`s themselves — inline servicing is actually the *only* option when the wiki-runner is itself a nested sub-agent, so the skill's design must not require fan-out.
+- **Inline (≤ ~50 requests per batch).** The wiki-runner answers every request directly, reasoning as the Tier 2 worker itself. No child sub-agent dispatch per request. Each request's `prompt`, `inputs`, `response_schema`, `effort` (with optional `model` override) are visible to the wiki-runner, which writes the JSON response inline. This is the right choice for a typical `build`/`rebuild` against a ~10-50 leaf corpus: batch sizes stay small, fan-out overhead would dwarf the work, and the wiki-runner's own context is plenty for a few dozen frontmatter-blob comparisons. Environment constraint: general-purpose sub-agents in current Agent Skills harnesses (Claude Code, Codex CLI) cannot spawn further sub-agents themselves, so inline servicing is actually the *only* option when the wiki-runner is itself a nested sub-agent, and the skill's design must not require fan-out.
 
-- **Fan-out (> ~50 requests per batch, or mixed `model_hint`s).** The wiki-runner reports the batch size back to the main session, which spawns one narrowly-scoped `Agent` per request (or per small group of homogeneous requests) with the request's `prompt`, `inputs`, `response_schema`, `model_hint`, and `effort_hint`. The sub-agent sees ONLY those inputs — two frontmatter blobs for a `merge_decision`, a cluster's leaf metadata for a `cluster_name`, a directory's whole leaf list for a `propose_structure`, and so on. Never pass the whole wiki. Fan-out is the right choice for large corpora (thousands of leaves → thousands of draft-frontmatter and merge-decision requests) where inline would burn through the wiki-runner's context.
+- **Fan-out (> ~50 requests per batch, or mixed `effort`/`model` per request).** The wiki-runner reports the batch size back to the main session, which dispatches one narrowly-scoped sub-agent per request (or per small group of homogeneous requests) via the host harness's sub-agent primitive, passing the request's `prompt`, `inputs`, `response_schema`, `effort`, and optional `model`. The sub-agent sees ONLY those inputs (two frontmatter blobs for a `merge_decision`, a cluster's leaf metadata for a `cluster_name`, a directory's whole leaf list for a `propose_structure`, and so on). Never pass the whole wiki. Fan-out is the right choice for large corpora (thousands of leaves → thousands of draft-frontmatter and merge-decision requests) where inline would burn through the wiki-runner's context.
 
 Either way the skill CLI doesn't change — it always emits pending files and exits 7, and the wiki-runner is free to decide how the actual reasoning happens before the response files appear.
 
@@ -156,13 +156,13 @@ Response: { "slug": "<kebab-case>", "purpose": "<one line>" } or { "decision": "
 
 Unless the user specifies otherwise, the wiki-runner and its Tier 2 fan-outs pick the **most suitable model for the task size** at their default effort level. Concretely:
 
-- **Wiki-runner** — spawned at the subagent type that can orchestrate CLI subprocesses and hold the whole operation in its context. For very large corpora (>1k entries or >10 MB) prefer a 1M-context Claude variant.
-- **Tier 2 draft-frontmatter sub-agent** — picks whatever model is cost-effective for writing a ~200-word `focus` + `covers[]` pair from a single source file. Effort: minimal.
-- **Tier 2 operator-convergence sub-agent** — picks whatever model is strong at structural judgment on frontmatter pairs. Effort: minimal-to-medium depending on pair ambiguity.
-- **Tier 2 rebuild plan review sub-agent** — picks a strong reasoning model because this is the "deep understanding" case. Effort: medium.
-- **HUMAN-class Fix sub-agent** — picks a strong reasoning model; effort medium because the decision needs justification.
+- **Wiki-runner**: spawned at the sub-agent type that can orchestrate CLI subprocesses and hold the whole operation in its context. For very large corpora (>1k entries or >10 MB) prefer a 1M-context model with high effort (`effort: "heavy"`).
+- **Tier 2 draft-frontmatter sub-agent**: picks whatever model the host maps to `effort: "light"`, cost-effective for writing a ~200-word `focus` + `covers[]` pair from a single source file.
+- **Tier 2 operator-convergence sub-agent**: `effort: "light"` to `"balanced"` depending on pair ambiguity. The host's mapped model should be strong at structural judgment on frontmatter pairs.
+- **Tier 2 rebuild plan review sub-agent**: `effort: "heavy"` because this is the "deep understanding" case.
+- **HUMAN-class Fix sub-agent**: `effort: "balanced"` because the decision needs justification.
 
-**User overrides.** If the user specifies a model (`"use sonnet"`, `"run it on haiku"`, `"use opus 1M for the whole thing"`) or an effort level (`"minimal effort"`, `"maximum quality"`), honour the override on every sub-agent the operation spawns, not just the wiki-runner. Pass the override through to the Tier 2 prompts as an explicit instruction. If the user specifies conflicting overrides (e.g., a model that doesn't support the requested effort level), ask before proceeding.
+**User overrides.** If the user specifies a model (`"use sonnet"`, `"use gpt-5-codex"`, `"use opus 1M for the whole thing"`) or an effort level (`"light effort"`, `"maximum quality"`), pass it as the dispatch envelope's optional `model` field and the required `effort` field. The host harness honours the explicit `model` when set; otherwise it maps `effort` to its own model lineup. Honour the override on every sub-agent the operation spawns, not just the wiki-runner. If the user specifies conflicting overrides (e.g., a model that doesn't support the requested effort level), ask before proceeding.
 
 ### Inline execution is the escape hatch, not the norm
 

package/guide/correctness/safety.md

@@ -69,8 +69,8 @@ The `.work/` directory is scratch space used by phases that need to stage interm
   folders. History is tracked by the private git repo at
   `<source>.wiki/.llmwiki/git/`, and rollback is `skill-llm-wiki rollback
   <source>.wiki --to pre-<op-id>` (byte-exact via `git reset --hard`).
-- See [guide/layout-modes.md](layout-modes.md) for the full mode matrix and
-  [guide/in-place-mode.md](in-place-mode.md) for the in-place variant. Legacy
+- See [guide/layout/layout-modes.md](../layout/layout-modes.md) for the full mode matrix and
+  [guide/layout/in-place-mode.md](../layout/in-place-mode.md) for the in-place variant. Legacy
   `<source>.llmwiki.v<N>/` wikis are detected via **INT-04** and must be
   migrated explicitly with `skill-llm-wiki migrate <legacy-path>` before any
   other operation will run.

package/guide/layout/in-place-mode.md

@@ -93,5 +93,5 @@ If the user's source folder is already tracked by their own git repo, the
 first in-place operation writes `.gitignore` with `.llmwiki/`, `.work/`,
 `.shape/history/*/work/`. The user's git sees those paths as ignored. Our
 private repo's operations never touch the user's `.git/` — see
-[guide/coexistence.md](coexistence.md) for the full coexistence story and
+[guide/isolation/coexistence.md](../isolation/coexistence.md) for the full coexistence story and
 proof-of-isolation tests.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ctxr/skill-llm-wiki",
-  "version": "1.1.0",
-  "description": "Claude Code skill — build, extend, validate, rebuild, fix, and join LLM wikis from any knowledge corpus. Token-efficient retrieval via hierarchical indices, DAG parents, and deterministic rewrite operators.",
+  "version": "1.2.0",
+  "description": "Agent Skills (Claude Code, Codex CLI): build, extend, validate, rebuild, fix, and join LLM wikis from any knowledge corpus. Token-efficient retrieval via hierarchical indices, DAG parents, and deterministic rewrite operators.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,9 @@
     "node": ">=18.0.0"
   },
   "keywords": [
+    "agent-skills",
+    "agents-md",
+    "codex",
     "claude-code",
     "skill",
     "llm-wiki",
@@ -38,6 +41,9 @@
     "type": "skill",
     "target": "folder"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
     "skill-llm-wiki": "scripts/cli.mjs"
   },
@@ -46,7 +52,8 @@
     "validate": "node scripts/cli.mjs --version",
     "lint": "markdownlint-cli2 '**/*.md' '#node_modules'",
     "lint:fix": "markdownlint-cli2 --fix '**/*.md' '#node_modules'",
-    "prepare": "husky || true"
+    "prepare": "husky || true",
+    "prepublishOnly": "npm run lint && npm test"
   },
   "devDependencies": {
     "husky": "^9.1.0",

package/scripts/lib/contract.mjs

@@ -65,8 +65,29 @@ const FRONTMATTER_SCHEMA = {
       shared_covers: { kind: "string[]" },
       // Only present (and required) when type === "overlay".
       overlay_targets: { kind: "string[]" },
-      links: { kind: "string[]" },
+      links: {
+        kind: "object[]",
+        description: "Cross-leaf references; each entry carries an `id` (and optional metadata) — see scripts/lib/join.mjs for how runtime code reads link.id.",
+      },
+      // Consumer-defined fields (e.g. skill-code-review's
+      // `dimensions`, `audit_surface`, `languages`, `tools`) are
+      // carried through rebuilds via the deny-list forwarding in
+      // draft.mjs; their VALUES are preserved (not dropped). Exact
+      // bytes can change because the renderer applies canonical
+      // top-level key ordering and YAML formatting. The contract
+      // here describes only the fields the wiki framework itself
+      // reads / writes; consumers ship their own schemas alongside.
     },
+    // Reserved fields that the rebuild ALWAYS re-derives from the
+    // target-tree position, regardless of what the author wrote.
+    // `parents` is NOT in this set — it's hand-authored when the
+    // soft-DAG layout requires it (the drafter picks the authored
+    // value over the heuristic).
+    reserved: ["id", "type", "depth_role", "source"],
+    // Deny-list semantics for everything else: any authored field not
+    // in `reserved` flows through verbatim. This keeps the wiki
+    // framework agnostic to consumer-specific schemas.
+    pass_through_authored: true,
   },
   index: {
     required: ["id", "type", "depth_role", "focus"],

package/scripts/lib/draft.mjs

@@ -23,21 +23,52 @@
 // `needs_ai` flag on the returned draft tells the caller which entries
 // need AI review.
 
-// Fields we copy straight from the source frontmatter when the author
-// supplied them. Fields NOT in this list (id / type / depth_role /
-// parents / source) are always re-derived because their authoritative
-// source is the target-tree position, not the original source file.
-const AUTHORED_LEAF_FIELDS = [
+// Prototype-pollution deny-list. Mirrors POLLUTION_KEYS in
+// scripts/lib/frontmatter.mjs — the parser refuses these at parse
+// time, but the new pass-through path in draftLeafFrontmatter could
+// still surface them if a crafted candidate JSON (e.g. from
+// `scripts/cli.mjs draft-leaf` invoked with adversarial input)
+// shipped them via authored_frontmatter. Refusing here keeps the
+// invariant local to the assignment site.
+const POLLUTION_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+// Fields whose authoritative source is the target-tree position (not
+// the original source file). These are ALWAYS re-derived during a
+// rebuild regardless of what the author wrote: `id` comes from the
+// filename / target slot, `type` defaults to "primary" (overlays must
+// be re-asserted explicitly via the rebuild's overlay path),
+// `depth_role` is always "leaf" for non-index leaves, and `source` is
+// recomputed from the build invocation.
+//
+// `parents` is NOT in this set — it's a hand-authored field (the
+// comment in the data object below describes the convention) and the
+// drafter pickAuthored()s it. Including it here would silently drop
+// authored parents and break the soft-DAG.
+//
+// EVERY OTHER authored field flows through verbatim. This is a
+// deny-list, not an allow-list (issue #26): consumers ship their own
+// schemas (e.g. skill-code-review's `dimensions`, `audit_surface`,
+// `languages`, `tools`) and a generic wiki framework should preserve
+// what the author wrote rather than enumerating per-consumer fields.
+const RESERVED_LEAF_FIELDS = new Set([
+  "id",
+  "type",
+  "depth_role",
+  "source",
+]);
+
+// Fields the drafter computes a heuristic baseline for and writes
+// explicitly in the canonical data object below. Authored values for
+// these win over the heuristic via pickAuthored(); they're listed here
+// only so the pass-through loop knows to skip them (they're already in
+// the data object — re-forwarding would be a no-op but with the wrong
+// authored-vs-heuristic precedence).
+const EXPLICITLY_HANDLED_LEAF_FIELDS = new Set([
   "focus",
   "covers",
   "tags",
-  "domains",
-  "aliases",
-  "activation",
-  "shared_covers",
-  "overlay_targets",
-  "links",
-];
+  "parents",
+]);
 
 export function draftLeafFrontmatter(candidate, { categoryPath } = {}) {
   const authored = candidate.authored_frontmatter || {};
@@ -71,15 +102,39 @@ export function draftLeafFrontmatter(candidate, { categoryPath } = {}) {
     },
   };
 
-  // Forward the remaining AUTHORED_LEAF_FIELDS verbatim. These have no
-  // heuristic analogue — when the author supplied them, we keep them;
-  // otherwise we omit the field entirely so the output stays compact.
+  // Forward EVERY authored field that isn't reserved (re-derived from
+  // target-tree position) or explicitly handled above (focus / covers
+  // / tags / parents, where authored-wins-over-drafted is enforced via
+  // pickAuthored). Issue #26: the previous allow-list dropped any
+  // consumer-specific v2 field (dimensions, audit_surface, languages,
+  // tools, …) authored at the source; the deny-list now preserves
+  // arbitrary author-shipped frontmatter VALUES (the downstream
+  // renderer applies canonical top-level key ordering and YAML
+  // formatting, so the rebuilt bytes need not match the source bytes).
   if (hasAuthored) {
-    for (const field of AUTHORED_LEAF_FIELDS) {
-      if (field === "focus" || field === "covers" || field === "tags") continue;
-      if (authored[field] !== undefined && authored[field] !== null) {
-        data[field] = authored[field];
-      }
+    for (const [field, value] of Object.entries(authored)) {
+      if (RESERVED_LEAF_FIELDS.has(field)) continue;
+      if (EXPLICITLY_HANDLED_LEAF_FIELDS.has(field)) continue;
+      // Refuse prototype-pollution keys before any assignment touches
+      // the prototype chain. Mirrors frontmatter.mjs's safeAssign.
+      if (POLLUTION_KEYS.has(field)) continue;
+      if (value === undefined || value === null) continue;
+      const sanitised = sanitiseAuthoredValue(value);
+      if (sanitised === undefined) continue;
+      // Empty arrays / empty strings DO get forwarded — distinguishing
+      // "author wrote []" from "author omitted" matters for some
+      // consumer schemas (e.g. an explicit empty file_globs[] means
+      // "this leaf opts out of glob-based activation"). Only the
+      // null/undefined case is treated as "author omitted".
+      // Use defineProperty (configurable, enumerable, writable) so the
+      // assignment never invokes a setter on Object.prototype if the
+      // POLLUTION_KEYS guard above is ever bypassed.
+      Object.defineProperty(data, field, {
+        value: sanitised,
+        configurable: true,
+        enumerable: true,
+        writable: true,
+      });
     }
   }
 
@@ -87,6 +142,58 @@ export function draftLeafFrontmatter(candidate, { categoryPath } = {}) {
   return { data, confidence, needs_ai: confidence < 0.6 };
 }
 
+// Sanitise a value pulled from authored frontmatter for assignment
+// into `data` (which is later passed to renderFrontmatter). The
+// renderer at scripts/lib/frontmatter.mjs handles plain objects,
+// arrays, and scalar primitives (string / number / boolean / null) but
+// not richer JS types — gray-matter / js-yaml can return:
+//   - Date (from YAML timestamps like `created_at: 2026-04-30`):
+//     converted to ISO string. Otherwise renderScalar(date) calls
+//     String(date) which produces the verbose JS Date toString form.
+//   - functions / symbols / class instances: rejected (return
+//     undefined so the pass-through loop skips the field).
+// Plain objects and arrays recurse so a Date nested inside an
+// authored object still gets normalised.
+function sanitiseAuthoredValue(value) {
+  if (value === null) return null;
+  if (value === undefined) return undefined;
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") return value;
+  if (t === "function" || t === "symbol" || t === "bigint") return undefined;
+  if (value instanceof Date) {
+    // YAML timestamps come back as Date; canonicalise to ISO string so
+    // a downstream rebuild round-trips the same string back into the
+    // YAML stream.
+    return value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitiseAuthoredValue).filter((v) => v !== undefined);
+  }
+  if (t === "object") {
+    // Plain-object check: only recurse into objects whose prototype
+    // is Object.prototype or null. Class instances (URL, Buffer, …)
+    // are rejected — their `Object.entries` shape is rarely what a
+    // YAML frontmatter consumer wants.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) return undefined;
+    // Use a null-prototype object as the accumulator so neither the
+    // POLLUTION_KEYS guard nor a setter on Object.prototype can be
+    // triggered by an `out[__proto__] = ...` assignment with a crafted
+    // key. (defineProperty would also work; null-proto is one allocation.)
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(value)) {
+      if (POLLUTION_KEYS.has(k)) continue;
+      const s = sanitiseAuthoredValue(v);
+      if (s === undefined) continue;
+      out[k] = s;
+    }
+    // Re-parent to Object.prototype before returning so downstream
+    // consumers that do `value.hasOwnProperty(...)` etc. keep working.
+    return Object.assign({}, out);
+  }
+  return undefined;
+}
+
 function pickAuthored(authoredVal, fallback) {
   if (authoredVal === undefined || authoredVal === null) return fallback;
   if (Array.isArray(authoredVal)) {

package/scripts/lib/frontmatter.mjs

@@ -126,8 +126,9 @@ function parseMap(p, baseIndent) {
     const rest = text.slice(colon + 1).trim();
     p.advance();
 
-    if (rest === "|" || rest === ">") {
-      safeAssign(out, key, parseBlockScalar(p, baseIndent, rest === "|"), p, tok);
+    const blockHeader = blockScalarHeader(rest);
+    if (blockHeader) {
+      safeAssign(out, key, parseBlockScalar(p, baseIndent, blockHeader), p, tok);
       continue;
     }
     if (rest !== "") {
@@ -178,6 +179,12 @@ function parseSeq(p, baseIndent) {
       continue;
     }
 
+    const itemBlockHeader = blockScalarHeader(afterDash);
+    if (itemBlockHeader) {
+      out.push(parseBlockScalar(p, baseIndent, itemBlockHeader));
+      continue;
+    }
+
     const colon = findKeyColon(afterDash);
     if (colon === -1) {
       out.push(parseScalarInline(afterDash));
@@ -189,8 +196,9 @@ function parseSeq(p, baseIndent) {
     const firstRest = afterDash.slice(colon + 1).trim();
     const item = {};
 
-    if (firstRest === "|" || firstRest === ">") {
-      item[firstKey] = parseBlockScalar(p, baseIndent + 2, firstRest === "|");
+    const firstBlockHeader = blockScalarHeader(firstRest);
+    if (firstBlockHeader) {
+      item[firstKey] = parseBlockScalar(p, baseIndent + 2, firstBlockHeader);
     } else if (firstRest !== "") {
       item[firstKey] = parseScalarInline(firstRest);
     } else {
@@ -237,10 +245,13 @@ function parseSeq(p, baseIndent) {
         } else {
           item[subKey] = null;
         }
-      } else if (subRest === "|" || subRest === ">") {
-        item[subKey] = parseBlockScalar(p, baseIndent + 2, subRest === "|");
       } else {
-        item[subKey] = parseScalarInline(subRest);
+        const subBlockHeader = blockScalarHeader(subRest);
+        if (subBlockHeader) {
+          item[subKey] = parseBlockScalar(p, baseIndent + 2, subBlockHeader);
+        } else {
+          item[subKey] = parseScalarInline(subRest);
+        }
       }
     }
 
@@ -248,8 +259,29 @@ function parseSeq(p, baseIndent) {
   }
 }
 
-function parseBlockScalar(p, baseIndent, literal) {
+// Recognise a YAML block scalar header: `|` (literal) or `>` (folded),
+// each optionally carrying a chomping indicator (`+`/`-`) and/or an explicit
+// indentation indicator (a single digit 1-9), in either order (YAML 1.2
+// §8.1.1). Returns { literal } or null. Chomping/indent indicators affect
+// only trailing-newline and indent-detection nuances that do not change the
+// value of the single-line/wrapped scalars our frontmatter uses, so we read
+// them for tolerance but act only on the literal-vs-folded distinction. This
+// is why a serializer-folded `id: >-` (js-yaml's default line wrap) parses
+// instead of tripping "unexpected indent".
+function blockScalarHeader(rest) {
+  const m = /^([|>])(?:(?:([+-])([1-9])?)|(?:([1-9])([+-])?))?$/.exec(rest);
+  return m
+    ? {
+        literal: m[1] === "|",
+        indent: Number(m[3] ?? m[4] ?? 0),
+      }
+    : null;
+}
+
+function parseBlockScalar(p, baseIndent, header) {
+  const { literal, indent } = header;
   const collected = [];
+  let contentIndent = indent > 0 ? baseIndent + indent : null;
   while (p.pos < p.lines.length) {
     const raw = p.lines[p.pos];
     if (raw.trim() === "") {
@@ -259,7 +291,11 @@ function parseBlockScalar(p, baseIndent, literal) {
     }
     const indent = raw.length - raw.trimStart().length;
     if (indent <= baseIndent) break;
-    collected.push(raw.slice(baseIndent + 2));
+    if (contentIndent == null) {
+      contentIndent = indent;
+    }
+    if (indent < contentIndent) break;
+    collected.push(raw.slice(contentIndent));
     p.pos++;
   }
   // Trim trailing empty lines

package/scripts/lib/tier2-protocol.mjs

@@ -20,18 +20,34 @@
 //   - Batch read / write / merge helpers
 //   - Pollution-key defence for JSON parse
 //
-// Request shape (JSON):
+// Request shape (JSON, conforms to the open subagent.dispatch.v1 envelope
+// with skill-specific extensions). What makeRequest() emits today:
 //   {
+//     kind:            "subagent.dispatch.v1"   (the wire-format literal)
 //     request_id:      string, unique per batch
-//     kind:            "merge_decision" | "nest_decision" | "cluster_name"
-//                    | "propose_structure"
-//                    | "draft_frontmatter" | "rebuild_plan_review"
-//                    | "human_fix_item"
+//     role:            "wiki-tier2-<tier2_kind>" (host maps to its native
+//                       sub-agent type)
 //     prompt:          natural-language question the sub-agent answers
 //     inputs:          minimal per-kind inputs (frontmatter blobs, etc.)
+//     effort:          "heavy" | "balanced" | "light" (provider-neutral hint)
 //     response_schema: JSON shape the sub-agent must return
-//     model_hint:      string, picked from guide/tiered-ai.md matrix
-//     effort_hint:     string, picked from guide/tiered-ai.md matrix
+//     tier2_kind:      "merge_decision" | "nest_decision" | "cluster_name"
+//                    | "propose_structure" | "draft_frontmatter"
+//                    | "rebuild_plan_review" | "human_fix_item"
+//                       (skill extension: the per-Tier-2-request kind, which
+//                        the wiki-runner routes on)
+//     model:           optional explicit model override; host prefers this
+//                       when set, else maps `effort` to its own lineup
+//
+//   Deprecated aliases kept for one release (emitted with the exact pre-v1
+//   per-kind values so existing wiki-runner consumers stay byte-compatible):
+//     model_hint  → preserved per-kind legacy model hint
+//     effort_hint → preserved per-kind legacy effort hint
+//
+//   Legacy envelopes written by a PREVIOUS release (where top-level `kind`
+//   WAS the Tier 2 kind and there was no `tier2_kind`/`role`) are still
+//   accepted on read: validateRequest and tier2KindOf both tolerate that
+//   shape so in-flight pending files resume across the upgrade.
 //   }
 //
 // Response shape (JSON):
@@ -57,30 +73,39 @@ import { dirname, join } from "node:path";
 
 export const TIER2_EXIT_CODE = 7;
 
-// The default model + effort matrix from guide/tiered-ai.md. Each
-// request kind maps to a model hint and an effort hint the wiki-
-// runner uses when spawning the sub-agent. These are hints, not
-// mandates — the wiki-runner may override per-session.
+// The default effort matrix from guide/tiered-ai.md. Each request
+// kind maps to an effort hint that the host harness translates to a
+// model from its own lineup. These are hints, not mandates — the
+// wiki-runner may override per-session by setting an explicit
+// `model` on the request.
+//
+// Effort enum (provider-neutral):
+//   "heavy"    — prior `opus` + high; deepest reasoning task
+//   "balanced" — prior `sonnet`/`opus` + medium; structural judgement
+//   "light"    — prior `sonnet`/`haiku` + low; quick decisions
 export const TIER2_DEFAULTS = Object.freeze({
   merge_decision: {
-    model_hint: "sonnet",
-    effort_hint: "low",
+    effort: "light",
+    legacy_model_hint: "sonnet",
+    legacy_effort_hint: "low",
     response_schema: {
       decision: "same|different|undecidable",
       reason: "string",
     },
   },
   nest_decision: {
-    model_hint: "sonnet",
-    effort_hint: "medium",
+    effort: "balanced",
+    legacy_model_hint: "sonnet",
+    legacy_effort_hint: "medium",
     response_schema: {
       decision: "nest|keep_flat|undecidable",
       reason: "string",
     },
   },
   cluster_name: {
-    model_hint: "sonnet",
-    effort_hint: "low",
+    effort: "light",
+    legacy_model_hint: "sonnet",
+    legacy_effort_hint: "low",
     response_schema: {
       slug: "kebab-case-slug",
       purpose: "string",
@@ -92,12 +117,13 @@ export const TIER2_DEFAULTS = Object.freeze({
   // ids) plus the leaves that should remain as siblings. This is
   // the "Tier 2 gets first dibs" escalation and fires BEFORE the
   // math-based cluster detector on every non-already-nested
-  // directory. Opus + medium effort because the task is a
-  // structural judgment call over many inputs that benefits from
-  // the strongest reasoning model.
+  // directory. balanced effort because the task is a structural
+  // judgement call over many inputs that benefits from a strong
+  // reasoning model.
   propose_structure: {
-    model_hint: "opus",
-    effort_hint: "medium",
+    effort: "balanced",
+    legacy_model_hint: "opus",
+    legacy_effort_hint: "medium",
     response_schema: {
       subcategories: "array of { slug, purpose, members[] }",
       siblings: "array of leaf ids",
@@ -105,8 +131,9 @@ export const TIER2_DEFAULTS = Object.freeze({
     },
   },
   draft_frontmatter: {
-    model_hint: "sonnet",
-    effort_hint: "medium",
+    effort: "balanced",
+    legacy_model_hint: "sonnet",
+    legacy_effort_hint: "medium",
     response_schema: {
       focus: "string",
       covers: "array of strings",
@@ -114,8 +141,9 @@ export const TIER2_DEFAULTS = Object.freeze({
     },
   },
   rebuild_plan_review: {
-    model_hint: "opus",
-    effort_hint: "high",
+    effort: "heavy",
+    legacy_model_hint: "opus",
+    legacy_effort_hint: "high",
     response_schema: {
       approve: "boolean",
       drop: "array of iteration ids",
@@ -123,8 +151,9 @@ export const TIER2_DEFAULTS = Object.freeze({
     },
   },
   human_fix_item: {
-    model_hint: "sonnet",
-    effort_hint: "low",
+    effort: "light",
+    legacy_model_hint: "sonnet",
+    legacy_effort_hint: "low",
     response_schema: {
       action: "string",
       rationale: "string",
@@ -132,6 +161,20 @@ export const TIER2_DEFAULTS = Object.freeze({
   },
 });
 
+// The three valid provider-neutral effort values. Any other value
+// is rejected by makeRequest rather than silently falling back to a
+// legacy alias.
+const VALID_EFFORTS = new Set(["heavy", "balanced", "light"]);
+
+let deprecationWarned = false;
+function warnDeprecatedAliasOnce() {
+  if (deprecationWarned) return;
+  deprecationWarned = true;
+  process.stderr.write(
+    "[skill-llm-wiki] tier2-protocol: `model_hint` and `effort_hint` are deprecated; pass `effort` and (optional) `model` instead.\n",
+  );
+}
+
 export const TIER2_KINDS = Object.freeze(Object.keys(TIER2_DEFAULTS));
 
 // Pollution keys that would leak onto Object.prototype if we
@@ -187,8 +230,26 @@ export function listBatches(wikiRoot) {
 // The builder fills in defaults from TIER2_DEFAULTS and validates
 // the shape. `inputs` is kind-specific and kept small (a few
 // frontmatter blobs at most) so batches stay under a few KB each.
+//
+// Wire shape: emitted envelopes conform to the open `subagent.dispatch.v1`
+// envelope (see https://github.com/ctxr-dev/kit/blob/main/docs/subagent-dispatch-v1.md) so any Agent
+// Skills harness can validate them. The Tier 2 per-request kind
+// (`merge_decision`, `propose_structure`, …) lives on `tier2_kind`, NOT on
+// the envelope's top-level `kind` field — `kind` MUST be the literal
+// `"subagent.dispatch.v1"`. The skill-side `role` is derived from the Tier 2
+// kind so the harness can map to its native sub-agent type.
+//
+// Legacy aliases `model_hint` / `effort_hint` are emitted alongside the
+// canonical `effort` field for one release so wiki-runners that read the
+// old names keep working. The schema's `additionalProperties: true` allows
+// these as a documented extension profile.
+
+const ROLE_PREFIX = "wiki-tier2-";
 
-export function makeRequest(kind, { prompt, inputs, model_hint, effort_hint, request_id } = {}) {
+export function makeRequest(
+  kind,
+  { prompt, inputs, effort, model, model_hint, effort_hint, request_id } = {},
+) {
   if (!TIER2_KINDS.includes(kind)) {
     throw new Error(`tier2-protocol: unknown kind "${kind}" (valid: ${TIER2_KINDS.join(", ")})`);
   }
@@ -203,15 +264,44 @@ export function makeRequest(kind, { prompt, inputs, model_hint, effort_hint, req
   }
   const defaults = TIER2_DEFAULTS[kind];
   const rid = request_id ?? deriveRequestId(kind, inputs);
-  return {
+
+  // Accept deprecated aliases (with a one-shot stderr warning) but
+  // prefer the new names when both are set.
+  if ((model_hint !== undefined || effort_hint !== undefined) && effort === undefined && model === undefined) {
+    warnDeprecatedAliasOnce();
+  }
+  const resolvedEffort = effort ?? defaults.effort;
+  if (!VALID_EFFORTS.has(resolvedEffort)) {
+    throw new Error(
+      `tier2-protocol: invalid effort "${resolvedEffort}" (allowed: ${[...VALID_EFFORTS].join(", ")})`,
+    );
+  }
+  // Required v1 fields first (`kind`, `request_id`, `role`, `prompt`,
+  // `inputs`, `effort`); skill-specific extensions follow.
+  const out = {
+    kind: "subagent.dispatch.v1",
     request_id: rid,
-    kind,
+    role: ROLE_PREFIX + kind,
     prompt,
     inputs,
+    effort: resolvedEffort,
     response_schema: defaults.response_schema,
-    model_hint: model_hint ?? defaults.model_hint,
-    effort_hint: effort_hint ?? defaults.effort_hint,
+    // Skill-specific extension: the per-Tier-2-request kind, used by the
+    // wiki-runner to route to the right inline handler / prompt template.
+    tier2_kind: kind,
+    // Deprecated aliases retained for one release; readers should migrate to
+    // `effort` (and optional `model`). These emit the EXACT pre-v1 per-kind
+    // `model_hint`/`effort_hint` values (stored on TIER2_DEFAULTS) so the
+    // deprecation window is byte-compatible — they are NOT derived from
+    // `effort` (which would change e.g. propose_structure's model_hint).
+    // A caller-supplied alias still wins.
+    model_hint: model_hint ?? defaults.legacy_model_hint,
+    effort_hint: effort_hint ?? defaults.legacy_effort_hint,
   };
+  if (typeof model === "string" && model.length > 0) {
+    out.model = model;
+  }
+  return out;
 }
 
 // Deterministic request id: sha256(kind + canonical-JSON(inputs))
@@ -248,6 +338,28 @@ function canonicalJson(value) {
 
 // ── Request validation ─────────────────────────────────────────────
 
+/**
+ * Pull the per-request Tier 2 kind off an envelope.
+ *
+ * New v1-conformant envelopes carry it on `tier2_kind` (the wire `kind` is
+ * the literal `"subagent.dispatch.v1"`). Legacy envelopes (pre-v1
+ * conformance) put it on `kind`. This helper accepts either so on-disk
+ * envelopes from a previous release continue to resolve correctly.
+ */
+export function tier2KindOf(req) {
+  if (!req || typeof req !== "object") return null;
+  // Only accept a `tier2_kind` that names a recognised kind; an unknown or
+  // malformed value must NOT be treated as valid downstream.
+  if (typeof req.tier2_kind === "string" && TIER2_KINDS.includes(req.tier2_kind)) {
+    return req.tier2_kind;
+  }
+  // Legacy fallback: `kind` was the per-request tier-2 kind before v1 conformance.
+  if (typeof req.kind === "string" && TIER2_KINDS.includes(req.kind)) {
+    return req.kind;
+  }
+  return null;
+}
+
 export function validateRequest(req) {
   if (!req || typeof req !== "object") {
     throw new Error("tier2-protocol: request must be an object");
@@ -258,8 +370,24 @@ export function validateRequest(req) {
   if (typeof req.request_id !== "string" || req.request_id.length === 0) {
     throw new Error("tier2-protocol: request.request_id must be a non-empty string");
   }
-  if (!TIER2_KINDS.includes(req.kind)) {
-    throw new Error(`tier2-protocol: request.kind "${req.kind}" is not recognised`);
+  // Envelope `kind` is REQUIRED. It must be the v1 wire constant
+  // "subagent.dispatch.v1" OR — for legacy pre-v1 envelopes — itself one of
+  // the Tier 2 kinds. Omitting it (even when a valid `tier2_kind` is present)
+  // is a malformed envelope: an envelope with no `kind` is neither v1 nor a
+  // recognised legacy shape, and must not be writable to a pending file.
+  if (typeof req.kind !== "string" || req.kind.length === 0) {
+    throw new Error(
+      `tier2-protocol: request.kind is required and must be "subagent.dispatch.v1" or a legacy tier-2 kind (${TIER2_KINDS.join(", ")})`,
+    );
+  }
+  if (req.kind !== "subagent.dispatch.v1" && !TIER2_KINDS.includes(req.kind)) {
+    throw new Error(
+      `tier2-protocol: request.kind must be "subagent.dispatch.v1" or a legacy tier-2 kind (${TIER2_KINDS.join(", ")}), got "${req.kind}"`,
+    );
+  }
+  const t2 = tier2KindOf(req);
+  if (!t2) {
+    throw new Error(`tier2-protocol: request must declare tier2_kind (or legacy kind) from: ${TIER2_KINDS.join(", ")}`);
   }
   if (typeof req.prompt !== "string" || req.prompt.length === 0) {
     throw new Error("tier2-protocol: request.prompt must be a non-empty string");
@@ -441,8 +569,12 @@ export function resolveFromFixture(fixtureMap, request) {
   if (!request || typeof request.request_id !== "string") return null;
   const specific = fixtureMap.get(request.request_id);
   if (specific !== undefined) return specific;
-  if (typeof request.kind === "string") {
-    const wildcard = fixtureMap.get(`__kind__${request.kind}`);
+  // Wildcard lookups key on the per-Tier-2-request kind, not the v1
+  // envelope `kind` literal. Resolve via `tier2KindOf` so both new and
+  // legacy envelope shapes route correctly.
+  const t2 = tier2KindOf(request);
+  if (t2) {
+    const wildcard = fixtureMap.get(`__kind__${t2}`);
     if (wildcard !== undefined) return wildcard;
   }
   return null;