@walwal-harness/cli 7.1.25 → 7.1.26

package/CHANGELOG.md

@@ -31,6 +31,16 @@ docmeta:
 
 ## Unreleased
 
+## 7.1.26 — Lazy rule links + MCP steward (2026-05-27)
+
+### Added
+- COO planning can hire `support-support-mcp-registry-steward` to inventory Claude/Codex MCP capabilities, registration risk, credentials, and maintenance notes.
+- CXX convention/gotcha files now act as lazy-loading indexes that link to topic files such as `i18n-locale-hotfix.md`.
+
+### Changed
+- `migrate` preserves topic-specific convention/gotcha files and adds related links to matching CXX index files instead of merging or deleting them.
+- CXX and worker guidance now passes only relevant convention/gotcha links to workers, avoiding full-registry scans.
+
 ## 7.1.25 — Absolute Claude hook paths + Codex adapter docs (2026-05-26)
 
 ### Fixed

package/HR-Resource/cdo/SKILL.md

@@ -9,6 +9,10 @@ disable-model-invocation: false
 
 Own design strategy for the mission.
 
+## Lazy Rule Loading
+
+Before design work, read `.harness/conventions/shared.md`, `.harness/conventions/cdo.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/cdo.md`. Then follow only the related links in `cdo.md` files that match the mission topic. Worker briefs must pass the relevant links instead of asking workers to scan all rule files.
+
 ## Workflow
 
 1. Read CEO and COO mission context.

package/HR-Resource/ceo/SKILL.md

@@ -9,6 +9,15 @@ disable-model-invocation: false
 
 You are the only direct conversation channel with the Owner.
 
+## Lazy Rule Loading
+
+Before routing or accepting CXX work, enforce lazy loading:
+
+- CEO reads `.harness/conventions/shared.md`, `.harness/conventions/ceo.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/ceo.md`.
+- Each CXX reads its own `.harness/conventions/{cxx}.md` and `.harness/gotchas/{cxx}.md`, then follows only the related links in those files that match the mission topic.
+- Topic files such as `.harness/gotchas/i18n-locale-hotfix.md` remain separate. CXX index files carry links to them; they are not merged into one large file.
+- Workers receive the relevant CXX link set in their brief instead of scanning every convention/gotcha file.
+
 ## Mission Protocol
 
 1. Read the Owner request and decide whether brainstorming is needed or execution can start.

package/HR-Resource/coo/SKILL.md

@@ -9,11 +9,26 @@ disable-model-invocation: false
 
 Own mission planning, research, references, hypotheses, and goal fit.
 
+## Lazy Rule Loading
+
+Before planning, read `.harness/conventions/shared.md`, `.harness/conventions/coo.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/coo.md`. Then follow only the related links in `coo.md` files that match the mission topic. Worker briefs must pass the relevant links instead of asking workers to scan all rule files.
+
+## MCP Capability Scan
+
+During planning, COO must determine whether the active runtime exposes MCP servers, MCP tools, connector tools, or tool-discovery tools that can materially improve the mission. This is a planning input, not an implementation shortcut.
+
+- Before finalizing a plan, create a worker task for an MCP capability scan. Prefer `support-support-mcp-registry-steward` when available; otherwise hire the smallest worker that can inventory Claude/Codex MCP availability without inventing unavailable tools.
+- The worker must use only discovery mechanisms actually exposed in the current runtime, such as MCP resource/tool listing, connector search, or tool-discovery tools. Do not invent unavailable MCPs.
+- The inventory must classify each applicable MCP by purpose, required credentials or setup, read/write risk, expected value, and where it fits in the mission flow.
+- If no discovery mechanism is exposed, or no applicable MCP is available, record that explicitly in the worker report and proceed without MCP dependency.
+- COO may recommend MCP usage only when the worker report shows that the tool is available, applicable, and safer or more efficient than the non-MCP path.
+- COO must route execution of any MCP-dependent implementation, verification, or operational work to the responsible CXX and hired workers. COO does not call MCP tools to complete specialist deliverables.
+
 ## Workflow
 
 1. Read `.harness/documents/{mission_name}/ceo.md`.
 2. Record work in `.harness/documents/{mission_name}/coo.md`.
-3. Break the COO scope into worker tasks: research, planning, hypothesis validation, backtest design, documentation, or product direction.
+3. Break the COO scope into worker tasks: research, planning, MCP capability scan, hypothesis validation, backtest design, documentation, or product direction.
 4. Use the `harness-resource-manager` skill to check available workers for every task.
 5. Use the `harness-hiring` skill before assigning any task that has no hired worker. Do not complete that task yourself.
 6. Delegate all COO deliverables to hired workers in fresh sessions.
@@ -36,8 +51,9 @@ Required output sections:
 
 1. Worker Task Briefs — task, capability needed, selected worker or hiring request, acceptance criteria.
 2. Worker Evidence Manifest — worker name, report path, status.
-3. COO Decision — only decisions accepted from worker evidence.
-4. Next Handoff — next CXX, inputs, blockers.
-5. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
+3. MCP Capability Inventory — available/applicable MCPs, required setup, read/write risk, recommended use, or explicit `None`.
+4. COO Decision — only decisions accepted from worker evidence.
+5. Next Handoff — next CXX, inputs, blockers.
+6. Implementation Notes — in English, with `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`.
 
 Every COO worker brief must require the worker to append the same English `## Implementation Notes` block to the bottom of `.harness/documents/{mission_name}/coo/workers/{worker-name}.md`, covering risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.

package/HR-Resource/cqo/SKILL.md

@@ -9,6 +9,10 @@ disable-model-invocation: false
 
 Own quality, recurrence prevention, and archive eligibility.
 
+## Lazy Rule Loading
+
+Before quality work, read `.harness/conventions/shared.md`, `.harness/conventions/cqo.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/cqo.md`. Then follow only the related links in `cqo.md` files that match the mission topic, such as i18n, regression, accessibility, API, runtime, or incident links. Worker briefs must pass the relevant links instead of asking workers to scan all rule files.
+
 ## Workflow
 
 1. Read CEO and CTO mission context.

package/HR-Resource/cto/SKILL.md

@@ -9,6 +9,10 @@ disable-model-invocation: false
 
 Own engineering execution for the mission.
 
+## Lazy Rule Loading
+
+Before engineering work, read `.harness/conventions/shared.md`, `.harness/conventions/cto.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/cto.md`. Then follow only the related links in `cto.md` files that match the mission topic, such as i18n, auth, API, runtime, or platform links. Worker briefs must pass the relevant links instead of asking workers to scan all rule files.
+
 ## Workflow
 
 1. Read CEO, COO, and CDO mission documents.

package/HR-Resource/hiring/SKILL.md

@@ -26,7 +26,11 @@ Hire workers from `.harness/shared/HR-Resource/`.
 5. Update `.harness/shared/hr-roster.json` without deleting existing hired entries. Record `owner` as the owning CXX, `skillPath` as `.harness/shared/HR-Resource/{name}/SKILL.md`, and `skillPaths.claude` / `skillPaths.codex` as tool-specific hierarchical installed paths.
 6. The owning CXX must write worker reports under `.harness/documents/{mission}/{owning-cxx}/workers/{name}.md`. Do not write flat `.harness/documents/{mission}/workers/{name}.md` except when migrating legacy missions.
 7. Ask the `harness-resource-manager` skill to update trigger wording.
-8. Return worker name, owner, source skill path, installed paths, mission report path, invocation wording, and the mandatory report appendix below.
+8. Return worker name, owner, source skill path, installed paths, mission report path, invocation wording, related convention/gotcha links supplied by the owning CXX, and the mandatory report appendix below.
+
+## Worker Rule Links
+
+Every hired worker receives the owning CXX's relevant convention/gotcha links in the worker brief. Workers read those linked topic files only when they match the assigned task.
 
 ## Mandatory Worker Report Appendix
 

package/HR-Resource/index.json

@@ -1,7 +1,7 @@
 {
   "source": "/Users/ted/Downloads/agency-agents-main",
   "imported_at": "2026-05-11T08:05:46.803Z",
-  "count": 179,
+  "count": 180,
   "resources": [
     {
       "sourceRel": "academic/academic-anthropologist.md",
@@ -679,6 +679,10 @@
       "sourceRel": "support/support-infrastructure-maintainer.md",
       "skillName": "support-support-infrastructure-maintainer"
     },
+    {
+      "sourceRel": "support/support-mcp-registry-steward.md",
+      "skillName": "support-support-mcp-registry-steward"
+    },
     {
       "sourceRel": "support/support-legal-compliance-checker.md",
       "skillName": "support-support-legal-compliance-checker"

package/HR-Resource/ops/SKILL.md

@@ -9,6 +9,10 @@ disable-model-invocation: false
 
 Monitor the environments that make the mission runnable.
 
+## Lazy Rule Loading
+
+Before monitoring work, read `.harness/conventions/shared.md`, `.harness/conventions/ops.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/ops.md`. Then follow only the related links in `ops.md` files that match the mission topic, such as runtime, port, log, production, or incident links. Worker briefs must pass the relevant links instead of asking workers to scan all rule files.
+
 OPS owns three environment classes:
 
 - Build environment: command-based local execution such as `flutter run`, `npm run dev`, test watchers, local build scripts, and other foreground/background commands used by CXX workers.

package/HR-Resource/resource-manager/SKILL.md

@@ -16,15 +16,18 @@ Manage worker availability and invocation wording.
 - Candidate pool: `.harness/shared/HR-Resource/*/SKILL.md`
 - Installed hired workers: `.claude/skills/{owning-cxx}/{worker}/SKILL.md` and `.codex/skills/{owning-cxx}/{worker}/SKILL.md`
 - Mission worker reports: `.harness/documents/{mission}/{owning-cxx}/workers/{worker}.md`
+- Related convention/gotcha links: selected from `.harness/conventions/{owning-cxx}.md` and `.harness/gotchas/{owning-cxx}.md`
 
 ## Workflow
 
 1. Check whether the requester is a CXX. CEO cannot request specialist worker assignment directly.
 2. Check whether a suitable worker is already hired for that owning CXX.
-3. If hired, return the exact skill name, owning CXX, hierarchical installed paths, mission report path, and the mandatory `## Implementation Notes` report appendix requirement.
+3. If hired, return the exact skill name, owning CXX, hierarchical installed paths, relevant convention/gotcha links, mission report path, and the mandatory `## Implementation Notes` report appendix requirement.
 4. If not hired, suggest `.harness/shared/HR-Resource/` candidates and recommend the `harness-hiring` skill with `owning CXX` filled in.
 5. Keep aliases narrow enough to avoid accidental generic invocation.
 
 ## Mandatory Worker Report Appendix
 
+Every worker assignment must include only the convention/gotcha links relevant to the assigned task. The owning CXX selects those links from its CXX index files.
+
 Every worker assignment must require the worker to append an English `## Implementation Notes` section with these subsections: `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`. The appendix must cover risks, self-corrections, chosen direction, and unresolved questions. Use `None` for empty subsections.

package/HR-Resource/support-support-mcp-registry-steward/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: support-support-mcp-registry-steward
+description: "MCP registry steward for Claude and Codex. Inventories available MCP servers/tools, recommends safe registration, and maintains project MCP usage records without inventing unavailable capabilities."
+model: sonnet
+disable-model-invocation: false
+---
+
+# MCP Registry Steward
+
+You manage Model Context Protocol capability discovery, registration guidance, and maintenance for Claude and Codex runtimes.
+
+## Mission
+
+Help COO and the responsible CXX decide whether MCP tools should be used for a mission, and keep the decision auditable.
+
+## Scope
+
+- Inventory MCP servers, MCP tools, connector tools, and tool-discovery mechanisms actually exposed in the current runtime.
+- Compare Claude and Codex availability separately. A tool available in one runtime is not automatically available in the other.
+- Recommend registration only when the MCP is useful, credentials/setup are clear, and read/write risk is acceptable.
+- Maintain a project MCP capability record for future missions.
+- Produce handoff notes for the CXX or worker that will actually use the MCP.
+
+## Discovery Rules
+
+1. Use only discovery mechanisms exposed in the active runtime.
+2. Do not invent MCP servers, tools, connector names, credentials, or config paths.
+3. If no discovery mechanism is available, record `None` with the exact reason.
+4. Treat write-capable MCPs as higher risk than read-only MCPs.
+5. Never edit global Claude, Codex, or user-level MCP configuration without explicit Owner approval.
+6. Prefer project-local documentation and registration instructions over hidden global state.
+
+## Claude Checks
+
+- Inspect project and user-visible Claude MCP configuration only when accessible.
+- Record server name, command, args, required environment variables, and whether tools are read-only or write-capable.
+- If Claude exposes MCP tool namespaces in the active session, list the tool names used for discovery.
+- If Playwright MCP is needed, verify whether project guidance already references it and whether setup instructions are present.
+
+## Codex Checks
+
+- Inspect Codex-visible tool discovery, MCP resources, connector tools, and local project instructions.
+- Record whether MCP discovery is exposed directly, only through connector/tool search, or not exposed.
+- If a Claude MCP is not available to Codex, mark it as Claude-only until Codex registration is confirmed.
+- Do not assume `.claude` MCP configuration applies to Codex.
+
+## Registration Review
+
+For every proposed MCP registration, document:
+
+- Purpose and mission fit.
+- Runtime target: Claude, Codex, or both.
+- Required credentials, environment variables, binaries, and network access.
+- Read/write risk and blast radius.
+- Suggested project-local docs or setup command.
+- Validation command or manual smoke test.
+- Rollback or disable procedure.
+
+## Maintenance Record
+
+Write or update a worker report under:
+
+`.harness/documents/{mission}/coo/workers/support-support-mcp-registry-steward.md`
+
+Required sections:
+
+1. `## MCP Capability Inventory`
+2. `## Claude Runtime`
+3. `## Codex Runtime`
+4. `## Registration Candidates`
+5. `## Risk Review`
+6. `## Maintenance Plan`
+7. `## Recommended Mission Use`
+8. `## Implementation Notes`
+
+Use `None` for empty sections. Include exact evidence paths or tool names for every claim.
+

package/README.md

@@ -216,6 +216,8 @@ Hourly autonomous wake:
 - Each wake tick prompts CEO to convene CXX + OPS, collect progress and decisions, dispatch the next action without asking Owner, and require CQO/OPS verification until the active goal works.
 - `npx @walwal-harness/cli migrate` refreshes package-owned runtime scripts, so existing projects receive wake prompt updates without a full re-init.
 - In Codex, `.codex/skills/**/SKILL.md` files are the runtime protocol. `.codex/agents/` is not required; Codex should manually read the relevant skill if it is not auto-listed.
+- Convention/gotcha topic files lazy-load through CXX index links: `migrate` preserves files such as `.harness/gotchas/i18n-locale-hotfix.md` and links them from relevant CXX files like `cto.md` and `cqo.md`.
+- COO can use `support-support-mcp-registry-steward` to inventory Claude/Codex MCP capabilities, registration risk, credentials, and maintenance notes before recommending MCP use.
 
 ---
 
@@ -227,8 +229,8 @@ Hourly autonomous wake:
 | `.harness/documents/goal-{index}-{name}/submission-{index}-{name}/` | Additional requirement under the active goal |
 | `.harness/documents/goal-{index}-{name}/hotfix-{index}-{name}/` | Emergency fix under the active goal |
 | `.harness/documents/{goal-or-child-mission}/{cxx}/workers/` | Worker reports owned by that CXX |
-| `.harness/conventions/` | Durable rules (CQO writes, survives missions) |
-| `.harness/gotchas/` | Recurrence-prevention records (CQO registers per hot-fix) |
+| `.harness/conventions/` | Durable rules and CXX lazy-loading indexes |
+| `.harness/gotchas/` | Recurrence-prevention records and CXX lazy-loading indexes |
 | `.harness/shared/HR-Resource/` | Hireable worker skill pool |
 | `.harness/archive/` | CQO-approved completed missions (immutable) |
 | `.harness/logs/YYYY-MM-DD/` | OPS exception logs |

package/assets/templates/AGENTS.md.template

@@ -144,6 +144,7 @@ Note: A docmeta skip decision on harness documents (ceo.md, cto.md, cqo.md, work
 8. **No CXX self-execution** — CXX agents coordinate and manage only. A CXX that produces deliverables without matching worker records has violated its scope. CEO must reject such reports.
 9. **No verdict without worker evidence** — CQO cannot issue ACCEPTED/REJECTED without a Worker Evidence Manifest referencing at least one evaluator worker. Self-inspection by CQO is not valid evidence.
 10. **Hierarchical worker ownership** — Hired workers are installed under `.claude/skills/{owning-cxx}/{worker}/` and `.codex/skills/{owning-cxx}/{worker}/`; mission worker reports live under `.harness/documents/{goal-or-child-mission}/{owning-cxx}/workers/`. Flat `{mission}/workers/` reports are legacy and signal an ownership violation unless explicitly migrated.
+11. **Lazy convention/gotcha loading** — CXX roles read `.harness/conventions/shared.md`, `.harness/conventions/{cxx}.md`, `.harness/gotchas/shared.md`, and `.harness/gotchas/{cxx}.md`, then follow only the related topic links listed in those CXX files. Workers read only the related links supplied by their owning CXX.
 11. **Implementation Notes required** — `ceo.md`, every `{cxx}.md`, and every worker report must end with one English `## Implementation Notes` section containing `Design Decisions`, `Deviations`, `Tradeoffs`, and `Open Questions`. Use `None` for empty subsections. Do not create a separate sidecar notes file; the notes belong at the bottom of the same role or worker report that produced the decision/evidence.
 12. **Owner is final acceptance only** — Owner is not a tester or QA substitute. CEO/CXX must not report "done, please check" until worker-backed verification proves the goal can be completed. Use unit tests, E2E, Playwright, test accounts, seeded data, build/run checks, logs, and CQO evidence before requesting Owner acceptance.
 13. **OPS watches CQO verification** — For runnable products, CQO PASS is invalid unless OPS has monitored the verification runtime or documented why OPS watch is not applicable. Open OPS incidents, missing runtime mapping, required log gaps, service down, health mismatch, or an unmonitored tested service block Owner acceptance.

package/assets/templates/config.json

@@ -262,7 +262,7 @@
     "actions": ".harness/actions",
     "archive": ".harness/archive",
     "gotchas": ".harness/gotchas",
-    "conventions": "CONVENTIONS.md",
+    "conventions": ".harness/conventions",
     "progress_state": ".harness/progress.json",
     "progress_log": ".harness/progress.log"
   },
@@ -284,16 +284,18 @@
     "statuses": ["start", "complete", "fail", "pass", "skip", "warn"]
   },
   "conventions": {
-    "comment": "House-style registry. 루트 CONVENTIONS.md(사용자 자유 기술) + .harness/conventions/<scope>.md(Dispatcher 자동 누적). 모든 에이전트가 세션 시작 시 읽고 적용한다. Gotcha 의 긍정 대칭판.",
+    "comment": "House-style registry. CXX files act as lazy-loading indexes that link to topic-specific convention/gotcha documents.",
     "root_file": "CONVENTIONS.md",
     "scoped_dir": ".harness/conventions/",
-    "scopes": ["shared", "planner", "generator-backend", "generator-frontend", "evaluator-code-quality", "evaluator-functional", "evaluator-visual"],
+    "gotcha_scoped_dir": ".harness/gotchas/",
+    "cxx_scopes": ["ceo", "coo", "cdo", "cto", "cqo", "ops", "hiring", "resource-manager", "brick-office"],
     "entry_id_prefix": "C",
-    "read_by": "all_agents",
-    "read_order": ["CONVENTIONS.md", ".harness/conventions/shared.md", ".harness/conventions/<self>.md", ".harness/gotchas/<self>.md", ".harness/memory.md"],
-    "conflict_priority": "self > shared > root",
-    "write_by": "dispatcher (auto-append C-NNN) or user_only (manual edit)",
-    "read_timing": "session_start",
+    "read_by": "CEO, CXX, and hired workers",
+    "cxx_read_order": [".harness/conventions/shared.md", ".harness/conventions/<cxx>.md", "follow relevant links in <cxx>.md", ".harness/gotchas/shared.md", ".harness/gotchas/<cxx>.md", "follow relevant links in <cxx>.md", ".harness/memory.md"],
+    "worker_read_order": ["links explicitly provided by owning CXX in the worker brief"],
+    "conflict_priority": "linked topic > owning-cxx > shared > memory > root",
+    "write_by": "CQO/gotcha-register, CXX, or Owner-approved manual edit",
+    "read_timing": "before each role or worker starts mission work",
     "preserve_on_postinstall": true
   },
   "recommended_skills": {

package/bin/init.js

@@ -527,7 +527,6 @@ function scaffoldHarness() {
       copyFile(srcPath, destPath);
     }
   }
-
   // Copy conventions — mirror gotchas preservation: never overwrite files with
   // accumulated `### [C-NNN]` entries.
   const conventionsSrc = path.join(PKG_ROOT, 'conventions');
@@ -550,7 +549,6 @@ function scaffoldHarness() {
       copyFile(srcPath, destPath);
     }
   }
-
   // First-install migration: extract Convention/Gotcha-shaped sections from
   // existing CLAUDE.md / AGENTS.md and copy into the hierarchical stores.
   if (isFirstInstall) {
@@ -1265,6 +1263,7 @@ function detectMigrationNeeded() {
     memoryMissingSystemEntries: [],
     gotchaMissingEntries: {},   // { "<filename>": [G-IDs...] }
     conventionMissingEntries: {}, // { "<filename>": [C-IDs...] }
+    ruleRegistryLinks: [],
     bundleVersionStale: null,    // { current, installed }
   };
 
@@ -1418,6 +1417,7 @@ function detectMigrationNeeded() {
       flags.memoryMissingSystemEntries = tplEntryIds.filter((id) => !userEntryIds.has(id));
     } catch {}
   }
+  flags.ruleRegistryLinks = detectRuleRegistryLinks();
   return flags;
 }
 
@@ -1479,6 +1479,136 @@ function extractConventionEntryBlock(md, id) {
   return m ? m[1].trimEnd() : null;
 }
 
+const CANONICAL_RULE_SCOPES = new Set([
+  'README.md',
+  'shared.md',
+  'ceo.md',
+  'coo.md',
+  'cdo.md',
+  'cto.md',
+  'cqo.md',
+  'ops.md',
+  'hiring.md',
+  'resource-manager.md',
+  'brick-office.md',
+]);
+
+const CXX_RULE_LINK_MARKER = '<!-- walwal-harness:related-rule-links -->';
+
+function collectKnownWorkerNames() {
+  const names = new Set();
+  const hrRoot = path.join(HARNESS_DIR, 'shared', 'HR-Resource');
+  if (fs.existsSync(hrRoot)) {
+    for (const entry of fs.readdirSync(hrRoot, { withFileTypes: true })) {
+      if (entry.isDirectory()) names.add(entry.name);
+    }
+  }
+  const rosterPath = path.join(HARNESS_DIR, 'shared', 'hr-roster.json');
+  if (fs.existsSync(rosterPath)) {
+    try {
+      const roster = JSON.parse(fs.readFileSync(rosterPath, 'utf8'));
+      for (const entry of Array.isArray(roster.hired) ? roster.hired : []) {
+        if (entry?.worker) names.add(entry.worker);
+      }
+    } catch {}
+  }
+  return names;
+}
+
+function classifyRuleRegistryFile(file, kind, knownWorkers, body = '') {
+  const base = path.basename(file, '.md');
+  const ext = path.extname(file);
+  if (ext !== '.md') return null;
+  if (LEGACY_V7_FILE_OWNER[file]) {
+    return { targets: [path.basename(LEGACY_V7_FILE_OWNER[file], '.md')], reason: 'legacy-role' };
+  }
+  const haystack = `${base}\n${body}`.toLowerCase();
+  const targets = new Set();
+
+  if (/\b(i18n|intl|locale|localization|translation|translate|multilingual|language|aria|rtl|l10n)\b/.test(haystack)) {
+    targets.add('cto');
+    targets.add('cqo');
+  }
+  if (/\b(ui|ux|design|brand|visual|layout|accessibility|a11y|responsive|color|typography)\b/.test(haystack)) {
+    targets.add('cdo');
+    targets.add('cqo');
+  }
+  if (/\b(api|backend|frontend|database|schema|auth|flutter|react|next|build|deploy|port|integration|migration)\b/.test(haystack)) {
+    targets.add('cto');
+  }
+  if (/\b(test|qa|quality|regression|e2e|playwright|bug|hotfix|incident|failure|risk)\b/.test(haystack)) {
+    targets.add('cqo');
+  }
+  if (/\b(ops|runtime|server|log|monitor|health|production|docker|port)\b/.test(haystack)) {
+    targets.add('ops');
+  }
+  if (/\b(plan|research|market|hypothesis|requirement|product|scope)\b/.test(haystack)) {
+    targets.add('coo');
+  }
+  if (knownWorkers.has(base)) {
+    return { targets: ['coo', 'cto', 'cqo', 'ops'].filter(Boolean), reason: 'worker-topic' };
+  }
+  if (!targets.size) targets.add('shared');
+  return { targets: [...targets], reason: targets.has('shared') ? 'unclassified-topic' : 'topic-keywords' };
+}
+
+function detectRuleRegistryLinks() {
+  const links = [];
+  const knownWorkers = collectKnownWorkerNames();
+  for (const kind of ['conventions', 'gotchas']) {
+    const root = path.join(HARNESS_DIR, kind);
+    if (!fs.existsSync(root)) continue;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (entry.isDirectory()) continue;
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      if (CANONICAL_RULE_SCOPES.has(entry.name)) continue;
+      const sourcePath = path.join(root, entry.name);
+      const body = fs.existsSync(sourcePath) ? fs.readFileSync(sourcePath, 'utf8') : '';
+      const classification = classifyRuleRegistryFile(entry.name, kind, knownWorkers, body);
+      if (!classification) continue;
+      links.push({
+        kind,
+        sourceRel: entry.name,
+        targets: classification.targets,
+        reason: classification.reason,
+      });
+    }
+  }
+  return links.filter((item) => item.targets.some((target) => !ruleRegistryLinkExists(item.kind, target, item.sourceRel)));
+}
+
+function ruleRegistryLinkExists(kind, target, sourceRel) {
+  const targetPath = path.join(HARNESS_DIR, kind, `${target}.md`);
+  if (!fs.existsSync(targetPath)) return false;
+  return fs.readFileSync(targetPath, 'utf8').includes(`](${sourceRel})`);
+}
+
+function updateRuleRegistryLinks(links, { dryRun, backupDir }) {
+  if (!links.length) return;
+  for (const item of links) {
+    const root = path.join(HARNESS_DIR, item.kind);
+    const sourcePath = path.join(root, item.sourceRel);
+    if (!fs.existsSync(sourcePath)) continue;
+    for (const target of item.targets) {
+      const targetPath = path.join(root, `${target}.md`);
+      if (path.resolve(sourcePath) === path.resolve(targetPath) || ruleRegistryLinkExists(item.kind, target, item.sourceRel)) continue;
+      log(`  ${item.kind}/${target}.md: link ${item.sourceRel} (${item.reason})`);
+      if (dryRun) continue;
+      ensureDir(path.dirname(targetPath));
+      const existing = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, 'utf8').trimEnd() : `# ${target.toUpperCase()} ${item.kind === 'gotchas' ? 'Gotchas' : 'Conventions'}`;
+      if (fs.existsSync(targetPath)) {
+        const backupTarget = path.join(backupDir, `${item.kind}-${target}.md`);
+        fs.copyFileSync(targetPath, backupTarget);
+      }
+      const header = existing.includes(CXX_RULE_LINK_MARKER)
+        ? ''
+        : `\n\n## Related ${item.kind === 'gotchas' ? 'Gotcha' : 'Convention'} Links\n${CXX_RULE_LINK_MARKER}\n`;
+      const line = `- [${item.sourceRel}](${item.sourceRel}) — ${item.reason}`;
+      fs.writeFileSync(targetPath, `${existing}${header}${header ? '' : '\n'}${line}\n`);
+    }
+  }
+}
+
 function showMigrationProposal(flags) {
   console.log('');
   console.log('╔══════════════════════════════════════════════════════════╗');
@@ -1544,6 +1674,12 @@ function showMigrationProposal(flags) {
       console.log(`    ${file}: [${ids.join(', ')}]`);
     }
   }
+  if (flags.ruleRegistryLinks && flags.ruleRegistryLinks.length) {
+    console.log('  • conventions/gotchas: topic 파일을 CXX index 에 link 하여 lazy-load 가능하게 보강');
+    for (const item of flags.ruleRegistryLinks) {
+      console.log(`    ${item.kind}/${item.sourceRel} → ${item.targets.map((t) => `${item.kind}/${t}.md`).join(', ')} (${item.reason})`);
+    }
+  }
   if (flags.bundleVersionStale) {
     const { current, installed } = flags.bundleVersionStale;
     console.log(`  • bundle: ${installed ?? '(없음)'} → ${current} 스탬프 갱신 필요`);
@@ -1572,6 +1708,7 @@ function runMigrate(opts = {}) {
   const runtimeScriptsAlwaysRefresh = true;
   const gotchaMissingTotal = Object.values(flags.gotchaMissingEntries || {}).reduce((n, a) => n + a.length, 0);
   const conventionMissingTotal = Object.values(flags.conventionMissingEntries || {}).reduce((n, a) => n + a.length, 0);
+  const ruleRegistryLinkTotal = (flags.ruleRegistryLinks || []).length;
   if (
     !flags.progressV3toV4 &&
     !flags.progressLegacyRouting &&
@@ -1588,6 +1725,7 @@ function runMigrate(opts = {}) {
     (!flags.memoryMissingSystemEntries || flags.memoryMissingSystemEntries.length === 0) &&
     gotchaMissingTotal === 0 &&
     conventionMissingTotal === 0 &&
+    ruleRegistryLinkTotal === 0 &&
     !flags.bundleVersionStale &&
     !runtimeScriptsAlwaysRefresh
   ) {
@@ -1608,6 +1746,7 @@ function runMigrate(opts = {}) {
   // Runtime scripts are package-owned. Migrate must refresh them so existing
   // projects receive wake/meeting/OPS fixes without requiring a full init.
   refreshScriptsForMigrate({ dryRun, backupDir });
+  updateRuleRegistryLinks(flags.ruleRegistryLinks || [], { dryRun, backupDir });
 
   // 1. progress.json
   const progressPath = path.join(HARNESS_DIR, 'progress.json');

package/conventions/README.md

@@ -15,4 +15,6 @@ Only company-level roles are provided by default:
 - `resource-manager.md`
 - `brick-office.md`
 
-Specialist worker conventions are not bundled here. They are created or promoted later through hiring, mission work, and CQO memory hygiene.
+Topic-specific convention files may use descriptive names such as `i18n-locale.md`.
+
+CXX files such as `cto.md` and `cqo.md` act as lazy-loading indexes. Add links there when a topic file applies to that CXX.

package/conventions/coo.md

@@ -2,5 +2,6 @@
 
 - COO owns planning, research, service direction, reference models, and hypothesis validation.
 - COO records decisions in `.harness/documents/{mission_name}/coo.md`.
-- COO hires researchers, product planners, junior experiment developers, and documentation workers before delegating specialist work.
+- COO hires researchers, product planners, MCP registry stewards/capability scanners, junior experiment developers, and documentation workers before delegating specialist work.
+- COO planning must include an MCP Capability Inventory: available/applicable MCPs, required setup, read/write risk, recommended mission use, or explicit `None` when discovery is unavailable or no MCP applies.
 - COO reports mission fit, evidence, rejected options, and recommended next CXX to CEO.

package/gotchas/README.md

@@ -15,4 +15,6 @@ Only company-level roles are provided by default:
 - `resource-manager.md`
 - `brick-office.md`
 
-Specialist worker gotchas are not bundled. CQO promotes recurring verified failures into this store as the company learns.
+Topic-specific gotcha files may use descriptive names such as `i18n-locale-hotfix.md`.
+
+CXX files such as `cto.md` and `cqo.md` act as lazy-loading indexes. Add links there when a topic file applies to that CXX.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "7.1.25",
+  "version": "7.1.26",
   "description": "Company-style AI agent harness for Claude and Codex. Installs commands, CXX agents, skills, HR-Resource hiring pool, and project-local .harness runtime state.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-gotcha-register.sh

@@ -70,6 +70,7 @@ TODAY="$(date +%Y-%m-%d)"
 register_one() {
   local target="$1" rule_id="$2" title="$3" wrong="$4" right="$5" why="$6" scope="$7" source="$8"
   local file="$GOTCHAS_DIR/${target}.md"
+  mkdir -p "$(dirname "$file")"
 
   # Ensure file exists with header
   if [ ! -f "$file" ]; then
@@ -184,6 +185,7 @@ register_convention_one() {
   local scope="$1" rule_id="$2" title="$3" rule="$4" why="$5" source="$6"
   mkdir -p "$CONVENTIONS_DIR"
   local file="$CONVENTIONS_DIR/${scope}.md"
+  mkdir -p "$(dirname "$file")"
 
   if [ ! -f "$file" ]; then
     cat > "$file" <<EOF