Add new msdmd application skills and canon; update docs and indexes

AGENTS.md

@@ -38,15 +38,19 @@ the skill. Treat it as the public contract.
 2. Parse the YAML frontmatter; index by `name` and `description`.
 3. When a user request matches the triggers in a `description`, read
    that skill's full `SKILL.md` before acting.
-4. Some skills (currently `msdmd`, `doc-build`, `cap-build`, `test-build`,
-   `meta-module-build`, `risk-boundary-build`, `ratios`, and `manifest`)
-   define metadata blocks that other modules declare inside their own source
-   files. Other skills (currently `canon`, `visitor-intro`, and
-   `char-compress`) are purely procedural and define no block.
+4. Some skills (currently `msdmd`, `doc-build`, `cap-build`, `deps-build`,
+   `owner-build`, `test-build`, `meta-module-build`, `risk-boundary-build`,
+   and `ratios`) define metadata blocks that other modules declare inside their own source files. Other
+   skills (currently `canon`, `char-compress`, `manifest`, and `visitor-intro`) are procedural and
+   define no block.
 
 A machine-readable index is also available at `skills.json` if you
 prefer not to walk the tree.
 
+This repo ships the universal msdmd parser implementations plus skill
+specifications. Treat per-skill runner sections as contracts for consuming
+repos unless the skill directory includes an actual helper script.
+
 ## How to install this lib into another repo
 
 The canonical install path inside a consuming repo is:

CLAUDE.md

@@ -31,21 +31,28 @@ tools/*.py             # pure-stdlib helper scripts
 
 | Skill | Kind | Depends on | Purpose |
 |---|---|---|---|
-| `msdmd/` | metadata-block | — | Module Self-Declared Metadata Markdown. Foundational comment-block syntax, parser contract, runner protocol, reserved fields, visible gap reporting, reference parsers. |
-| `doc-build/` | metadata-block | `msdmd` | Documentation coverage through `DOCS` blocks; verifies paths and anchors; reports stale docs and visible gaps. |
-| `cap-build/` | metadata-block | `msdmd` | Capability inventory through `CAPABILITIES` blocks; verifies exposed surfaces and duplicates. |
-| `test-build/` | metadata-block | `msdmd` | Contract tests through `CONTRACTS` blocks in source modules; runner discovers contracts and reports gaps. |
-| `meta-module-build/` | metadata-block | `msdmd` | Metadata-first module scaffolding through `MODULE_BUILD`; surfaces, boundaries, tests, rollout, rollback. |
-| `risk-boundary-build/` | metadata-block | `msdmd`, `meta-module-build` | Runtime boundaries through `BOUNDARIES`; auth, storage, network, user-data, admin, operational effects. |
-| `ratios/` | metadata-block | `msdmd` | Module composition ratios; comments/code, imports/exports, calls/definitions; recompute and drift-check. |
-| `canon/` | procedural | — | Canonical-source and doctrine maintenance; separates declared, implemented, repo-local, inferred, desired, and `hmmm`. |
-| `visitor-intro/` | procedural | — | Newcomer orientation for any org repo without inventing org-level facts. |
-| `char-compress/` | procedural | — | Bone/flesh context compression. Carry flesh, frozen bones, transforms, and `hmmm`; drop only safely regenerable scaffold. No UCNS-A theorem transfer; no edcmbone metric claim. |
-| `manifest/` | metadata-block | `msdmd` | Living-spec generator; derives repo facts from pyproject/tree and splices a machine-owned block into `CLAUDE.md` in consuming repos. |
-
-## Skill anatomy
-
-Every skill directory contains at least `SKILL.md` with YAML frontmatter:
+| `msdmd/` | metadata-block | — | Foundational convention. Defines the comment-block syntax, the parser contract, the runner protocol, reserved field names, and the visible gap-reporting requirement. Ships reference parsers under `msdmd/parsers/`. Every metadata-block skill builds on it. |
+| `doc-build/` | metadata-block | `msdmd` | Self-declaring documentation coverage. Modules declare `# === DOCS ===` blocks; a runner verifies documentation paths/anchors and reports stale docs plus visible gaps. |
+| `cap-build/` | metadata-block | `msdmd` | Self-declaring capability inventory. Modules declare `# === CAPABILITIES ===` blocks; a runner builds a capability map and verifies exposed surfaces. |
+| `deps-build/` | metadata-block | `msdmd` | Self-declaring dependency topology. Modules declare `# === DEPENDENCIES ===` blocks; a runner builds import/call/capability graphs and reports unresolved edges, cycles, and visible gaps. |
+| `owner-build/` | metadata-block | `msdmd`, `risk-boundary-build` | Self-declaring module stewardship. Modules declare `# === OWNERS ===` blocks; a runner reports unowned modules, unresolved owners, and review coverage gaps. |
+| `test-build/` | metadata-block | `msdmd` | Self-declaring contract tests. Each module declares a `# === CONTRACTS ===` block; a runner discovers and executes the referenced test functions and reports per-contract status plus modules with no CONTRACTS as coverage gaps. |
+| `meta-module-build/` | metadata-block | `msdmd` | Metadata-first module scaffolding. Each module declares a `# === MODULE_BUILD ===` block (manifest: surfaces, boundaries, tests, rollout, rollback) before implementation. New module work in any org repo is expected to start here. |
+| `risk-boundary-build/` | metadata-block | `msdmd`, `meta-module-build` | Runtime risk and permission boundaries. Existing modules declare `# === BOUNDARIES ===` blocks for auth, storage, network, user-data, admin, and operational effects. |
+| `ratios/` | metadata-block | `msdmd` | Self-declaring module composition ratios. Each module records `loc_comments`, `imports_exports`, and `calls_definitions` in bookend `# === RATIOS ===` blocks; a runner recomputes values, fails on drift, and reports visible gaps. |
+| `canon/` | procedural | — | Canonical-source and doctrine maintenance. Helps agents distinguish source-backed canon, proposed canon, repo-local practice, and `hmmm`. No metadata block. |
+| `visitor-intro/` | procedural | — | Onboarding tour. Lets any agent give a coherent, repo-aware orientation to newcomers at any org repo without inventing org-level facts. No metadata block. |
+
+---
+
+## Anatomy of a skill
+
+Every skill is a directory at the repo root containing **at least a `SKILL.md`**. Optional
+supporting files (parsers, executors, examples) live alongside it.
+
+### SKILL.md frontmatter
+
+`SKILL.md` opens with YAML frontmatter:
 
 ```yaml
 ---
@@ -58,8 +65,13 @@ The `description` is the loading contract. Keep it specific. List triggers. Do n
 
 Two kinds:
 
-- **Metadata-block skills:** define a block schema and executor pattern over `msdmd` parser output.
-- **Procedural skills:** define agent behavior, doctrine, output shape, and hmmm; no block schema required.
+- **Metadata-block skills** apply the msdmd convention to a named block (`DOCS`, `CAPABILITIES`, `DEPENDENCIES`, `OWNERS`, `CONTRACTS`,
+  `MODULE_BUILD`, `BOUNDARIES`, `RATIOS`, …). They define a field schema, a thin executor that consumes parsed
+  entries, and a runner that emits a visible gap list. `test-build/` is the canonical worked
+  example; `doc-build/`, `cap-build/`, `deps-build/`, `owner-build/`,
+  `risk-boundary-build/`, and `ratios/` define adjacent applications. `msdmd` itself is the foundation.
+- **Procedural skills** define an agent behaviour with no msdmd block. They state the doctrine
+  they enforce and the output shape they produce. `canon/` and `visitor-intro/` are the examples.
 
 ## msdmd block syntax
 
@@ -113,6 +125,12 @@ Tool boundaries:
 - `char_compress_check.py` runs preservation fixtures from `char-compress/fixtures.json`; it is not a full natural-language codec.
 - `propagate_skills.py` copies canonical skill directories into a checked-out target repo; it does not commit, push, open pull requests, or contact GitHub.
 
+- The parsers are reference implementations; this repo does not ship a test suite for them.
+- Runner sections in application SKILLs are contracts or patterns for *consuming* repos to
+  implement against their own source trees, not scripts that live or run here unless the skill
+  directory includes a helper file.
+- Validation here is editorial: keep `SKILL.md` frontmatter accurate, keep `skills.json` and the
+  README table in sync with the directories present, and keep the parsers stdlib-only.
 ## Consumption and propagation
 
 - Canonical install path inside consuming repos: `.agents/skills/<skill-name>/`.

ORG_DISTRIBUTION.md

@@ -20,6 +20,8 @@ Propagation PRs should cite this repository and the source commit SHA.
 * `msdmd/` — Module Self-Declared Metadata Markdown
 * `doc-build/` — documentation coverage metadata blocks
 * `cap-build/` — capability inventory metadata blocks
+* `deps-build/` — dependency topology metadata blocks
+* `owner-build/` — module stewardship metadata blocks
 * `test-build/` — contract-test metadata blocks
 * `meta-module-build/` — metadata-first module scaffolding
 * `risk-boundary-build/` — runtime risk and permission boundary metadata blocks

README.md

@@ -22,6 +22,8 @@ Agents consuming this lib should start at
 | [`msdmd/`](msdmd/SKILL.md) | The foundational convention. Defines the block syntax, parser contract, and visibility (gap-reporting) requirement. Every metadata-block skill in this lib depends on it. |
 | [`doc-build/`](doc-build/SKILL.md) | Applies msdmd → documentation coverage. Modules declare `# === DOCS ===` blocks; a runner verifies documentation paths and anchors, reports stale docs, and surfaces visible gaps. |
 | [`cap-build/`](cap-build/SKILL.md) | Applies msdmd → capability inventory. Modules declare `# === CAPABILITIES ===` blocks; a runner builds a capability map and verifies exposed surfaces. |
+| [`deps-build/`](deps-build/SKILL.md) | Applies msdmd → dependency topology. Modules declare `# === DEPENDENCIES ===` blocks; a runner builds import/call/capability graphs, detects unresolved edges, and reports cycles. |
+| [`owner-build/`](owner-build/SKILL.md) | Applies msdmd → module stewardship. Modules declare `# === OWNERS ===` blocks; a runner reports unowned modules, unresolved owners, and review coverage gaps. |
 | [`test-build/`](test-build/SKILL.md) | Applies msdmd → contract test runner. Each module declares its test contracts in a `# === CONTRACTS ===` block; the runner walks the tree, parses, runs them, and reports per-contract status plus visible coverage gaps. |
 | [`meta-module-build/`](meta-module-build/SKILL.md) | Applies msdmd → metadata-first module scaffolding. Each module declares its build manifest in a `# === MODULE_BUILD ===` block before implementation drifts into unscoped patches. |
 | [`risk-boundary-build/`](risk-boundary-build/SKILL.md) | Applies msdmd → runtime boundary declarations. Modules declare `# === BOUNDARIES ===` blocks for auth, storage, network, user-data, admin, and operational effects. |
@@ -50,6 +52,11 @@ char-compress runner executes preservation fixtures for negation, quantifier,
 order, values, statuses, secrets, `hmmm`, and no UCNS-A / edcmbone status
 leakage.
 
+|∆|Implementation status: this repo ships the universal msdmd parsers and skill
+specifications. Most application skills define runner contracts for consuming
+repos; they do not ship standalone executors here unless a helper file exists
+in that skill directory.|∆|
+
 ## The core idea
 
 Most "keep docs/tests/configs in sync with code" attempts rot because the
@@ -89,14 +96,15 @@ authoritative spec.
 Skills come in two kinds. Pick the right one for what you're adding.
 
 **Metadata-block skills** apply the `msdmd` convention to a new block
-name (`doc-build`, `cap-build`, `test-build`, `meta-module-build`, `risk-boundary-build`, `ratios` are the existing examples).
+name (`doc-build`, `cap-build`, `deps-build`, `owner-build`, `test-build`, `meta-module-build`, `risk-boundary-build`, `ratios` are the existing examples).
 To add one:
 
 1. Pick a `<BLOCK_NAME>` (e.g. `DOCS`, `CAPABILITIES`, `OWNERS`).
 2. Decide the field schema (which fields are required, which optional).
-3. Write a thin executor that takes parsed entries from
-   `msdmd/parsers/universal.py` and does something with them.
-4. Author a `SKILL.md` that documents the convention and the executor.
+3. Specify the runner/executor contract, or write a thin executor that takes
+   parsed entries from `msdmd/parsers/universal.py` and does something with
+   them.
+4. Author a `SKILL.md` that documents the convention and runner behavior.
 
 `test-build/` is the canonical worked example.
 

cap-build/SKILL.md

@@ -9,6 +9,10 @@ description: Self-declaring capability inventory built on msdmd. Each module dec
 agents and humans a source-backed inventory of what modules can do, where
 those capabilities are exposed, and which boundaries they cross.
 
+Implementation status: this skill defines the `CAPABILITIES` block and runner
+contract. This repo does not currently ship a CAPABILITIES runner script;
+consuming repos should implement the contract below against their own surfaces.
+
 Read `msdmd/SKILL.md` first if you have not. The block syntax, parser
 contract, and visible gap rule are inherited.
 

deps-build/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: deps-build
+description: Self-declaring dependency topology built on msdmd. Each module declares dependency edges it owns in a `# === DEPENDENCIES ===` block; a runner builds an import/call/capability graph, detects unresolved edges and cycles, and surfaces visible dependency coverage gaps. Load this when declaring module dependencies, auditing architecture drift, checking graph cycles, or wiring dependency topology checks into CI.
+---
+
+# deps-build — Dependency topology on msdmd
+
+`deps-build` is an application of [msdmd](../msdmd/SKILL.md). It makes a
+module's dependency edges visible beside the code that creates them, so
+architecture drift becomes inspectable instead of hidden in imports.
+
+Implementation status: this skill defines the `DEPENDENCIES` block and runner
+contract. This repo does not currently ship a DEPENDENCIES graph runner;
+consuming repos should implement the contract below with local resolvers.
+
+Read `msdmd/SKILL.md` first if you have not. The block syntax, parser
+contract, and visible gap rule are inherited.
+
+## The block
+
+```python
+# === DEPENDENCIES ===
+# id: chat_route_dependency_edges
+#   summary: chat API route depends on auth context and chat repository
+#   imports: auth.user_context, repositories.chat
+#   calls: ChatRepository.get_by_owner
+#   requires: auth_user_context, chat_repository
+#   class: runtime
+# === END DEPENDENCIES ===
+```
+
+## Field schema
+
+Required:
+
+| Field | Meaning |
+|---|---|
+| `id` | Stable dependency declaration id. |
+| `summary` | One-sentence description of why these edges exist. |
+
+At least one edge field is required unless the entry records `hmmm`:
+
+| Edge field | Meaning |
+|---|---|
+| `imports` | Comma-separated modules/packages imported by this module. |
+| `calls` | Comma-separated functions, methods, routes, commands, or capabilities called by this module. |
+| `requires` | Comma-separated msdmd ids this module depends on. |
+| `provides` | Comma-separated ids or surfaces this module provides to others. |
+| `external` | Comma-separated external services, APIs, or packages this module depends on. |
+
+Optional:
+
+| Field | Meaning |
+|---|---|
+| `class` | Dependency class (`runtime`, `build`, `test`, `docs`, `ops`, `agent`). |
+| `direction` | `inbound`, `outbound`, `bidirectional`, or `hmmm`. |
+| `owner` | Person, role, or team responsible for this dependency shape. |
+| `since` | Version or date the declaration was added. |
+| `deprecated` | If present, marks an edge scheduled for removal. |
+
+## Runner contract
+
+A DEPENDENCIES runner MUST:
+
+1. Parse every `DEPENDENCIES` block with the universal msdmd parser.
+2. Build a graph from `imports`, `calls`, `requires`, `provides`, and
+   `external` fields where resolvers exist.
+3. Report unresolved non-`hmmm` edges as drift.
+4. Report cycles in classes where cycles are disallowed by local policy.
+5. Report modules with imports/calls but no DEPENDENCIES block as visible
+   coverage gaps when the runner can detect them.
+6. Exit non-zero for malformed required fields, unresolved resolvable edges,
+   or forbidden cycles. Coverage gaps fail only in strict mode.
+
+## Reporting shape
+
+- `EDGE`: declared edge and source module.
+- `UNRESOLVED`: declared edge no longer resolves.
+- `CYCLE`: graph cycle detected.
+- `PENDING`: edge or direction recorded as `hmmm`.
+- `GAP`: dependency-bearing module without DEPENDENCIES metadata.
+
+## Anti-patterns
+
+- Treating an import list as architecture without explaining why edges exist.
+- Declaring dependencies only in a central graph file.
+- Hiding unresolved dependencies by omitting them; use `hmmm`.
+- Failing all cycles blindly; some test or plugin graphs may intentionally cycle.
+
+hmmm
+- exact resolver syntax for cross-language call and route edges
+- which dependency classes disallow cycles by default
+- whether package-manager dependencies should be declared here or only source-level edges

doc-build/SKILL.md

@@ -9,6 +9,10 @@ description: Self-declaring documentation coverage built on msdmd. Each module d
 module's documentation obligations into colocated metadata so docs drift is
 observable instead of discovered by surprise.
 
+Implementation status: this skill defines the `DOCS` block and runner contract.
+This repo does not currently ship a DOCS runner script; consuming repos should
+implement the contract below against their own documentation tree.
+
 Read `msdmd/SKILL.md` first if you have not. The block syntax, parser
 contract, and visible gap rule are inherited.
 

msdmd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: msdmd
-description: Module Self-Declared Metadata in Markdown — the foundational convention where each source module declares its own structured metadata in a fenced comment block. Other skills in this lib (doc-build, cap-build, test-build, meta-module-build, risk-boundary-build, ratios, etc.) are thin applications on top of this convention. Load this when authoring a new metadata-driven skill, when extending the block schema, or when building a parser/executor for a new application.
+description: Module Self-Declared Metadata in Markdown — the foundational convention where each source module declares its own structured metadata in a fenced comment block. Other skills in this lib (doc-build, cap-build, deps-build, owner-build, test-build, meta-module-build, risk-boundary-build, ratios, etc.) are thin applications on top of this convention. Load this when authoring a new metadata-driven skill, when extending the block schema, or when building a parser/executor for a new application.
 ---
 
 # msdmd — Module Self-Declared Metadata in Markdown
@@ -184,8 +184,9 @@ their own SKILL.md.
 
 `test-build/` is the canonical reference application. Read its
 SKILL.md alongside this one to see the pattern fully realized; read
-`doc-build/`, `cap-build/`, `risk-boundary-build/`, and `ratios/` for
-additional applications over the same parser contract.
+`doc-build/`, `cap-build/`, `deps-build/`, `owner-build/`,
+`risk-boundary-build/`, and `ratios/` for additional applications over
+the same parser contract.
 
 ## Anti-patterns