@jaybeeuu/agent-cortex 2.1.0 → 2.3.0

package/skills/productivity/migration/REFERENCE.md

@@ -0,0 +1,227 @@
+# Migration reference
+
+Contracts, step details, and recovery recipes for the `migration` skill. `SKILL.md` holds the
+workflow and the gate; this file holds the detail you reach for while running it.
+
+## Command interface the skill relies on
+
+The command is shipped by the `agent-cortex` CLI (`bin/agent-cortex.mjs` + `lib/cli.mjs`), which
+exposes exactly one executable name — `agent-cortex`. From a checkout that is not installed, run
+it as `node bin/agent-cortex.mjs migrate`. There is no shorter alias. This skill depends on the
+following behaviour — nothing wider:
+
+| Contract | Guarantee the skill assumes |
+|---|---|
+| `agent-cortex migrate` | **Dry run is the default**: plans the first pending step only, zero writes, exit 0. With `--apply` it runs every step the repo still needs. |
+| `--apply` | Performs the writes. Same plan, executed. |
+| `--dry-run` | Explicit form of the default; identical output, still zero writes. |
+| `--help` | Lists the commands and flags this build accepts, including whether `migrate` itself is present. |
+| `--dir <path>` | Points step v2 at a workspace that keeps its idea files somewhere other than `docs/ideas`. Omitted, the default applies; a missing value is a usage error, not a silent fallback. |
+| Idea source | Step v2 reads `*.md` under the idea directory (`docs/ideas/` unless `--dir` says otherwise), one level of nesting included, and never writes or deletes one. |
+| Registry detection | Reports the repo's current version and the first step with pending work — the only step a dry run plans — derived from workspace state, not from a flag or a stored marker the agent has to keep. |
+| Step ordering | Applies steps in version order, oldest first. The final summary is one line per step: its name and description, that step's pending bead total, and a `verified` line. It carries no per-group breakdown — derive group sizes from the step-v1 export counts. |
+| Idempotence | A converged repo plans zero targets and exits 0; a re-run after a partial failure resumes rather than repeating writes. |
+| Failure mode | Fails loudly (non-zero exit) when `bd` is missing or a `bd` subcommand errors; never silently skips a group. A v1 label value outside `afk\|hitl` is a blocking error that names each offending bead and label and stops before any write — both the dry run and `--apply` refuse. |
+
+Read `agent-cortex migrate --help` in the target workspace before relying on any flag beyond the
+above. The registry grows over time; treat the flags in this table as the floor, and the installed
+build's help output as the truth. If `migrate` is not listed at all, the installed package predates
+the command — upgrade rather than reconstructing the steps by hand.
+
+Scope note: the command touches beads only. Skills, hooks, docs, and agent prompts that mention
+the old labels are follow-up edits in the repo, not command output. Step v2 reads idea files and
+never writes or deletes one — retiring the files is the repo's cutover, not the migration.
+
+## Detection source and its cost
+
+Detection and verification read `bd export --all`, cross-checked against `bd label list-all
+--json`. A label-filtered `bd list` is not in the path: on bd 1.3.1 that query can omit closed
+beads, which is how a half-migrated workspace once verified clean. The cross-check keeps the
+export from becoming the new silent weak link — an export that cannot attribute a legacy label
+the index still lists fails the run rather than shrinking the count.
+
+The cost is operational. One `--apply` reads the whole export about three times — initial
+detection, verification after the step, then re-detection for the next step — so a large workspace
+pays for a full export per call rather than a label-filtered page. Each call is capped at 32 MB of
+stdout (roughly 12k issues at typical record sizes); past the cap the run fails loudly instead of
+truncating. Near the ceiling, expect that explicit failure and do not read a short result as a
+clean workspace.
+
+Step v2 adds two reads of its own, both cheap: the idea files on disk, and one `bd list -l
+kind:idea --all --json --limit 0` for the records that already exist. It never runs the full
+export.
+
+## Snapshot scope (SKILL step 2)
+
+`bd export --all` is the pre-migration snapshot. It includes infrastructure beads (agents, roles,
+messages), templates, gates, and `bd remember` memories as well as regular issues — so treat the
+file as sensitive and keep it out of the repo (a path outside the workspace, or one you have
+gitignored; `bd export --all -o <path>.jsonl` writes it directly). It is an issue export, not a
+full database backup: Dolt branches, commit history, and working-set state are not captured. For
+undoing a migration that is enough — steps change labels and dependencies, both of which the
+export records.
+
+## Step v1 — label rename
+
+Purpose: `implementation-type:afk|hitl` → `execution:afk|hitl`, strictly renamed and
+agent-agnostic. Only those two values are mapped: any other value (`wip`, a typo, a value from a
+future axis) is a blocking error naming the bead and the label, raised before any write, so the
+run can never invent a label such as `execution:wip` that nothing queries.
+
+Mechanics the plan reflects:
+
+1. Enumerate every bead carrying an `implementation-type:*` label by reading the whole workspace —
+   `bd export --all` (JSONL) — closed beads included, because a clean label space is the goal and
+   bd tolerates label history on closed issues. There is no label filter and no page limit in this
+   path, so the count is the workspace's rather than a query's.
+2. Group bead ids by label value. A bead carrying both `afk` and `hitl` appears in both groups;
+   that is a data problem worth inspecting, not a conflict the tool resolves for you.
+3. Per group, on `--apply`: `bd label add <ids…> execution:<value>` then
+   `bd label remove <ids…> implementation-type:<value>`. Add-then-remove keeps the routing label
+   present at every instant, so nothing is unroutable mid-flight.
+4. Re-running after convergence finds zero targets — the no-op that proves idempotence.
+
+Verification commands:
+
+```bash
+bd label list-all                               # no implementation-type:* entries
+bd export --all | grep '"implementation-type:'  # empty, closed beads included
+bd label list <bead-id>                         # spot-check: execution:<value> present
+bd ready -l execution:afk                       # the routing query still works
+```
+
+## Step v2 — ideas to beads
+
+Purpose: loose idea files (`docs/ideas/*.md`) become `kind:idea` + `execution:hitl` beads, one
+bead per file. The files are read and left in place; deleting them is the repo's own cutover step.
+The step is repo-agnostic — it assumes an idea directory (`docs/ideas/` by default, `--dir`
+overridable) and nothing else: no skill, no install path, no agent-cortex-specific label.
+
+Mechanics the plan reflects:
+
+- **Discovery.** Top-level `*.md` under the idea directory, plus one level of nesting (a multi-part
+  idea can live in its own folder). A missing directory is not an error — a workspace that never
+  used idea files has nothing pending. The plan prints one line per file: path, title, priority.
+- **Field mapping.** The files predate a single template, so a `##` heading is matched by normalised
+  name (case-folded, trailing parenthetical ignored) rather than exact text. Every field keeps its
+  `##` marker, because the marker is the contract `flesh-out-idea` reads a bead by.
+
+  | Bead field | Sections |
+  |---|---|
+  | title | the `#` heading, `Idea: ` prefixed (a leading `Idea:`/`Design:` is not doubled) |
+  | `--description` | `## Problem`, legacy `## Why it might be useful`, `## Who benefits`, `## Proposed outcome` |
+  | `--design` | `## How we might do it`, `## Fleshed-out design (…)`, `## Design so far / provenance` |
+  | `--notes` | `## Status`, `## Created`, `## Validity check`, `## Constraints`, `## Next validation step`, `## Priority`, `## When to think about it`, `## Open questions`, `## Notes`, and every unlisted `##` section in file order |
+  | `--context` | unused — no idea file in the wild carries a referential section; do not invent one |
+  | `--acceptance` | fixed promotion criterion: a scoped epic/feature is spawned from the bead, or it is explicitly rejected (a `task` bead needs acceptance criteria to lint clean) |
+  | `-p` | first `P0`–`P4` token anywhere in the file, `P4` when the file states none |
+
+  The invariant that makes the mapping checkable: **no content loss** — the heading becomes the
+  title and every other line of the file appears in exactly one of the three fields.
+
+- **Priority caveat.** The first `P<n>` token wins, so a file that only mentions a `P0-P4` *scale*
+  reads as `P0`. Read the priority column of the plan before applying.
+
+- **Labels.** `kind:idea` marks the record as an unscoped idea; `execution:hitl` is always applied
+  because an idea is human-owned until promoted, and it stays out of the agent queue by *not*
+  carrying `execution:afk`.
+
+- **Idempotence.** Before creating anything the step reads `bd list -l kind:idea --all --json
+  --limit 0` and skips a file when an idea bead already records it: either a bead names the file
+  under a `## Provenance` heading, or a bead carrying no provenance has a matching title (after
+  dropping the `Idea: ` / `Design: ` prefix and all punctuation). Every bead the step creates
+  cites its source file under `## Provenance`, so the provenance rule is what makes a re-run, or
+  an `--apply` that died part-way, a no-op — and what keeps two files that share a title
+  (`task-session-context.md` and `task-session-context.local.md` do) separately attributable. The
+  title rule is the fallback for records migrated by hand before the step existed, which cite no
+  source; a title match is therefore also the one case where a summary bead can stand in for a
+  file's content. A passing cross-reference outside a provenance section is not a record — the
+  step still creates that bead.
+
+- **Write order.** One `bd create --silent` per file, in path order, so a partial failure leaves
+  only the unmigrated files behind; the verification pass re-detects and must find nothing.
+
+Verify with `bd list -l kind:idea --json --limit 0`, then compare one bead's fields against its
+source file before the files are retired ("files present but already migrated" is a normal state:
+the plan simply has nothing to say about them).
+
+## Rollback recipes
+
+The pre-migration `bd export --all` snapshot plus the recorded dry-run plan is enough to undo any
+step. Work per label group, oldest rename last, and re-verify with the v1 checks after each
+inversion.
+
+Every `bd label` call in this skill passes issue ids first and the label last, matching the CLI's
+`bd label add [issue-id...] [label[,label...]]`. Reversing that order fails: the ids are resolved
+before the trailing argument is read as a label.
+
+```bash
+# Invert the v1 rename for a specific group
+bd label add <ids…> implementation-type:afk
+bd label remove <ids…> execution:afk
+
+# Confirm the inversion landed before touching the next group
+bd list -l execution:afk --all
+```
+
+Rules that keep recovery safe:
+
+- Drive every change through `bd`; editing `.beads/` files bypasses Dolt bookkeeping and produces
+  a workspace that disagrees with its own history.
+- Invert one group at a time and re-check. Whole-step inversion in one shot makes a partial
+  mistake indistinguishable from a partial success.
+- If the workspace is shared or synced (`bd dolt push` in use), say so in your report and pause
+  for the human owner before inverting — other clones may already have observed the rename.
+
+## Manual fallback (pinned version, no `migrate`)
+
+Use only when the installed package genuinely lacks the command and an upgrade is out of scope.
+Run exactly what v1 would run, with the same gate:
+```bash
+# Read the plan; confirm the group counts match what you expect
+bd export --all | grep '"implementation-type:'   # every bead, closed included
+bd label add <ids…> execution:afk
+bd label remove <ids…> implementation-type:afk
+bd label add <ids…> execution:hitl
+bd label remove <ids…> implementation-type:hitl
+bd label list-all                        # verify: nothing left
+```
+
+Then record in the handoff that the run did not go through the registry, so the repo still needs
+a `migrate` dry run once the command is available (it will simply find nothing to do).
+
+For step v2 by hand, follow the field table under _Step v2 — ideas to beads_ and create one bead
+per file:
+
+```bash
+bd create "Idea: <file title>" --silent -l kind:idea,execution:hitl -p P<n> \
+  -d "<## Problem, ## Who benefits, ## Proposed outcome>" \
+  --design "<## How we might do it>" \
+  --notes "<## Status, ## Validity check, ## Constraints, ## Next validation step, …>" \
+  --acceptance "<promotion criterion>"
+```
+
+Keep every `##` marker inside its field, check the title against `bd list -l kind:idea` before
+creating — a hand-run has no collision skip — and leave the source files in place unless the repo
+has already retired the file flow.
+
+## Stale-reference sweep
+
+The rename is not done while text still teaches the old label. Search the workspace for the old
+name and route each hit to its owner:
+
+```bash
+grep -rn "implementation-type" . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.beads
+```
+
+Classify each hit before editing: skill instructions and classifier logic (they apply labels),
+routing queries in orchestration docs (they filter on labels), and historical records such as
+changelogs, ADRs, or closed-bead notes (leave them — rewriting history removes the trail).
+
+## Reporting a run
+
+Record, in order: the detected version and steps planned, the snapshot location, the dry-run
+plan with the group sizes reconciled from the export (or, at v2, the per-file title and priority
+lines), the `--apply` summary, the four post-check results, the idempotence re-run outcome, and the
+stale-reference list with owning files. That sequence is also the evidence trail if a later
+post-check fails.

package/skills/productivity/migration/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: migration
+description: "Migrate a beads workspace to the two-axis model via the versioned `agent-cortex migrate` command: dry-run, apply, verify, recover. Use when asked to \"run the migration\" or \"rename the labels\"."
+disable-model-invocation: true
+---
+
+# Migration
+
+Bring a beads workspace up to the current workflow model by running the versioned
+`agent-cortex migrate` command in that workspace. From a checkout that is not installed, the same
+command is `node bin/agent-cortex.mjs migrate` — those are the only two invocations. The command
+keeps an ordered registry of steps, detects the version a repo is at, and applies each step in
+order until the repo is current — the same command migrates every workspace, whenever it joins.
+
+Steps are **dry-run by default**, **idempotent**, and **verified per step**. Your job is to
+plan, gate, and prove the run — never to hand-edit `.beads/` or a label list.
+
+Steps in the registry (full contract in `REFERENCE.md`):
+
+| Version | Step | Effect |
+|---|---|---|
+| v1 | Label rename | `implementation-type:afk\|hitl` → `execution:afk\|hitl`, all beads including closed |
+| v2 | Ideas → beads | `docs/ideas/*.md` (default; `--dir` overrides, one level of nesting included) become `kind:idea` + `execution:hitl` beads — the command reads the files and never deletes them |
+
+## When to use
+
+- A workspace's beads still carry `implementation-type:afk|hitl` and must move to `execution:*`.
+- The user says "run the migration", "rename the labels", "migrate this repo", or asks why
+  `bd ready -l execution:afk` returns nothing in a project that clearly has AFK work.
+- A repo adopts agent-cortex (or a newer version) and its existing beads predate the model.
+- Loose idea markdown still lives under `docs/ideas/` in a workspace and those records belong in
+  the backlog as beads (step v2).
+
+## When NOT to use
+
+- No `.beads/` in the workspace — initialise it first with the `init-beads` skill; there is
+  nothing to migrate.
+- The migration command is absent from the installed `agent-cortex` — upgrade the package
+  instead of hand-running steps. The only exception is the documented manual fallback in
+  `REFERENCE.md`, used when a fix is needed on a pinned version.
+- The repo's skills and routing queries still create and filter the *old* labels. Land those
+  updates first: renaming under a ralph that queries `implementation-type:afk` leaves the
+  workspace unroutable. Order the sequence; do not race it.
+
+## Workflow
+
+1. **Preflight.** Run `bd version`, `bd label list-all`, and `agent-cortex --help` (upgrade the
+   package if `migrate` is not listed). The command is `agent-cortex migrate`; if the CLI is not
+   on PATH, run it from the package checkout as `node bin/agent-cortex.mjs migrate`. Read
+   `agent-cortex migrate --help` for the flags this build accepts. Act on the version the registry
+   detects — do not infer it yourself.
+
+2. **Snapshot before touching anything.** `bd export --all -o <path>.jsonl` (JSONL of every issue
+   including closed, with labels and dependencies). `--all` also exports infrastructure beads,
+   templates, gates, and `bd remember` memories, so keep the file outside the repo or gitignored —
+   see _Snapshot scope_ in `REFERENCE.md`. This is the rollback source of truth; keep it until the
+   post-checks pass.
+
+3. **Dry run.** Run the command with no apply flag — dry-run is the default, and an explicit
+   `--dry-run` is equivalent. It writes nothing and exits 0. Read the plan it prints: the
+   workspace version against the latest, then the **first pending step** only — its name, one
+   line per pending item, the pending count, and the no-writes notice. A v1 line is a bead and the
+   labels it would gain and lose; a v2 line is an idea file and the title plus priority it becomes.
+   Steps behind a pending one are not named, and the plan does not group beads by label value —
+   take group sizes from the export counts in step 4.
+
+4. **Gate on the plan.** Apply only when all of these hold:
+   - The detected version and the steps to run match what you expect for this repo.
+   - Every `implementation-type:<value>` group maps to exactly one `execution:<value>` group.
+   - Group sizes reconcile with the legacy-label counts in `bd export --all` — the source the
+     command itself reads. A bead carrying both labels appears in both groups — expected, not a
+     conflict. Do not reconcile with `bd list --label-pattern` (see `REFERENCE.md`).
+   - No unmapped or novel label value: the rename is strict and only `afk|hitl` are mapped, so
+     the command refuses the whole run — dry run and `--apply` alike, nothing written — naming
+     each offending bead and label. Treat that error as a signal to inspect, not to work around.
+   - For a v2 plan, each line names the file, the title, and the priority it will carry. A file
+     missing from the plan is one the command considers already recorded (a bead citing the file
+     under `## Provenance` — which every bead the step creates does — or a source-less bead with
+     that title); confirm the record exists before accepting the skip, and do not hand-create a
+     replacement.
+
+5. **Apply.** Run the same command with `--apply`. Step v1 writes in batches per label value —
+   add the `execution:<value>` label, then remove the `implementation-type:<value>` label — so a
+   partial failure never loses the routing label. Step v2 creates one bead per idea file, one file
+   at a time, so a run that dies part-way leaves only the unmigrated files behind and the retry
+   resumes exactly there. Record the summary verbatim in your report.
+
+6. **Post-check.** Treat the migration as unproven until all of these hold:
+
+   ```bash
+   bd label list-all                              # no implementation-type:* remains
+   bd export --all | grep '"implementation-type:' # empty, closed beads included
+   bd ready -l execution:afk                      # same beads as the pre-migration AFK set
+   ```
+
+   Then grep the repo for stale `implementation-type` references (skills, docs, hooks, configs).
+   List the files still to update — they are follow-up work, not part of the rename.
+
+   For v2, check a migrated bead against its source file with `bd show <id>` before the files are
+   retired: `--description`, `--design`, and `--notes` carry the file's sections with their `##`
+   markers, and the priority matches what the file stated.
+
+7. **Prove idempotence.** Re-run the dry run. A converged repo plans zero targets, performs no
+   writes, and exits 0. A non-empty plan after `--apply` means the write step did not converge:
+   investigate before applying again.
+
+8. **Recover if needed.** A dry run that wrote nothing is the normal failure mode. For a
+   half-applied step, an inverted rename, or a bad plan, follow _Rollback and recovery_.
+
+9. **Continue the sequence.** The label rename is one step, not the migration. Idea files become
+   beads at a later step, and any skill, hook, or doc that creates or queries the old labels
+   must be updated before the workspace is truly current. Hand those edits to their owners; the
+   migration command does not rewrite prose — and it does not delete the idea files either. Retire
+   them (and any scaffold script that writes them) only after the skills that used the file flow
+   have stopped, or the repo recreates what you just deleted.
+
+Workflow at a glance:
+
+```text
+[Preflight: bd + command]
+          |
+          v
+[Snapshot: bd export --all]
+          |
+          v
+[Dry run: read plan] --(plan unexpected)--> [Stop: no writes]
+          |
+    (plan matches)
+          v
+     [Apply --apply]
+          |
+          v
+[Post-check 4 gates] --(fail)--> [Invert per group]
+          |
+        (pass)
+          v
+[Re-run dry run: no-op] --> [Hand off stale refs + later steps]
+```
+
+## Rollback and recovery
+
+- **Nothing applied yet** — the dry run wrote nothing, so discard the plan; the workspace is
+  untouched; the snapshot is not even needed.
+- **A step died mid-batch** — dry-run, then re-run `--apply`: steps are idempotent, so
+  already-renamed beads no longer match and an already-created idea bead cites its source file, so
+  the retry resumes instead of repeating writes — even when two files share one title.
+- **A completed step was wrong** — invert it per group from the recorded plan or pre-migration
+  export: `bd label add <ids…> implementation-type:<value>` then
+  `bd label remove <ids…> execution:<value>` (issue ids first, label last), through `bd`, never
+  by editing `.beads/` files.
+- **Unsure which groups moved** — diff the pre-migration export's label sets against
+  `bd export --all` now. Recipes and shared-workspace cautions are in `REFERENCE.md`.
+
+## Rationale: why the rename exists
+
+The workspace runs on two independent axes: **bead type** (`idea → epic → feature → chore`,
+what shape the work has) and **execution** (`execution:afk` = agent-routable, `execution:hitl` =
+human required). Hierarchy is ownership via `--parent`; ordering is `depends-on`, which alone
+gates readiness. `implementation-type:` collapsed the two axes and named one particular executor,
+which is why routing broke when the executor changed; `execution:` is agent-agnostic and is the
+exact value ralph queries (`bd ready -l execution:afk`). That is also why the rename is strict:
+the label *is* the query, so a half-migrated workspace does not error — it silently starves, and
+the queue looks empty instead of broken. Hence snapshot → dry run → gated apply → post-check.
+
+## See Also
+
+- [bd-tool](../bd-tool/SKILL.md) — bead query and label conventions the post-checks assume.
+- [classify-bead](../../planning/classify-bead/SKILL.md) — the classifier that applies `execution:*` labels to new beads after the rename.
+- [ralph](../../workflow/ralph/SKILL.md) — the consumer whose `execution:afk` query is the migration's smoke test.
+- [init-beads](../init-beads/SKILL.md) — load when the project has no `.beads/` workspace to migrate yet.
+
+## Verification checklist
+
+- [ ] `bd version` and `agent-cortex migrate --help` both ran; the flags this build accepts are known.
+- [ ] A pre-migration `bd export --all` snapshot exists and is readable.
+- [ ] The dry run reported a plan and wrote nothing (no label changes in `bd label list-all`).
+- [ ] The plan reconciles with the legacy-label counts in `bd export --all`.
+- [ ] The `--apply` summary is recorded verbatim: one line per step with its pending bead total
+      and a `verified` line. It reports no per-group counts — reconcile group sizes against the
+      step-4 export counts.
+- [ ] `bd label list-all` and the export grep in step 6 both show nothing left.
+- [ ] `bd ready -l execution:afk` returns the same beads as the pre-migration AFK set.
+- [ ] A repeat dry run is a no-op (zero targets, exit 0).
+- [ ] Stale `implementation-type` references are listed with their owning files, and later steps
+      (idea files → beads) plus skill/doc updates are handed off explicitly.
+- [ ] For v2: one `kind:idea` + `execution:hitl` bead exists per idea file, a spot-checked bead
+      carries its source sections in `--description`/`--design`/`--notes` with the original
+      priority, and the source files were left in place for the repo's own cutover to retire.

package/skills/productivity/validate-agent-dir/scripts/{validate-agent-dir.ts → validate-agent-dir.mjs}

@@ -1,43 +1,59 @@
+// @ts-check
+// Validator for the composable agent directory layout: `agent.md` plus at
+// least one harness subdirectory with a valid `frontmatter.json`.
+//
+// Zero dependencies: import the pure functions, or run the test suite at
+// `test/validate-agent-dir.test.mjs`.
+
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
-export interface Frontmatter {
-  name: string;
-  description: string;
-  tools: string[];
-  model?: string;
-  argumentHint?: string;
-  [key: string]: unknown;
-}
-
-export interface AgentDir {
-  name: string;
-  agentMdPath: string;
-  harnesses: Map<string, { frontmatter: Frontmatter; sections: string[] }>;
-}
-
-export interface ValidationResult {
-  ok: boolean;
-  errors: string[];
-}
+/**
+ * @typedef {object} Frontmatter
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} tools
+ * @property {string} [model]
+ * @property {string} [argumentHint]
+ */
+
+/**
+ * @typedef {object} AgentDir
+ * @property {string} name
+ * @property {string} agentMdPath
+ * @property {Map<string, { frontmatter: Frontmatter, sections: string[] }>} harnesses
+ */
+
+/**
+ * @typedef {object} ValidationResult
+ * @property {boolean} ok
+ * @property {string[]} errors
+ */
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-const REQUIRED_FIELDS = ["name", "description", "tools"] as const;
-const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"] as const;
+/** @type {readonly string[]} */
+const REQUIRED_FIELDS = ["name", "description", "tools"];
+/** @type {readonly string[]} */
+const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
 
 // ─── Validation ───────────────────────────────────────────────────────────────
 
-export function validateFrontmatter(fm: unknown): ValidationResult {
-  const errors: string[] = [];
+/**
+ * @param {unknown} fm
+ * @returns {ValidationResult}
+ */
+export function validateFrontmatter(fm) {
+  /** @type {string[]} */
+  const errors = [];
 
   if (typeof fm !== "object" || fm === null) {
     return { ok: false, errors: ["frontmatter must be an object"] };
   }
 
-  const record = fm as Record<string, unknown>;
+  const record = /** @type {Record<string, unknown>} */ (fm);
 
   // Check required fields
   for (const field of REQUIRED_FIELDS) {
@@ -70,7 +86,7 @@ export function validateFrontmatter(fm: unknown): ValidationResult {
   // Check for unknown fields
   const knownFields = new Set([...REQUIRED_FIELDS, ...KNOWN_OPTIONAL_FIELDS]);
   for (const key of Object.keys(record)) {
-    if (!knownFields.has(key as any)) {
+    if (!knownFields.has(/** @type {any} */ (key))) {
       errors.push(`unknown field: ${key}`);
     }
   }
@@ -78,8 +94,13 @@ export function validateFrontmatter(fm: unknown): ValidationResult {
   return { ok: errors.length === 0, errors };
 }
 
-export function validateAgentDir(agentDirPath: string): ValidationResult {
-  const errors: string[] = [];
+/**
+ * @param {string} agentDirPath
+ * @returns {ValidationResult}
+ */
+export function validateAgentDir(agentDirPath) {
+  /** @type {string[]} */
+  const errors = [];
 
   // Check agent.md exists
   const agentMdPath = join(agentDirPath, "agent.md");
@@ -118,7 +139,7 @@ export function validateAgentDir(agentDirPath: string): ValidationResult {
           errors.push(`${harnessDir}/frontmatter.json: ${err}`);
         }
       }
-    } catch (e) {
+    } catch {
       errors.push(`${harnessDir}/frontmatter.json: invalid JSON`);
     }
   }

package/skills/productivity/write-a-skill/SKILL.md

@@ -49,11 +49,11 @@ Verify the final document against the verification checklist below before finish
 - **Padding sections with generic content** — Every section must earn its place with content specific to the skill's purpose. Copying generic filler from the template placeholder text produces a weak skill.
 - **Skipping the trigger-phrase interview** — The description's trigger phrases are the main routing signal for the skill. Guessing what users say rather than asking produces a skill that is hard to invoke.
 
-## Cross-skill references
+## See Also
 
-- Use `refactor-skill` when the task is upgrading an existing skill rather than creating a new one.
-- Run `style-code` after writing to check that code conventions in any example snippets or bundled scripts are consistent.
-- Run `review-security` before committing to check for leaked secrets in examples or documentation.
+- [refactor-skill](../../review/refactor-skill/SKILL.md) — load when upgrading an existing skill rather than authoring a new one.
+- [style-code](../../style/style-code/SKILL.md) — load when the skill ships code examples or bundled scripts.
+- [review-security](../../review/review-security/SKILL.md) — run before committing, so examples carry no leaked credentials.
 
 ## Examples
 
@@ -72,4 +72,4 @@ Output: A new `skills/review-security/SKILL.md` with front matter, When to use,
 - [ ] No ALL-CAPS emphasis
 - [ ] `SKILL.md` ≤ 150 lines (`wc -l skills/<name>/SKILL.md`)
 - [ ] Supporting docs split by purpose when `SKILL.md` exceeds ~150 lines
-- [ ] Cross-skill references point to `refactor-skill` for upgrades where relevant
+- [ ] `See Also` entries link the target `SKILL.md` relatively, state why to load it, and point to `refactor-skill` for upgrades where relevant

package/skills/review/maintain-agent-docs/SKILL.md

@@ -74,14 +74,12 @@ See [REFERENCE.md](REFERENCE.md) for templates, examples, and detailed section g
 - [ ] Phase 1 complete: audit findings presented as a numbered list; nothing fixed yet.
 - [ ] Phase 2 complete: every proposal reviewed and approved before applying.
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| What and whether to document | `style-documentation` |
-| Tone, structure, and concision for the writing | `style-comms` |
-| Creating or refactoring a skill | `write-a-skill`, `refactor-skill` |
-| Scanning changes for leaked secrets | `review-security` |
+- [style-documentation](../../style/style-documentation/SKILL.md) — what and whether to document, applied to the pages being audited.
+- [style-comms](../../style/style-comms/SKILL.md) — tone and concision for the prose being edited.
+- [refactor-skill](../refactor-skill/SKILL.md) — load when the drift is inside a SKILL.md instead of docs/.
+- [review-security](../review-security/SKILL.md) — run before committing, so audited examples carry no leaked credentials.
 
 ## Examples
 

package/skills/review/refactor-skill/SKILL.md

@@ -14,7 +14,8 @@ description: Refactor an existing SKILL.md to the canonical anatomy template thr
 
 ## When NOT to use
 
-- Creating a brand-new skill from scratch — use `write-a-skill` instead.
+- Creating a brand-new skill from scratch — use [write-a-skill](../../productivity/write-a-skill/SKILL.md) instead.
+- Drift in `AGENTS.md` or `docs/` rather than in a `SKILL.md` — use [maintain-agent-docs](../maintain-agent-docs/SKILL.md).
 - Minor copy-editing or typo fixes that don't need anatomy alignment.
 - Skills that are already verified against the anatomy template.
 
@@ -42,7 +43,7 @@ Run through each dimension of the anatomy template and record how the target cur
 - **Red Flags**: present? Only include for discipline-enforcement skills (security, TDD, review).
 - **Common Rationalizations**: present? Only include for process-critical skills where shortcut pressure is common.
 - **Phase-gate checklists**: present? Only include for multi-phase workflows (3+ distinct phases).
-- **Cross-skill references**: present? Only include when another skill owns a sub-domain better than restating.
+- **See Also**: present? Only include when another skill owns a sub-domain better than restating — as a relative `SKILL.md` link plus the reason to load it.
 - **Examples**: present? Only include for non-trivial output contracts.
 - **Verification checklist**: present? Concrete, machine-checkable items?
 - **Voice/tone**: imperative second-person? Positive framing? Rationale sentences for non-obvious rules?
@@ -68,7 +69,7 @@ Present the comparison and discuss optional sections using the inclusion criteri
 | `Red Flags` | The skill enforces process discipline (security, TDD, review) |
 | `Common Rationalizations` | The skill is process-critical where shortcut pressure is common |
 | `Phase-gate checklists` | The workflow has 3+ distinct phases |
-| `Cross-skill references` | Another skill owns a sub-domain the workflow delegates to |
+| `See Also` | Another skill owns a sub-domain the workflow delegates to |
 | `Examples` | The output contract is non-trivial (formats, schemas, templates) |
 | `Philosophy / rationale` | The skill defends an opinionated method with trade-offs |
 

package/skills/review/review-security/SKILL.md

@@ -71,12 +71,10 @@ When running within a ralph review pipeline, the outcome is communicated through
 | "I will scan before pushing, not before committing" | The earlier you catch it, the cheaper it is. Pre-commit scan costs two seconds. |
 | "This is a false positive" | It might be. Verify the context before dismissing it. |
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| Code conventions that help avoid embedding secrets | `style-code` |
-| Documentation conventions that keep examples secret-free | `style-documentation` |
+- [style-code](../../style/style-code/SKILL.md) — the conventions that keep secrets out of the code in the first place.
+- [style-documentation](../../style/style-documentation/SKILL.md) — the conventions that keep examples in docs secret-free.
 
 ## Examples
 

package/skills/style/style-code/SKILL.md

@@ -68,17 +68,12 @@ description: Defines this project's coding style, conventions, and architectural
 | "A factory closure is more functional/pure" | State is state — a class names it. A closure over mutable state is an object with extra steps: the state is still there, the API is less discoverable, and nothing is gained. Use `#private` fields and public methods. |
 | "It's convenient to return the saved row / new count from the write" | That return turns a command into a query mid-flight: the caller now depends on data the mutation happens to produce. Return a typed result for the outcome, and let a separate query read the state if the caller needs it. |
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| Test-first development loop | `tdd` |
-| Test writing conventions | `style-tests` |
-| Building or hardening the project's ubiquitous language | `grill-with-docs` |
-| Communication tone and document structure | `style-comms` |
-| What and whether to document | `style-documentation` |
-| Surfacing architectural friction and deepening shallow modules | `improve-codebase-architecture` |
-| Secrets and credential scanning | `review-security` |
+- [tdd](../../engineering/tdd/SKILL.md) — the red-green loop that drives the code being named.
+- [style-tests](../style-tests/SKILL.md) — assertion, mock, and test-data conventions, which these rules leave out.
+- [grill-with-docs](../../engineering/grill-with-docs/SKILL.md) — the ubiquitous language that names and boundaries should follow.
+- [review-security](../../review/review-security/SKILL.md) — run before committing, for leaked secrets these rules cannot catch.
 
 ## Examples