bmad-module-skill-forge 2.0.0 → 2.0.2

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "2.0.0",
+      "version": "2.0.2",
       "author": {
         "name": "Armel"
       },

package/.nvmrc

@@ -1 +1 @@
-22
+24

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "2.0.0"
+skf_version: "2.0.2"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/workflows.md

@@ -474,7 +474,7 @@ If the answer to all of these is "no", the health check exits in one line (`Clea
 
 - **Severity gate.** Only `bug` findings submit live as GitHub issues by default. `friction` and `gap` findings — the most subjective categories — go to a **local queue** at `{forge_data_folder}/improvement-queue/` unless you explicitly opt in to submit them live during the review gate. This keeps the high-signal reports (real defects) flowing to maintainers while the softer observations sit safely on your disk for you to batch or revisit.
 - **Fingerprint dedup.** Every finding gets a deterministic 7-hex fingerprint computed from `sha1(severity|workflow|step_file|section)` — no LLM similarity judgment, just a tuple hash. Before Ferris opens a new issue, it searches the repo for an existing open issue with the same `fp-*` label. If one exists, you're offered a choice: add a 👍 reaction (silent upvote), react + post a one-sentence environment delta, open a new issue anyway (if you're certain it's distinct), or skip. Re-reporting the same fingerprint is safe — it just adds to the signal-count on the canonical issue.
-- **Global seen-cache.** Once you've submitted or reacted for a given fingerprint, it's recorded at `~/.skf/health-check-seen.json` so the same user never re-reports the same defect across sessions or across different projects on the same machine.
+- **Global seen-cache.** Once you've submitted or reacted for a given fingerprint, it's recorded at `~/.skf/health-check-seen.json` so the same user doesn't re-report the same defect across sessions or across different projects on the same machine, for as long as the issue it points at stays open. Once that issue is closed as completed, the suppression lifts on purpose: a fresh sighting of a fixed defect is a regression, and it gets reported and linked back to the original.
 - **Server-side safety net.** If two users race past the client-side search and both open issues with the same fingerprint, a GitHub Action on this repo catches it: the later issue is auto-closed as a duplicate, linked to the canonical (lowest-numbered) issue, and a 👍 is added there to preserve the signal-count. Manual filers using the [issue template](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) feed the same pipeline.
 
 **Net effect:** 1,000 users hitting the same bug produce **one canonical issue** with a reaction-count of roughly 1,000 — not 1,000 duplicate issues or a 1,000-comment thread. The maintainer sees population impact at a glance, and your report is never lost.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-language-corpora.py test/test-skf-merge-doc-urls.py test/test-skf-derive-assembly-shape.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py test/test-skf-campaign-state.py test/test-skf-campaign-pins.py test/test-skf-campaign-deps.py test/test-skf-campaign-report.py test/test-skf-campaign-stepfiles.py test/test-skf-campaign-validate-state.py test/test-skf-campaign-provenance.py test/test-skf-campaign-parse-manifest.py test/test-skf-campaign-render-kickoff.py -v",
+    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-language-corpora.py test/test-skf-merge-doc-urls.py test/test-skf-derive-assembly-shape.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py test/test-skf-campaign-state.py test/test-skf-campaign-pins.py test/test-skf-campaign-deps.py test/test-skf-campaign-report.py test/test-skf-campaign-stepfiles.py test/test-skf-campaign-validate-state.py test/test-skf-campaign-provenance.py test/test-skf-campaign-parse-manifest.py test/test-skf-campaign-render-kickoff.py test/test-skf-campaign-render-batch.py test/test-skf-shard-body.py test/test-skf-render-metadata-stats.py test/test-skf-comention-pairs.py test/test-skf-count-tokens.py test/test-skf-reconcile-coverage.py test/test-skf-verify-provenance-completeness.py test/test-skf-find-cycles.py test/test-skf-validate-feasibility-report.py test/test-skf-rewrite-skill-name.py test/test-skf-verify-no-trace.py test/test-skf-validate-inventory.py test/test-skf-check-metadata-coherence.py test/test-skf-scan-doc-rot.py test/test-skf-aggregate-coherence.py test/test-skf-dir-sizes.py test/test-skf-parse-pipeline.py test/test-skf-validate-rename-name.py test/test-skf-verify-declared-numerator.py test/test-skf-combine-external-scores.py test/test-skf-new-file-diff.py test/test-skf-coverage-tally.py test/test-skf-report-delta.py test/test-skf-verdict-rollup.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/knowledge/skill-lifecycle.md

@@ -143,7 +143,7 @@ EX → agentskills.io bundle + context snippets (flat platform paths)
 
 VS → feasibility-report-{project_name}.md (verdict + integration verdicts)
        ↓ (report consumed by RA)
-RA → refined-architecture-{project_name}.md (gaps filled, issues flagged, improvements suggested)
+RA → refined-architecture-{arch_project_name}.md (gaps filled, issues flagged, improvements suggested)
        ↓ (refined doc consumed by SS compose-mode)
 SS (compose) → SKILL.md (stack skill synthesized from individual skills + architecture)
 ```

package/src/module-help.csv

@@ -1,4 +1,4 @@
-module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 skf,skf-forger,Ferris — Skill Forge Agent,FF,"Skill compilation specialist — the forge master. Invoke to access all SKF workflows via guided menu.",,,anytime,,,false,,
 skf,skf-setup,Setup Forge,SF,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Forge+/Deep)",,,anytime,,"skf-analyze-source,skf-brief-skill,skf-quick-skill,skf-verify-stack,skf-campaign",false,,forge-tier.yaml
 skf,skf-campaign,Campaign,CA,"Orchestrate multi-library skill production across sessions — dependency tracking, file-based state, and resume",,resume [--from=<skill>],anytime,skf-setup,,false,forge_data_folder,_campaign-state.yaml
@@ -10,7 +10,7 @@ skf,skf-create-stack-skill,Stack Skill,SS,"Consolidated project stack skill with
 skf,skf-update-skill,Update Skill,US,"Smart regeneration preserving [MANUAL] sections after source changes",,,anytime,skf-export-skill,,false,skills_output_folder,SKILL.md
 skf,skf-audit-skill,Audit Skill,AS,"Drift detection between skill and current source code",,,anytime,skf-export-skill,,false,,drift report
 skf,skf-verify-stack,Verify Stack,VS,"Pre-code stack feasibility verification against architecture and PRD documents",,,anytime,skf-setup,skf-refine-architecture,false,forge_data_folder,feasibility-report-{project_name}.md
-skf,skf-refine-architecture,Refine Architecture,RA,"Improve architecture doc using verified skill data and VS feasibility findings",,,anytime,skf-verify-stack,,false,output_folder,refined-architecture-{project_name}.md
+skf,skf-refine-architecture,Refine Architecture,RA,"Improve architecture doc using verified skill data and VS feasibility findings",,,anytime,skf-verify-stack,,false,output_folder,refined-architecture-{arch_project_name}.md
 skf,skf-test-skill,Test Skill,TS,"Cognitive completeness verification — quality gate before export",,,anytime,"skf-create-skill,skf-create-stack-skill,skf-quick-skill",skf-export-skill,false,,completeness score
 skf,skf-export-skill,Export Skill,EX,"Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules",,,anytime,skf-test-skill,"skf-update-skill,skf-audit-skill,skf-rename-skill,skf-drop-skill",false,skills_output_folder,agentskills.io package
 skf,skf-rename-skill,Rename Skill,RS,"Rename a skill across all its versions — transactional copy-verify-delete with platform context rebuild",,,anytime,skf-export-skill,,false,skills_output_folder,renamed skill group

package/src/shared/health-check.md

@@ -151,7 +151,36 @@ The `section-slug` is a kebab-case normalized section heading (e.g. `missing-sta
 
 **2. Check the local seen-cache** at `{seenCachePath}`:
 
-If the cache exists and already contains this fingerprint for this user, skip submission silently and log: `"fp-{hash}: already submitted from this machine on {date}, issue {url} — skipping"`. This prevents the same user from re-reporting the same defect across sessions.
+Read `{seenCachePath}`. A missing file, an empty file, or one that does not parse as JSON is an empty cache — never an error, never a reason to halt.
+
+**Presence in the cache is not the verdict.** A fingerprint whose defect was already fixed must NOT suppress: a fresh sighting of a fixed defect is a *regression*, and it is the single most valuable report this loop can produce. Look up the fingerprint and work these branches in order, stopping at the first that matches:
+
+1. **No record for this fingerprint** → `unseen`. Go to sub-step 3.
+2. **Record with `"action": "resolved"`** → `regression`. Recorded by hand when the defect was fixed. Go to sub-step 3 and apply the regression treatment below.
+3. **Record with `"action"` of `created`, `reacted`, or `commented`, and a non-empty `issue_url`** → you must decide whether that issue is still live before you may suppress. The cache is machine-local and records only what *this* user did; the issue's own state is shared, so it is the better authority. Run exactly this, and give it a hard time bound so a hung network can never strand the run:
+
+   ```
+   timeout 10 gh issue view {issue_url} --json state,stateReason --jq '.state + "/" + (.stateReason // "")'
+   ```
+
+   - `CLOSED/COMPLETED`, or `MERGED` (the record points at a resolving PR) → `regression`. It was fixed and closed out.
+   - `CLOSED/NOT_PLANNED` → `handled`. **Not** a fix: this is how the dedup Action closes a duplicate, and how a maintainer closes a wontfix. Treating it as a regression would file a REGRESSION issue against a defect nobody ever fixed, every session, forever.
+   - `OPEN` → `handled`. Already filed and still being tracked.
+   - Any failure at all (offline, timeout, no auth, deleted issue, unparseable output) → `handled`. This refinement never blocks a run and never halts on error.
+4. **Record with one of those actions but an empty `issue_url`** → `handled`. There is no issue to consult, so the local record stands.
+5. **Record with no `action`, or any other value** → `unrecognized`. Hand-edited, or written by a newer version of this file, so it cannot be confirmed handled. Go to sub-step 3 as an ordinary submission.
+
+**`handled` is the only verdict that suppresses.** Skip submission silently and log: `"fp-{hash}: already handled on {date}, issue {url} — skipping"`. Every other verdict proceeds to sub-step 3.
+
+**Why anything uncertain reports instead of suppressing.** A duplicate report is self-healing: the dedup Action closes it and moves the upvote to the canonical issue. A silenced regression is caught by nothing at all. When the verdict is in doubt, report.
+
+**Regression treatment** (verdicts `regression` only). Carry the prior record forward so the recurrence can never be filed as a first sighting:
+
+- Append ` — REGRESSION` to the issue title, after `{short description}`.
+- Add a `## Regression` section immediately above `## Finding`, containing one line: `Regression of {issue_url}, resolved {date}.` If the prior record has no `issue_url`, write `Regression of a previously resolved local finding, resolved {date}.` The `{fp}` label still ties the two together server-side.
+- Leave `## Finding` and the other one-sentence sections exactly as specified below. The backlink lives in its own section precisely so those budgets are untouched.
+
+**What this does and does not catch.** The fingerprint is `sha1` over the section slug, so a fix that renames or relocates the section it touches changes the fingerprint. Such a regression arrives as `unseen` and is reported as a first sighting, which is safe but unlinked. These branches catch the regressions that recur under the same heading in the same step file, which is the case where the old behaviour was silent.
 
 **3. Check GitHub CLI availability** with `gh auth status`. If `gh` is unavailable, fall through to step 5c (local fallback).
 
@@ -205,9 +234,11 @@ gh issue create \
   --body "{formatted body using issue template structure}"
 ```
 
+When sub-step 2 returned `regression`, append ` — REGRESSION` to that `--title` value, after `{short description}`, and include the `## Regression` backlink section in the body. The command above is the literal one you run, so the marker has to be in it: an instruction that the title should say REGRESSION loses to a copied command that does not.
+
 The fingerprint `{fp}` appears in both title (human-readable) and label (server-side filterable). Maintainers can query all reports for a defect via the `fp-*` label without relying on title text.
 
-After the issue is created, write the fingerprint → issue-url mapping to the seen-cache at `{seenCachePath}` so this user never re-reports the same fingerprint.
+After the issue is created, write the fingerprint → issue-url mapping to the seen-cache at `{seenCachePath}` so this user does not re-report it while that issue stays open.
 
 **Writing rules — non-negotiable:**
 
@@ -300,7 +331,13 @@ After each successful `gh issue create`, append to `{seenCachePath}`:
 }
 ```
 
-Ensure the parent directory exists. This file is global across the user's machine — not per-project — so the same defect is never re-reported across different repos the user works in.
+Ensure the parent directory exists. This file is global across the user's machine — not per-project — so the same defect is not re-reported across different repos the user works in while its issue stays open.
+
+**Merge, never replace.** Read the existing file, set this one key, write the whole object back. A write that emits only the new key silently discards every other fingerprint the user has ever recorded.
+
+**Read before you write, and never downgrade a `resolved` record.** Before setting the key, check whether one already exists with `"action": "resolved"`. If it does, and you are here because that resolved defect just recurred, you are recording the regression's new issue: overwrite it with `created` and the new URL, which is correct because a live issue now tracks the recurrence. In every other case leave a `resolved` record alone. The record must never move from `resolved` back to a suppressing action without a new open issue to justify it, or the next run silently re-arms the suppression the fix removed.
+
+**The `action` vocabulary is `created`, `reacted`, `commented`, `resolved`.** The first three are written by this workflow. `resolved` is written by hand when the defect is fixed, and it is the only one that does not suppress. See the health-check section of `CONTRIBUTING.md` for when to record it.
 
 ### 5c. Local-Queue Path (gh unavailable OR friction/gap default)
 

package/src/shared/scripts/skf-comention-pairs.py

@@ -0,0 +1,350 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Co-mention Pairs — compute compose-mode co-mention pairs from an
+architecture document with the same precision guards the prompt used to run
+by hand.
+
+`detect-integrations.md` §2 (compose branch) asks the LLM to scan an
+architecture markdown document for skill-name co-mentions using three
+deterministic guards:
+
+  1. Word-boundary matching (`\\b{skill_name}\\b`, case-insensitive) — no
+     substring false positives (`react` must not match inside `reactive`).
+  2. Section filtering — paragraphs governed by an H1/H2 header that
+     normalises to one of {introduction, overview, glossary, table of
+     contents, references, appendix, index} are excluded, and heading text
+     itself is never a co-mention source.
+  3. Two-paragraph minimum — a pair (A, B) qualifies only when at least two
+     distinct body paragraphs each contain word-boundary matches for both A
+     and B.
+
+Given a fixed architecture doc and skill-name set the qualifying-pair set is
+fully determined, so this belongs in a deterministic helper rather than
+in-prompt regex/counting. It mirrors the co-import subprocess the code-mode
+branch already delegates and the `skf-pair-intersect.py` pre-pass. The LLM
+still does the semantic composition (integration-section authoring, tier
+inheritance, VS-verdict parsing) — the script only emits the qualifying pairs
+and their evidence paragraphs.
+
+Subcommand:
+  comention --doc <md-file-or-'-'> --skills <json-file-or-'-'>
+      --doc     path to the architecture markdown document, or '-' for stdin.
+      --skills  path to a JSON array of loaded skill names
+                (e.g. `["react", "express"]`), or '-' for stdin.
+                (--doc and --skills cannot both read from stdin.)
+
+      Emit JSON:
+        {
+          "pairs": [
+            {
+              "a": "<skill>", "b": "<skill>",
+              "paragraph_count": N,
+              "evidence": [{"header": "<governing-header-or-null>",
+                            "excerpt": "<collapsed paragraph text>"}, ...]
+            },
+            ...
+          ],
+          "excluded_section_count": M
+        }
+
+      Only unordered pairs (a < b lexicographically) with paragraph_count >= 2
+      are emitted. `pairs[]` is sorted by paragraph_count DESC, then (a, b)
+      ASC — stable, mirroring skf-pair-intersect.py. `evidence[]` is in
+      document order. `excluded_section_count` is the number of DISTINCT
+      excluded H1/H2 sections (by normalised header) that governed at least
+      one body paragraph — a diagnostic for the caller, not a gate.
+
+CLI examples:
+  uv run skf-comention-pairs.py comention --doc arch.md --skills skills.json
+  echo '["react","express"]' | uv run skf-comention-pairs.py comention \\
+      --doc arch.md --skills -
+
+Exit codes:
+  0  — operation succeeded (including: no qualifying pairs → empty list)
+  1  — user error (bad JSON, missing/unreadable file, both inputs on stdin,
+       malformed skills array)
+  2  — unexpected internal error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# Closed exclusion set — governing H1/H2 headers that normalise to one of
+# these drop their paragraphs from co-mention analysis (they typically
+# enumerate all libraries without describing an integration).
+EXCLUDED_HEADERS = frozenset({
+    "introduction",
+    "overview",
+    "glossary",
+    "table of contents",
+    "references",
+    "appendix",
+    "index",
+})
+
+# ATX header line: 1-6 leading hashes followed by at least one space/tab.
+# A line like `#foo` (no space) is NOT a header per CommonMark and is treated
+# as body text. Capture group 1 = hashes (level), group 2 = header text.
+_HEADER_RE = re.compile(r"^(#{1,6})[ \t]+(.*)$")
+
+_EXCERPT_LIMIT = 240
+
+
+class UserError(Exception):
+    """A caller-facing input error → exit code 1."""
+
+
+# --------------------------------------------------------------------------
+# Markdown parsing
+# --------------------------------------------------------------------------
+
+
+def _strip_closing_hashes(text: str) -> str:
+    """Remove a closed-ATX trailing run of hashes (e.g. `Overview ##`)."""
+    return re.sub(r"[ \t]*#+[ \t]*$", "", text)
+
+
+def normalize_header(text: str) -> str:
+    """Normalise a header for exclusion-set comparison: lowercase, collapse
+    internal whitespace, strip trailing punctuation."""
+    t = text.strip().lower()
+    t = re.sub(r"\s+", " ", t).strip()
+    t = t.rstrip(".,:;!?").strip()
+    return t
+
+
+def parse_body_paragraphs(doc_text: str) -> list[tuple[str | None, str]]:
+    """Split the document into body paragraphs, each tagged with the raw text
+    of its governing (nearest-preceding) H1/H2 header (or None).
+
+    Paragraphs are maximal runs of consecutive non-blank, non-header lines,
+    separated by blank lines. Header lines of ANY level are never emitted as
+    paragraphs (headings are not a co-mention source). Only H1/H2 headers
+    update the governing header; H3-H6 leave it unchanged.
+    """
+    paragraphs: list[tuple[str | None, str]] = []
+    governing: str | None = None
+    buf: list[str] = []
+
+    def _flush() -> None:
+        if buf:
+            text = "\n".join(buf).strip()
+            if text:
+                paragraphs.append((governing, text))
+            buf.clear()
+
+    for raw_line in doc_text.splitlines():
+        m = _HEADER_RE.match(raw_line)
+        if m is not None:
+            # A header terminates the current paragraph; the header line
+            # itself is not body content.
+            _flush()
+            level = len(m.group(1))
+            header_text = _strip_closing_hashes(m.group(2)).strip()
+            if level <= 2:
+                governing = header_text if header_text else None
+            continue
+        if raw_line.strip() == "":
+            _flush()
+            continue
+        buf.append(raw_line)
+    _flush()
+    return paragraphs
+
+
+# --------------------------------------------------------------------------
+# Co-mention analysis
+# --------------------------------------------------------------------------
+
+
+def _make_excerpt(text: str, limit: int = _EXCERPT_LIMIT) -> str:
+    """Collapse whitespace and truncate for a stable, compact evidence quote."""
+    collapsed = re.sub(r"\s+", " ", text).strip()
+    if len(collapsed) > limit:
+        return collapsed[: limit - 3].rstrip() + "..."
+    return collapsed
+
+
+def analyze(doc_text: str, skill_names: list[str]) -> dict:
+    """Compute qualifying co-mention pairs and their evidence.
+
+    Deterministic: same (doc_text, skill_names) → identical output.
+    """
+    names = sorted(set(skill_names))
+    patterns = {
+        n: re.compile(r"\b" + re.escape(n) + r"\b", re.IGNORECASE)
+        for n in names
+    }
+    paragraphs = parse_body_paragraphs(doc_text)
+
+    excluded_sections: set[str] = set()
+    # (a, b) -> list of evidence dicts, one per qualifying paragraph
+    pair_evidence: dict[tuple[str, str], list[dict]] = {}
+
+    for governing, text in paragraphs:
+        if governing is not None:
+            norm = normalize_header(governing)
+            if norm in EXCLUDED_HEADERS:
+                excluded_sections.add(norm)
+                continue
+        # names is sorted, so `present` is sorted → pairs are (a < b)
+        present = [n for n in names if patterns[n].search(text)]
+        if len(present) < 2:
+            continue
+        excerpt = _make_excerpt(text)
+        evidence_entry = {"header": governing, "excerpt": excerpt}
+        for i in range(len(present)):
+            for j in range(i + 1, len(present)):
+                key = (present[i], present[j])
+                pair_evidence.setdefault(key, []).append(evidence_entry)
+
+    pairs: list[dict] = []
+    for (a, b), evidence in pair_evidence.items():
+        if len(evidence) >= 2:
+            pairs.append({
+                "a": a,
+                "b": b,
+                "paragraph_count": len(evidence),
+                "evidence": evidence,
+            })
+    pairs.sort(key=lambda p: (-p["paragraph_count"], p["a"], p["b"]))
+
+    return {
+        "pairs": pairs,
+        "excluded_section_count": len(excluded_sections),
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _read_source(source: str, label: str) -> str:
+    """Read text from a file path or stdin (if source == '-')."""
+    if source == "-":
+        try:
+            return sys.stdin.read()
+        except OSError as exc:
+            raise UserError(f"failed to read {label} from stdin: {exc}") from exc
+    path = Path(source)
+    if not path.is_file():
+        raise UserError(f"{label} file not found: {path}")
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise UserError(f"failed to read {label} file {path}: {exc}") from exc
+
+
+def parse_skills(raw_text: str) -> list[str]:
+    """Parse and validate the --skills JSON array of non-empty strings."""
+    try:
+        data = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise UserError(f"malformed JSON in --skills input: {exc}") from exc
+    if not isinstance(data, list):
+        raise UserError(
+            "--skills input must be a JSON array of strings; "
+            f"got {type(data).__name__}"
+        )
+    names: list[str] = []
+    for idx, item in enumerate(data):
+        if not isinstance(item, str) or not item:
+            raise UserError(
+                f"--skills[{idx}] must be a non-empty string; got {item!r}"
+            )
+        names.append(item)
+    return names
+
+
+def _cmd_comention(args: argparse.Namespace) -> int:
+    if args.doc == "-" and args.skills == "-":
+        raise UserError(
+            "--doc and --skills cannot both read from stdin ('-')"
+        )
+    # Read the file-backed input first so a single stdin source stays intact.
+    if args.doc == "-":
+        skills_text = _read_source(args.skills, "--skills")
+        doc_text = _read_source(args.doc, "--doc")
+    else:
+        doc_text = _read_source(args.doc, "--doc")
+        skills_text = _read_source(args.skills, "--skills")
+    skill_names = parse_skills(skills_text)
+
+    result = analyze(doc_text, skill_names)
+    if args.verbose:
+        print(
+            f"analyzed {len(set(skill_names))} distinct skill names; "
+            f"{len(result['pairs'])} qualifying pairs; "
+            f"{result['excluded_section_count']} excluded sections",
+            file=sys.stderr,
+        )
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-comention-pairs",
+        description=(
+            "Compute compose-mode co-mention pairs from an architecture "
+            "document (detect-integrations.md §2 compose branch)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_cm = sub.add_parser(
+        "comention",
+        help=(
+            "emit qualifying co-mention pairs (>=2 body paragraphs, "
+            "word-boundary, section-filtered) as JSON"
+        ),
+    )
+    p_cm.add_argument(
+        "--doc",
+        required=True,
+        help="path to the architecture markdown document, or '-' for stdin",
+    )
+    p_cm.add_argument(
+        "--skills",
+        required=True,
+        help=(
+            "path to a JSON array of loaded skill names, or '-' for stdin. "
+            "Shape: [\"<skill>\", ...]"
+        ),
+    )
+    p_cm.add_argument(
+        "--verbose",
+        action="store_true",
+        help="print a one-line summary to stderr",
+    )
+    p_cm.set_defaults(func=_cmd_comention)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except UserError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:  # noqa: BLE001 — last-resort guard → exit 2
+        print(f"internal error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())