crewly 1.8.9 → 1.8.12

package/config/skills/orchestrator/wiki-cleanup/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: Wiki Cleanup
+description: Detect + remove low-quality pages from a wiki vault (low confidence, agent memory dumps, per-agent overflow). Default dry-run; archives every deletion; idempotent.
+version: 1.0.0
+category: knowledge
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+---
+
+# Wiki Cleanup
+
+Removes low-quality pages from a wiki vault. Origin: the 2026-05-27 migrate pass dumped every agent's `memory.json roleKnowledge[]` entries as their own wiki page (~3,277 pages across 6 project vaults). Many are stream-of-consciousness daily memory rather than team-level patterns. This skill identifies + deletes them safely.
+
+## Two modes
+
+### scan (default) — dry-run
+
+Walks `<vault>/llm-curated/**/*.md`, parses each page's frontmatter, and returns the list of pages flagged by at least one cleanup rule. **No filesystem mutation.** Use this to eyeball what would be deleted before running apply.
+
+```bash
+bash execute.sh --vault /Users/me/proj/.crewly/wiki
+bash execute.sh --vault /Users/me/proj/.crewly/wiki --min-confidence 0.4
+bash execute.sh --vault /Users/me/proj/.crewly/wiki --max-per-agent 20
+```
+
+Output:
+```json
+{
+  "candidates": [
+    { "relPath": "llm-curated/patterns/x.md", "reasons": ["confidence 0.3 < 0.5"], ... }
+  ],
+  "scannedCount": 526,
+  "summary": { "lowConfidence": 412, "agentMemoryDump": 380, "perAgentCapped": 18 },
+  "truncated": false
+}
+```
+
+### apply — execute deletes
+
+Deletes the explicit `--pages` list and archives each page's body + frontmatter to `<vault>/.wiki-cleanup-archive.json`. The migrate manifest (`.migration-state.json`) is **deliberately left intact** so that `wiki-migrate --apply` sees "already migrated" for the cleaned-up `sourceId`s and skips re-import. Touching the manifest would break that idempotence and the page would resurrect on the next bridge tick (the 2026-05-28 cleanup-then-migrate-resurrection bug).
+
+```bash
+bash execute.sh --vault /Users/me/proj/.crewly/wiki \
+  --apply \
+  --pages "llm-curated/patterns/a.md,llm-curated/patterns/b.md"
+```
+
+Output:
+```json
+{
+  "deleted": ["llm-curated/patterns/a.md", "llm-curated/patterns/b.md"],
+  "skipped": [],
+  "archivePath": "/Users/me/proj/.crewly/wiki/.wiki-cleanup-archive.json",
+  "manifestEntriesInvalidated": 2
+}
+```
+
+## Scan rules
+
+| Rule | Default | Disables via | What it catches |
+|---|---|---|---|
+| `--min-confidence FLOAT` | `0.5` | `--min-confidence 0` | Pages with frontmatter `confidence < threshold`. Migrate sets this when the classifier was uncertain — usually correlates with low-quality content. |
+| (drop agent memory dumps) | ON | `--no-drop-agent-memory` | Pages with `migrated_from: "agent/<id>/memory.json"`. These are verbatim daily-memory dumps, NOT team-level patterns. |
+| `--max-per-agent INT` | `0` (off) | omit flag | Keeps top-N pages per `original_author` (by confidence desc, original_date desc). Useful for taming pathological cases where one agent dumped 100+ entries. |
+
+A page is a candidate if it matches **any** rule (union, not intersection). The per-agent cap only considers pages NOT already flagged by other rules — so a low-confidence page doesn't "use up" a cap slot.
+
+## Safety guarantees
+
+- **Default dry-run.** Without `--apply`, nothing is written.
+- **Archive before delete.** Every deleted page's body + frontmatter is appended to `.wiki-cleanup-archive.json` BEFORE the file is removed. Rollback = "paste body back into the path from the archive."
+- **Migrate manifest is preserved.** Cleanup deletes the file on disk but never touches `.migration-state.json` — the manifest is what makes `wiki-migrate --apply` idempotent. Future migrate runs see the matching `sourceId` + content hash and skip re-import. Page stays deleted.
+- **Frozen folders are protected.** `memory/`, `sop/`, `sop-overrides/`, `okr/` are NEVER scanned and NEVER deleted (even if the caller passes a frozen-folder path to `--pages`, apply skips it with `reason: 'frozen'`).
+- **Path-traversal guard.** Any `--pages` entry that resolves outside the vault (`../../etc/passwd` etc) is skipped with `reason: 'outside_vault'`.
+- **Idempotent.** A `--apply` re-run on the same `--pages` list with already-deleted entries is a no-op (each missing file → `reason: 'not_found'`).
+- **Legacy source files are NEVER touched.** `~/.crewly/agents/*/memory.json` and `<project>/.crewly/knowledge/*` stay as-is. Cleanup only removes wiki pages.
+
+## When to invoke
+
+- **Operator one-shot**: you notice `<project>/.crewly/wiki/llm-curated/patterns/` has 500+ entries. Run `scan` to see candidates, then `apply` with the page list you actually want gone.
+- **Bridge-auto**: starting 2026-05-28 the `WikiWorkItemBridge` periodically scans every vault and creates `wiki_quality_cleanup` WorkItems with a chunked candidate list. The agent claims the WI, reads the brief, and calls `--apply` with the explicit list of pages it decided to delete. See your prompt's "Bridge-auto WorkItems — DO NOT bulk-delete" rule.
+
+## Failure modes
+
+- `400 invalid_input` — `vaultPath` missing or `pages` empty on apply.
+- `404 vault_missing` — `vaultPath` does not exist on disk.
+- `400 confirm_required` — apply was POSTed without `confirm: true` (the skill always sets this; see the underlying HTTP route for raw clients).

package/config/skills/orchestrator/wiki-cleanup/execute.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# wiki-cleanup — detect + remove low-quality pages from a wiki vault.
+#
+# Two modes:
+#   scan   (default) — dry-run. Returns the list of cleanup candidates
+#                      with their reasons (low confidence / agent
+#                      memory dump / per-agent cap). No filesystem writes.
+#   apply             — delete the listed pages, archive each body +
+#                       frontmatter to <vault>/.wiki-cleanup-archive.json,
+#                       and invalidate matching migrate-manifest entries
+#                       so the same source can't re-import the page.
+#
+# Safety:
+#   - LEGACY FILES are never touched (memory.json, .crewly/knowledge/*).
+#   - Frozen folders (memory/, sop/, sop-overrides/, okr/) are not scanned.
+#   - apply requires an explicit `--pages` list — the caller (usually an
+#     agent in the loop) decides which scan candidates to actually delete.
+#
+# Usage:
+#   bash execute.sh --vault /abs/vault                                # scan with defaults
+#   bash execute.sh --vault /abs/vault --min-confidence 0.4           # scan with custom rule
+#   bash execute.sh --vault /abs/vault --apply --pages "a.md,b.md"    # delete the two listed pages
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+INPUT_JSON=""
+VAULT=""
+APPLY="false"
+PAGES_CSV=""
+MIN_CONFIDENCE=""
+DROP_AGENT_MEMORY=""
+MAX_PER_AGENT=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"; shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --vault|-v)          VAULT="$2"; shift 2 ;;
+    --apply|-a)          APPLY="true"; shift ;;
+    --pages|-p)          PAGES_CSV="$2"; shift 2 ;;
+    --min-confidence)    MIN_CONFIDENCE="$2"; shift 2 ;;
+    --no-drop-agent-memory)
+                         DROP_AGENT_MEMORY="false"; shift ;;
+    --max-per-agent)     MAX_PER_AGENT="$2"; shift 2 ;;
+    --json|-j)           INPUT_JSON="$2"; shift 2 ;;
+    --help|-h)
+      cat <<EOF
+Usage:
+  execute.sh --vault <abs path>                                  # scan (dry-run)
+  execute.sh --vault <abs path> --min-confidence 0.4             # scan with custom threshold
+  execute.sh --vault <abs path> --apply --pages "X.md,Y.md"      # delete listed pages
+
+Scan rules (applied independently — any match flags the page):
+  --min-confidence FLOAT      Pages with frontmatter confidence < FLOAT
+                              (default 0.5).
+  --no-drop-agent-memory      Disable the "drop pages migrated_from:
+                              agent/<id>/memory.json" rule (default ON).
+  --max-per-agent INT         Keep top-N (by confidence desc, date desc)
+                              per original_author. Default 0 = disabled.
+
+Apply:
+  --apply                     Execute deletes (requires --pages).
+  --pages "X.md,Y.md"         Comma-separated relative paths to delete.
+                              Each MUST be under the vault. Paths under
+                              frozen folders (memory/, sop/, ...) are
+                              refused even with --apply.
+
+Outputs a JSON report:
+  scan:  { candidates: [...], scannedCount, summary, truncated }
+  apply: { deleted: [...], skipped: [...], archivePath, manifestEntriesInvalidated }
+
+Re-runs are safe — apply is idempotent (a missing file is "skipped").
+EOF
+      exit 0 ;;
+    --) shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then INPUT_JSON="$1"; shift
+      else error_exit "Unknown argument: $1"; fi ;;
+  esac
+done
+
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$VAULT" ] && VAULT=$(printf '%s' "$INPUT" | jq -r '.vaultPath // empty')
+  if printf '%s' "$INPUT" | jq -e '.apply == true' >/dev/null 2>&1; then APPLY="true"; fi
+  if [ -z "$PAGES_CSV" ]; then
+    JSON_PAGES=$(printf '%s' "$INPUT" | jq -r '.pages // [] | join(",")')
+    [ -n "$JSON_PAGES" ] && PAGES_CSV="$JSON_PAGES"
+  fi
+  if [ -z "$MIN_CONFIDENCE" ]; then
+    MIN_CONFIDENCE=$(printf '%s' "$INPUT" | jq -r '.rules.minConfidence // empty')
+  fi
+  if [ -z "$MAX_PER_AGENT" ]; then
+    MAX_PER_AGENT=$(printf '%s' "$INPUT" | jq -r '.rules.maxPerAgent // empty')
+  fi
+fi
+
+require_param "vaultPath (--vault)" "$VAULT"
+
+export _WC_V="$VAULT"
+
+if [ "$APPLY" = "true" ]; then
+  if [ -z "$PAGES_CSV" ]; then
+    error_exit "--apply requires --pages with at least one relative path"
+  fi
+  # Convert CSV → JSON array of trimmed strings.
+  export _WC_PAGES="$PAGES_CSV"
+  BODY=$(jq -n '{
+    vaultPath: env._WC_V,
+    pages: (env._WC_PAGES | split(",") | map(gsub("^\\s+|\\s+$"; ""))),
+    confirm: true
+  }')
+  api_call POST "/wiki/cleanup/apply" "$BODY"
+  unset _WC_PAGES
+else
+  # Build rules object only with keys the user actually set.
+  RULES_JSON="{}"
+  if [ -n "$MIN_CONFIDENCE" ]; then
+    export _WC_MC="$MIN_CONFIDENCE"
+    RULES_JSON=$(printf '%s' "$RULES_JSON" | jq '. + {minConfidence: (env._WC_MC | tonumber)}')
+    unset _WC_MC
+  fi
+  if [ "$DROP_AGENT_MEMORY" = "false" ]; then
+    RULES_JSON=$(printf '%s' "$RULES_JSON" | jq '. + {dropAgentMemoryDumps: false}')
+  fi
+  if [ -n "$MAX_PER_AGENT" ]; then
+    export _WC_MPA="$MAX_PER_AGENT"
+    RULES_JSON=$(printf '%s' "$RULES_JSON" | jq '. + {maxPerAgent: (env._WC_MPA | tonumber)}')
+    unset _WC_MPA
+  fi
+  export _WC_RULES="$RULES_JSON"
+  BODY=$(jq -n '{vaultPath: env._WC_V, rules: (env._WC_RULES | fromjson)}')
+  api_call POST "/wiki/cleanup/scan" "$BODY"
+  unset _WC_RULES
+fi
+unset _WC_V

package/config/skills/orchestrator/wiki-lint/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: Wiki Lint
+description: Deterministic vault validation — frozen-path violations, dangling wikilinks, orphan pages, stale claims, restructure proposals. Reports only; the agent decides what to fix.
+version: 1.0.0
+category: knowledge
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+---
+
+# Wiki Lint
+
+Per v2.1 spec §3, the third Phase 1 wiki skill (alongside `wiki-ingest` and `wiki-query`). Unlike `wiki-bookkeep` which surfaces HEALTH metrics (counts, recent activity, duplicate clusters), `wiki-lint` validates CORRECTNESS:
+
+| Check | Surfaces | Why it matters |
+|---|---|---|
+| `frozenPathRespected` | Ingest-style files inside frozen folders | Frozen paths (`memory/`, `sop/`, `team-norm/`, `sop-overrides/`, `okr/`) are OSS-referenced; LLM-curated content there breaks `get-sops` / `remember` / etc. |
+| `missingEntities` | `[[wikilinks]]` that resolve to no page in the vault | Renamed-target or hallucinated link; dead reference must be fixed or removed. |
+| `orphanPages` | Pages with zero incoming wikilinks (excluding `log.md`, `index.md`, `README*`, `SCHEMA.md`) | Either the page should be linked from somewhere or it should be archived — orphans are "did anyone find this useful?" candidates. |
+| `staleClaims` | Files un-touched for `staleDays` (default 90) | Old enough to need a freshness check — the claim may have been superseded by newer pages. |
+| `restructureProposals` | Heuristic proposals (e.g. "add an index.md" for big folders) | LLM-curated only; lint refuses to alter frozen paths. |
+
+**The skill never modifies the vault.** It produces a JSON report; the agent's LLM reads it, decides what to do, and routes through `wiki-ingest` for any rewrites.
+
+## When to run
+
+- After a `wiki-bookkeep` consolidation pass (verify the merges didn't create new orphans or dangling links).
+- When you suspect drift — e.g. a customer page was renamed and other pages may still point at the old name.
+- As part of a weekly cron (the bookkeep trigger may grow to fire lint too).
+
+## Inputs
+
+| Flag | Required | Default | Description |
+|---|---|---|---|
+| `--vault <path>` | yes | — | Absolute vault path (must contain `SCHEMA.md`). |
+| `--stale-days <n>` | no | 90 | Files older than this count as stale claims. |
+
+## What you do with the report
+
+1. **`frozenPathRespected: false`** is the most serious finding — a `wiki-ingest` call somehow wrote into a frozen folder (the runtime usually rejects this with 422; if you see it here, file a bug). For each violation, move the file to `llm-curated/` (`wiki-ingest --target llm-curated/<…>`) and delete the original.
+2. **`missingEntities`** — open the source page, fix or remove the dangling link.
+3. **`orphanPages`** — for each, decide: add an inbound link (edit a parent index page) OR mark for archive in your reply.
+4. **`staleClaims`** — for each, decide if the claim is still true. If superseded, link the newer page; if no longer relevant, mark for archive.
+5. **`restructureProposals`** — pick the high-value ones and act on them via `wiki-ingest`.
+
+## Output
+
+```json
+{
+  "success": true,
+  "report": {
+    "vault": { "scope": "project", "id": "crewly", "path": "..." },
+    "generatedAt": "2026-05-24T19:00:00.000Z",
+    "staleDays": 90,
+    "frozenPathRespected": true,
+    "frozenViolations": [],
+    "missingEntities": [
+      { "sourcePath": "llm-curated/decisions/pricing.md", "target": "ghost-page", "lineNumber": 7 }
+    ],
+    "orphanPages": ["llm-curated/customers/forgotten.md"],
+    "staleClaims": ["llm-curated/patterns/old-pattern.md"],
+    "restructureProposals": [
+      { "description": "llm-curated/decisions/ has 31 pages and no index.md ...", "path": "llm-curated/decisions" }
+    ],
+    "truncated": false
+  }
+}
+```
+
+## Failure modes
+
+- `404 vault_missing` — vault directory does not exist.
+- `404 schema_missing` — SCHEMA.md not found or unparseable.
+- `400 invalid_input` — vaultPath not absolute / staleDays not positive.

package/config/skills/orchestrator/wiki-lint/execute.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# wiki-lint — deterministic vault validation pass.
+#
+# Distinct from wiki-bookkeep (which reports HEALTH metrics). Lint focuses
+# on CORRECTNESS:
+#   - frozenPathRespected (no ingest-style writes inside frozen folders)
+#   - missingEntities      ([[wikilinks]] that resolve to no page)
+#   - orphanPages          (pages with zero incoming wikilinks)
+#   - staleClaims          (untouched for staleDays, default 90)
+#   - restructureProposals (heuristics for llm-curated/ only)
+#
+# This skill does NOT modify the vault. Your runtime reads the report and
+# decides next actions: rename / merge / archive (via wiki-ingest for the
+# rewrites; archiving is out of Phase 1 scope — surface in chat).
+#
+# Usage:
+#   bash execute.sh --vault /path
+#   bash execute.sh --vault /path --stale-days 60
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+INPUT_JSON=""
+VAULT_PATH=""
+STALE_DAYS=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"; shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --vault|-v)       VAULT_PATH="$2";  shift 2 ;;
+    --stale-days|-s)  STALE_DAYS="$2";  shift 2 ;;
+    --json|-j)        INPUT_JSON="$2";  shift 2 ;;
+    --help|-h)
+      cat <<EOF
+Usage:
+  execute.sh --vault <path> [--stale-days 90]
+
+Runs a deterministic validation pass and returns a JSON report. Each
+section is capped to 50 rows so the payload stays bounded. The skill
+makes no LLM calls; your runtime decides what to act on.
+EOF
+      exit 0 ;;
+    --) shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then INPUT_JSON="$1"; shift
+      else error_exit "Unknown argument: $1"; fi ;;
+  esac
+done
+
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$VAULT_PATH" ] && VAULT_PATH=$(printf '%s' "$INPUT" | jq -r '.vaultPath  // empty')
+  [ -z "$STALE_DAYS" ] && STALE_DAYS=$(printf '%s' "$INPUT" | jq -r '.staleDays  // empty')
+fi
+
+require_param "vaultPath (--vault)" "$VAULT_PATH"
+
+export _WL_V="$VAULT_PATH"
+BODY=$(jq -n '{vaultPath: env._WL_V}')
+[ -n "$STALE_DAYS" ] && BODY=$(echo "$BODY" | jq --argjson s "$STALE_DAYS" '. + {staleDays: $s}')
+unset _WL_V
+
+api_call POST "/wiki/lint" "$BODY"

package/config/skills/orchestrator/wiki-migrate/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: Wiki Migrate
+description: One-shot conversion from legacy `.crewly/knowledge/*.json` + loose `.md` + agent `memory.json` into the v2.1 three-scope vault structure. Default dry-run; idempotent; never deletes legacy files.
+version: 1.0.0
+category: knowledge
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+---
+
+# Wiki Migrate
+
+For users who installed Crewly BEFORE the v2.1 LLM-wiki landed (2026-05-22+). The legacy knowledge stores live at:
+
+| Legacy source | New target |
+|---|---|
+| `<project>/.crewly/knowledge/decisions.json[]` | `<project>/.crewly/wiki/llm-curated/decisions/<date>-<slug>.md` |
+| `<project>/.crewly/knowledge/patterns.json[]` | `<project>/.crewly/wiki/llm-curated/patterns/<date>-<slug>.md` |
+| `<project>/.crewly/knowledge/gotchas.json[]` | `<project>/.crewly/wiki/llm-curated/patterns/<date>-<slug>.md` |
+| `<project>/.crewly/knowledge/relationships.json[]` | `<project>/.crewly/wiki/llm-curated/people/<date>-<slug>.md` |
+| `<project>/.crewly/knowledge/learnings.md` | appended to `<project>/.crewly/wiki/llm-curated/log.md` |
+| `<project>/.crewly/knowledge/*.md` (loose) | `<project>/.crewly/wiki/llm-curated/decisions/<slug>.md` |
+| `<project>/.crewly/docs/*.md` ← **legacy `query-knowledge` storage** | `<project>/.crewly/wiki/llm-curated/docs/<slug>.md` |
+| `<project>/CLAUDE.md` / `AGENTS.md` / `DEPLOYMENT*.md` | `<project>/.crewly/wiki/llm-curated/runbooks/<slug>.md` |
+| `<project>/deploy/*.md`, `<project>/docs/deploy*.md`, `<project>/.claude/commands/deploy*.md` | `<project>/.crewly/wiki/llm-curated/runbooks/<slug>.md` |
+| `~/.crewly/agents/<id>/memory.json roleKnowledge[]` | `<project>/.crewly/wiki/llm-curated/{patterns,decisions}/<date>-<slug>.md` (copy; original retained) |
+| `<crewly-src>/config/sops/<role>/*.md` (OSS-distributed) | `~/.crewly/global-wiki/llm-curated/sops/<role>/<slug>.md` (via `migrate/oss-sops`) |
+| `<crewly-src>/config/domain-sops/*.sop.md` | `~/.crewly/global-wiki/llm-curated/sops/domain/<slug>.md` |
+| `<crewly-src>/config/templates/pro-sops/norms/*.md` | `~/.crewly/global-wiki/llm-curated/sops/pro-norms/<slug>.md` |
+
+Per spec §6 the agent's `memory.json` stays put — this skill **copies** its `roleKnowledge` entries to the wiki rather than moving them, so private agent memory keeps working unchanged.
+
+## What the legacy stores were (and what replaces them)
+
+The migration **fully retires** the legacy `query-knowledge` skill (2026-05-27). After migration:
+
+- `<project>/.crewly/docs/*.md` → still on disk (NOT deleted) but no agent skill reads them; **all content is in the wiki**
+- `<project>/.crewly/knowledge/*` → same — preserved as source of truth but consumers now use `wiki-query`
+- The single replacement skill is `wiki-query` (v2.1) — same query verb, richer vault routing (global / team / project)
+
+If you're updating prompts that referenced `query-knowledge`, swap to:
+
+```bash
+bash {{AGENT_SKILLS_PATH}}/core/wiki-query/execute.sh --vault <vault-path> --query "<topic>" --top-k 5
+```
+
+Vault picker:
+- Org-wide SOPs / cross-team decisions / OKR → `~/.crewly/global-wiki`
+- Team SOPs / team norms → `~/.crewly/teams/<team-uuid>/wiki`
+- Project decisions / customers / project runbooks → `<project-root>/.crewly/wiki`
+
+## Guarantees
+
+- **Default dry-run.** No writes happen unless `--apply` (or `confirm: true` in JSON body) is passed.
+- **Idempotent.** A manifest at `<vault>/.migration-state.json` records every migrated entry's content hash + sourceId. Re-runs skip duplicates.
+- **Legacy preserved.** `.crewly/knowledge/` and `memory.json` files are NEVER deleted. Rollback is just "ignore the new vault."
+- **Bootstrap on apply.** If the project / global / team vaults are missing `SCHEMA.md`, they're created with the v2.1 skeleton before any content lands.
+- **Routing default.** Everything goes to the project vault. Items whose body looks cross-project (mention foreign team UUIDs, "company-wide", OKR lingo, cross-project codenames) are tagged `routing_uncertain: true` in frontmatter; `wiki-lint` surfaces them later for human review / promotion to global.
+
+## Inputs
+
+| Flag | Required | Default | Description |
+|---|---|---|---|
+| `--project-root <abs path>` | yes | — | The dir containing `.crewly/`. |
+| `--apply` | no | off | Execute writes. Without this, run a dry-run scan. |
+| `--no-memory` | no | off | Skip the per-agent `memory.json` import. |
+
+## What you do with the report
+
+**On scan (dry-run):**
+- Read `proposedPages` — each row tells you target path, source file, sourceId.
+- Look at `bootstrapNeeded` — confirms which vaults will be created.
+- Look at `summary` — counts per source type.
+- Look for `routingUncertain: true` rows — these will land in the project vault but flagged for later human review.
+
+**On apply:**
+- Confirm `applied` count matches the proposal.
+- `bootstrapped` lists the vault dirs newly created.
+- `manifestPath` is the persistent ledger — `cat` it to audit the migration.
+- Run `wiki-lint --vault <project-vault>` afterwards to surface any `routing_uncertain` items.
+
+## Examples
+
+**Dry-run:**
+```bash
+bash execute.sh --project-root /Users/me/code/myproject
+```
+
+**Apply for real:**
+```bash
+bash execute.sh --project-root /Users/me/code/myproject --apply
+```
+
+**Apply but skip agent memory.json copies:**
+```bash
+bash execute.sh --project-root /Users/me/code/myproject --no-memory --apply
+```
+
+## Failure modes
+
+- `400 invalid_input` — `projectRoot` is not absolute, or `confirm` was missing on apply (skill handles this automatically).
+- `404 project_root_missing` — the directory doesn't exist.

package/config/skills/orchestrator/wiki-migrate/execute.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# wiki-migrate — one-shot conversion of legacy `.crewly/knowledge/*.json` +
+# loose .md + agent memory.json into the v2.1 three-scope vault structure.
+#
+# Two modes:
+#   scan   (default) — dry-run preview. Returns proposed pages with
+#                      target paths, no writes.
+#   apply             — execute the migration. Bootstraps missing vaults,
+#                       writes pages, records a manifest. LEGACY FILES
+#                       ARE NEVER DELETED.
+#
+# Safe to re-run. The manifest at <project>/.crewly/wiki/.migration-state.json
+# tracks already-migrated entries by content hash + sourceId.
+#
+# Usage:
+#   bash execute.sh --project-root /abs/path                       # scan
+#   bash execute.sh --project-root /abs/path --apply               # write
+#   bash execute.sh --project-root /abs/path --no-memory --apply   # skip agent memory.json copies
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+INPUT_JSON=""
+PROJECT_ROOT=""
+APPLY="false"
+INCLUDE_MEMORY="true"
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"; shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project-root|-p) PROJECT_ROOT="$2"; shift 2 ;;
+    --apply|-a)        APPLY="true";     shift   ;;
+    --no-memory)       INCLUDE_MEMORY="false"; shift ;;
+    --json|-j)         INPUT_JSON="$2";  shift 2 ;;
+    --help|-h)
+      cat <<EOF
+Usage:
+  execute.sh --project-root <abs path>            # scan (dry-run)
+  execute.sh --project-root <abs path> --apply    # execute migration
+  execute.sh --project-root <abs path> --no-memory --apply
+                                                  # apply but skip agent memory.json copies
+
+Outputs a JSON report:
+  - legacyDetected   : true when any legacy source exists
+  - proposedPages    : per-entry target + skipReason (when "already migrated")
+  - bootstrapNeeded  : which vaults will be bootstrapped on --apply
+  - summary          : counts per source type
+  - applied/skipped  : only present on --apply
+
+The skill makes NO LLM calls. Re-running is safe (idempotent via manifest).
+EOF
+      exit 0 ;;
+    --) shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then INPUT_JSON="$1"; shift
+      else error_exit "Unknown argument: $1"; fi ;;
+  esac
+done
+
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$PROJECT_ROOT" ] && PROJECT_ROOT=$(printf '%s' "$INPUT" | jq -r '.projectRoot       // empty')
+  if printf '%s' "$INPUT" | jq -e '.apply == true' >/dev/null 2>&1; then APPLY="true"; fi
+  if printf '%s' "$INPUT" | jq -e '.includeAgentMemory == false' >/dev/null 2>&1; then INCLUDE_MEMORY="false"; fi
+fi
+
+require_param "projectRoot (--project-root)" "$PROJECT_ROOT"
+
+export _WM_R="$PROJECT_ROOT"
+export _WM_M="$INCLUDE_MEMORY"
+
+if [ "$APPLY" = "true" ]; then
+  BODY=$(jq -n '{projectRoot: env._WM_R, includeAgentMemory: (env._WM_M == "true"), confirm: true}')
+  api_call POST "/wiki/migrate/apply" "$BODY"
+else
+  BODY=$(jq -n '{projectRoot: env._WM_R, includeAgentMemory: (env._WM_M == "true")}')
+  api_call POST "/wiki/migrate/scan" "$BODY"
+fi
+unset _WM_R _WM_M

package/config/skills/orchestrator/wiki-process-queue/SKILL.md

@@ -21,9 +21,16 @@ Claim the next pending queue item and get back the vault state your runtime's LL
    - **Merge** into an existing `result.vaultContext.candidatePages[i].path` — preferred if a candidate fits.
    - **Create** a new page under `llm-curated/<freshly-invented-subfolder>/<slug>.md`. You may invent subfolder names; there is NO preset taxonomy.
    - **Skip** if you decide the item isn't wiki-worthy after all.
-4. Commit:
+4. **Cascade-update related pages (2026-05-26 — Karpathy 10-15-pages-per-source rule).** After writing the primary target, ask: *"what existing pages in this vault are now stale or contradicted because of this new content?"* Run `wiki-query` with the topic to surface related pages, read each, and decide:
+   - **Update**: the new content changes the truth of that page → `wiki-ingest --target <that-page>` with the updated body
+   - **Cross-link**: just add a `[[<primary-target-slug>]]` to that page so future readers find the connection
+   - **Leave alone**: no contradiction, no overlap — skip
+   - **Update `index.md`**: if you created a new sub-folder or added a load-bearing page, append a link in `llm-curated/index.md` (create the file if absent)
+   - Aim for **3-7 cascade touches per primary ingest** when the topic is load-bearing (customers, decisions, OKRs). Routine learnings may have 0-1 cascade touches.
+5. Commit:
    - To write: call `wiki-ingest` with `--vault`, `--source-type`, `--source-ref`, `--source-body`, and `--target <relative-path>`.
    - Then POST `/api/wiki/queue/<id>/process` with `{ingested:true, pagesWritten:[…], targetPath:'…', summary:'…'}`.
+     - `pagesWritten` should list ALL pages touched in step 4 + step 5 — primary + every cascade update.
    - To skip: POST `/api/wiki/queue/<id>/skip` with `{skipReason:'…'}`.
 
 ## Hard rules your LLM must honor
@@ -31,6 +38,7 @@ Claim the next pending queue item and get back the vault state your runtime's LL
 - **NEVER target a frozen folder** (`result.vaultContext.schemaSummary.frozenPaths`). The ingest call will reject these with HTTP 422.
 - **PREFER merging into an existing page** over creating a new one. Only create new when nothing fits.
 - **DO NOT re-justify wiki-worthiness** — the agent who queued the item already did (`result.item.reason`). Your job is classification, not gatekeeping. The exception is skip: if context reveals the item is a duplicate / low signal, skip with a `skipReason`.
+- **Cascade updates are cheap and load-bearing — do not skip them.** A wiki where every page is a disconnected snapshot is no better than chat history. Per Karpathy: *"updating cross-references, keeping summaries current, noting when new data contradicts old claims — humans abandon wikis because of this. LLMs don't get bored."* The compounding value of the wiki comes from these cascade touches, not from the primary write.
 
 ## Inputs