bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-update-skill/scripts/skf-new-file-diff.py

@@ -1,12 +1,12 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # ///
 """Deterministic NEW_FILE detection for skf-update-skill (detect-changes Category D).
 
 `skf-hash-content compare` classifies files already tracked in the provenance
 map (UNCHANGED / MODIFIED_FILE / DELETED_FILE) but by design cannot report a
-file that is present in source yet absent from the provenance map — a NEW_FILE.
+file that is present in source yet absent from the provenance map: a NEW_FILE.
 Deriving that set is a set-difference plus a filter with exactly one correct
 answer per input: take every `source_file` in the scripts/assets inventory
 (emitted by `skf-detect-scripts-assets detect`), subtract the paths already in
@@ -37,10 +37,12 @@ inventory it came from (scripts -> "script", assets -> "asset"). A path found
 in both inventories is counted once, resolved as "script".
 
 Exit codes:
-  0  success
-  2  bad input (unreadable/invalid stdin JSON, missing/invalid provenance map)
+  0  success (and --help)
+  2  bad input (a usage error, unreadable/invalid stdin JSON, missing/invalid
+     provenance map)
 """
 
+import argparse
 import json
 import re
 import sys
@@ -139,11 +141,31 @@ def diff(detect: dict, tracked: set[str]) -> dict:
     }
 
 
+class _JsonErrorParser(argparse.ArgumentParser):
+    """Report a usage error as the JSON error and exit 2 every other bad input gets."""
+
+    def error(self, message: str) -> "NoReturn":  # type: ignore[valid-type]
+        _fail(f"usage: skf-new-file-diff.py <provenance-map-path>  (detect JSON on stdin): {message}")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _JsonErrorParser(
+        prog="skf-new-file-diff.py",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "provenance_map",
+        metavar="provenance-map-path",
+        help="the skill's provenance-map.json (the detect JSON is read on stdin)",
+    )
+    return parser
+
+
 def main(argv: list[str]) -> int:
-    if len(argv) != 2:
-        _fail("usage: skf-new-file-diff.py <provenance-map-path>  (detect JSON on stdin)")
+    args = _build_parser().parse_args(argv[1:])
 
-    provenance_path = Path(argv[1])
+    provenance_path = Path(args.provenance_map)
     if not provenance_path.exists():
         _fail(f"provenance map not found: {provenance_path}")
 

package/src/skf-verify-stack/SKILL.md

@@ -7,7 +7,7 @@ description: Pre-code stack feasibility verification against architecture and PR
 
 ## Overview
 
-Cross-references generated skills against architecture and PRD documents to produce a feasibility report with evidence-backed integration verdicts, coverage analysis, and requirements mapping. Read-only: it reads skills and input documents and writes only the feasibility report (see Workflow Rules).
+Cross-references generated skills against architecture and PRD documents to produce a feasibility report with evidence-backed integration verdicts, coverage analysis, and requirements mapping. Read-only: it reads skills and input documents and writes only the feasibility report, its result files and a scratch run folder (see Workflow Rules).
 
 **Schema contract:** This skill is the producer of the SKF shared feasibility report schema — every report conforms to it.
 
@@ -18,6 +18,8 @@ Cross-references generated skills against architecture and PRD documents to prod
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
 - `{skill-name}` resolves to the skill directory's basename.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `shared/references/output-contract-schema.md` and `shared/health-check.md`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
 
 ## Role
 
@@ -33,7 +35,11 @@ These rules apply to every step in this workflow:
 - If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
 - At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision; a gate that picks its default for the user (step 1's offer of the newest earlier report) also records that decision in the run sink the moment it decides
+- Every helper a stage runs (a `scripts/` file, or a shared helper from the stage's probe order) is required: if the probe order resolves to no path, or the helper cannot start, HALT (exit code 3, `halt_reason: "resolution-failure"`) at the stage's phase, through the stage's halt envelope. Never recompute a helper's result by hand: the main-thread rule above covers subagent work, not helpers.
+- Every HARD HALT names its exit code, `halt_reason` and phase, and in headless mode prints its envelope through the shared emitter, with the command each stage file shows (`references/exit-codes.md` describes the envelope).
+- Stages 1 to 5 write only the timestamped report `{outputFile}`, and each write that fails halts (exit code 4, `halt_reason: "write-failed"`). Step 6 copies the report to `{outputFileLatest}` only after it passes the feasibility-report check, so a run that halts before then leaves the previous finished copy, the one consumers read, in place.
+- Run state lives in `{run_dir}`, not in context; step 6 deletes it, a HALT keeps it.
 
 ## Stages
 
@@ -44,7 +50,7 @@ These rules apply to every step in this workflow:
 | 3 | Integration Verification | references/integrations.md | Yes |
 | 4 | Requirements Mapping | references/requirements.md | Yes |
 | 5 | Synthesize Verdict | references/synthesize.md | Yes |
-| 6 | Report | references/report.md | No (confirm) |
+| 6 | Report | references/report.md | Yes |
 | 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
@@ -53,20 +59,14 @@ These rules apply to every step in this workflow:
 |--------|--------|
 | **Inputs** | architecture_doc_path [required], prd_path [optional], previous_report_path [optional] |
 | **Flags** | `--headless` / `-H` (auto-resolve all gates); `--architecture-doc <path>` (skip step 1 prompt for the required input); `--prd <path>` (skip step 1 prompt for the optional PRD); `--previous-report <path>` (skip step 1 prompt for delta comparison) |
-| **Gates** | step 1 Input Gate (use args); step 6 Report Menu ([R] review / [X] exit, headless default X). Steps 2-3 also hold elective vacuous-analysis guards (0% coverage, all-Blocked) that only fire in degenerate cases; every guard auto-resolves to Continue in headless. |
-| **Outputs** | `feasibility-report-{projectSlug}-{timestamp}.md` and `feasibility-report-{projectSlug}-latest.md` (copy, not symlink) per the SKF shared feasibility report schema (`_bmad/skf/shared/references/feasibility-report-schema.md`; `src/shared/references/…` in a dev checkout) — with integration verdicts, coverage analysis, recommendations, and evidence sources; plus `verify-stack-result-{timestamp}.json` and `verify-stack-result-latest.json` |
+| **Gates** | step 1 Input Gate (use args), including the offer to compare against the newest earlier report (headless default: use it). No later stage waits for input: a run with 0% coverage or only Blocked pairs prints one warning and continues, so its report still carries the recommendations. |
+| **Outputs** | `feasibility-report-{project_slug}-{timestamp}.md` and its `feasibility-report-{project_slug}-latest.md` copy (not a symlink), written by step 6 once the finished report passes the feasibility-report check, both per the SKF shared feasibility report schema (`{project-root}/_bmad/skf/shared/references/feasibility-report-schema.md`; `{project-root}/src/shared/references/feasibility-report-schema.md` in a dev checkout), with integration verdicts, coverage analysis, recommendations, and evidence sources; plus `verify-stack-result-{YYYYMMDD-HHmmss}.json` and `verify-stack-result-latest.json` in `{forge_data_folder}` |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Per-flag args (`--architecture-doc`, `--prd`, `--previous-report`) consumed at the gates that would otherwise prompt. |
 | **Exit codes** | See `references/exit-codes.md` |
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every headless hard halt emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-SKF_VERIFY_STACK_RESULT_JSON: {"status":"success|error","report_path":"…|null","report_latest_path":"…|null","overall_verdict":"…|null","coverage_percentage":0,"recommendation_count":0,"exit_code":0,"halt_reason":null}
-```
-
-`status` is `"success"` on the terminal happy path, `"error"` on any halt. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"skills-folder-missing"`, `"insufficient-skills"`, `"forge-folder-unconfigured"`, `"resolution-failure"`, `"previous-report-collision"`, `"inventory-unreliable"`, `"schema-violation"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches `references/exit-codes.md` (the `analysis-halted` / exit-8 gates are interactive-only, so they never reach this envelope). `overall_verdict` uses the schema tokens (`FEASIBLE`/`CONDITIONALLY_FEASIBLE`/`NOT_FEASIBLE`).
+When `{headless_mode}` is true, step 6 prints one `SKF_VERIFY_STACK_RESULT_JSON: {...}` line on **stdout** and every HARD HALT one on **stderr**, built by the shared emitter: `references/exit-codes.md` gives its fields, the `halt_reason` values and the halt command.
 
 ## On Activation
 
@@ -74,49 +74,30 @@ SKF_VERIFY_STACK_RESULT_JSON: {"status":"success|error","report_path":"…|null"
    - `project_name`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
 
-2. **Compute run-scoped variables** (same place as config so every stage can reference them without re-derivation):
-   - `project_slug` ← slugify `project_name` (lowercase, hyphens only, no unicode, no whitespace)
+2. **Fix the run-scoped variables** so no stage derives them again:
    - `timestamp` ← UTC `YYYYMMDD-HHmmss` captured at activation time
-   - These two combine in init.md §4 into `{outputFile}` per the stage frontmatter template, but the values themselves are fixed for the entire workflow run — every later reference to `{outputFile}` resolves consistently.
+   - `project_slug` is bound by init.md before its §1, from the shared feasibility-report helper, which holds the one slug rule the consumers of this report also apply; never slugify `project_name` by hand
+   - The two combine in init.md §4 into `{outputFile}` and `{outputFileLatest}` per the stage frontmatter template, and stay fixed for the whole run, so every later reference to either file resolves to the same path.
+   - `run_dir` ← `{project-root}/_bmad-output/.skf-run/skf-verify-stack-{timestamp}`, the run folder init.md creates first
 
 3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
+   **Bind the inputs** in every mode: `{architecture_doc_path}` ← the `--architecture-doc` value, `{prd_path}` ← `--prd` and `{previous_report_path}` ← `--previous-report`, each null when its flag is absent. init.md §1 asks only for those still null.
+
 4. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
-
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
-
-   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
-
-   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the four scalars, if the merged value is empty or absent, use the bundled default:
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-verify-stack.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for init.md to record once it has created `{run_dir}`.
 
-   - `{reportTemplatePath}` ← `workflow.report_template_path` if non-empty, else `assets/feasibility-report-template.md`
-   - `{integrationRulesPath}` ← `workflow.integration_rules_path` if non-empty, else `references/integration-verification-rules.md`
-   - `{coveragePatternsPath}` ← `workflow.coverage_patterns_path` if non-empty, else `references/coverage-patterns.md`
-   - `{outputFolderPath}` ← `workflow.output_folder_path` if non-empty, else `{forge_data_folder}`
-
-   Stash all four as workflow-context variables. Stage files reference them directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default.
+   Apply the path-scalar fallback now so stage files don't repeat it: `{reportTemplatePath}` ← `workflow.report_template_path` if non-empty, else `assets/feasibility-report-template.md`. An empty or absent value falls through to that default, and init.md §4 loads the variable as it is. Bind `{outputFolderPath}` ← `{forge_data_folder}`, always (no setting moves it): the report and its `-latest` copy go where create-stack-skill and refine-architecture look for them, and step 1 finds the earlier reports there.
 
    The same merge resolves `workflow.on_complete` (default empty = no-op); report.md §5 executes it, if non-empty, at the terminal stage.
 
-   Also apply the array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries load their file/glob contents as facts — the bundled default glob is `{project-root}/**/project-context.md`); then execute each entry in `workflow.activation_steps_append` after activation completes.
-
-5. **Pre-flight write probe.** Verify `{outputFolderPath}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at init.md §4 atomic write — by then the user has already gone through the input prompts:
-
-   ```bash
-   mkdir -p "{outputFolderPath}" && \
-     printf 'probe' > "{outputFolderPath}/.skf-write-probe" && \
-     rm "{outputFolderPath}/.skf-write-probe"
-   ```
+   Also apply the array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries load their file/glob contents as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off); then execute each entry in `workflow.activation_steps_append` after activation completes.
 
-   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, emit the error envelope per **Result Contract (Headless)** with `report_path: null`, `report_latest_path: null`, `overall_verdict: null`.
+5. **Pre-flight: the emitter.** Before the first prompt, resolve `{emitEnvelopeHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py`, else `{project-root}/src/shared/scripts/skf-emit-result-envelope.py` (the first that exists). If neither exists, HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `on-activation:emitter` and display only: "Verify Stack cannot run without `skf-emit-result-envelope.py`, which is not installed. Re-install SKF."
 
 6. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-verify-stack/assets/feasibility-report-template.md

@@ -19,6 +19,9 @@ architectureDoc: ''
 prdDoc: ''
 previousReport: ''
 skillsAnalyzed: 0
+coverageCovered: null
+coverageMissing: null
+coverageReplaced: null
 stepsCompleted: []
 requirementsPass: ''
 requirementsFulfilled: null
@@ -55,9 +58,8 @@ deltaUnchanged: null
 
 ## Integration Verdicts
 
-<!-- Appended by integrations.
-Consumers grep for the `## Integration Verdicts` heading to locate the pair table.
-The table header is fixed and MUST be emitted exactly as shown below: -->
+<!-- Filled in place by integrations: one row per pair goes under this header.
+The report holds this table once: consumers read it and reject a second copy. -->
 
 | lib_a | lib_b | verdict | rationale |
 |-------|-------|---------|-----------|
@@ -72,5 +74,9 @@ The table header is fixed and MUST be emitted exactly as shown below: -->
 
 ## Evidence Sources
 
-<!-- Appended by synthesize — cite each skill's SKILL.md path, metadata_schema_version,
-     confidence_tier, stack manifest (if any), and architecture/PRD doc paths -->
+<!-- Filled in place by synthesize: one row per skill goes under this header (the
+next run's delta reads its evidence_tier column), then the architecture and PRD
+document paths. -->
+
+| skill | evidence_tier | confidence_tier | metadata_schema_version | skill_md |
+|-------|---------------|-----------------|-------------------------|----------|

package/src/skf-verify-stack/customize.toml

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-verify-stack.
-# Team overrides:     _bmad/custom/skf-verify-stack.toml under {project-root}
-# Personal overrides: _bmad/custom/skf-verify-stack.user.toml under {project-root}
+# Team overrides:     {project-root}/_bmad/custom/skf-verify-stack.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-verify-stack.user.toml
 
 [workflow]
 
@@ -10,27 +10,41 @@
 #   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
 #   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
 
-# Steps to run before the standard activation (uv probe, config load).
-# Overrides append. Use for org-wide pre-flight checks (auth, network,
-# compliance) that must precede any verification work.
+# Steps SKILL.md On Activation step 4 runs once this file resolves: after
+# config.yaml is loaded and {headless_mode} is resolved, before the emitter
+# pre-flight (step 5) and before any stage. Overrides append. Use for org-wide
+# pre-flight checks (auth, network, compliance) that must precede any
+# verification work.
 
 activation_steps_prepend = []
 
-# Steps to run after activation but before the first stage executes.
-# Overrides append. Use for context loads or banner customization that
-# should run once activation completes successfully.
+# Steps to run once activation completes (the emitter resolved), before
+# references/init.md (the first stage) loads. Overrides append. Use for
+# context loads or banner customization.
 
 activation_steps_append = []
 
 # Persistent facts the workflow keeps in mind for the whole run
 # (verification standards, evidence-citation rules, house-style verdict
-# language). Overrides append.
+# language, the other names a technology goes by). Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "Verdict citations must include file:line spans."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/verify-policy.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# Extra aliases go here: a fact such as "Our documents call the postgresql
+# skill Postgres or PG." makes step 2 (coverage) pass both names to the
+# mentions helper as aliases of that skill, so the architecture document's
+# "PG" covers it and pairs it for step 3.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-verify-stack.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
@@ -42,18 +56,37 @@ persistent_facts = [
 
 on_complete = ""
 
-# --- Optional asset overrides ---
-#
-# Lift the canonical asset paths so orgs can substitute house-style copies
-# without forking the skill. Empty string = use the bundled default.
+# --- Optional override. An empty string means the default named below. ---
 
-report_template_path = ""
-integration_rules_path = ""
-coverage_patterns_path = ""
+# The template step 1 (references/init.md section 4) creates the feasibility
+# report from: a path from the skill root, or a {project-root}/... path.
+# Default: assets/feasibility-report-template.md. A house-style copy may
+# reword the prose and add sections of its own, and must keep what the shared
+# feasibility report schema (feasibility-report-schema.md under
+# shared/references/) fixes, since the next run, create-stack-skill and
+# refine-architecture read the report through it:
+#   - the frontmatter keys with their starting values, `schemaVersion: "1.0"`
+#     included;
+#   - the `## Executive Summary`, `## Coverage Analysis`,
+#     `## Integration Verdicts`, `## Recommendations` and `## Evidence Sources`
+#     headings, once each and in that order;
+#   - one empty `| lib_a | lib_b | verdict | rationale |` table under
+#     `## Integration Verdicts`, and the empty
+#     `| skill | evidence_tier | confidence_tier | metadata_schema_version | skill_md |`
+#     table under `## Evidence Sources`: the stages fill both in place.
+# Step 6 checks the finished report against the schema and halts
+# (`schema-violation`) on a copy that breaks it.
 
-# Override the destination directory for the feasibility report only. Empty =
-# use {forge_data_folder} from config.yaml. The result-contract JSON
-# (verify-stack-result-*.json) always stays in {forge_data_folder} as a stable
-# path for pipeline consumers, so redirecting this does not relocate it.
+report_template_path = ""
 
-output_folder_path = ""
+# Not overridable:
+#   - the integration verification rules: they hold the obligations the shared
+#     schema puts on this report's producer (Check 4's literal citation and the
+#     Plausible cap), which the report's readers rely on;
+#   - the coverage patterns: the shared mentions helper finds the skills the
+#     architecture document names, and a fact (see persistent_facts) adds the
+#     other names a skill goes by;
+#   - the report folder: the report always lands in {forge_data_folder}, where
+#     create-stack-skill and refine-architecture look for it. Change
+#     forge_data_folder in config.yaml to move the report and its readers
+#     together.

package/src/skf-verify-stack/references/coverage-patterns.md

@@ -2,18 +2,21 @@
 
 ## Purpose
 
-Rules for detecting technology/library references in architecture and PRD documents, and matching them against generated skills.
+Rules for finding the technologies, libraries and frameworks an architecture document references, and for matching each one to a generated skill. The coverage stage (`coverage.md`) applies them.
 
 ---
 
-## Technology Detection in Documents
+## Skills the Document Names
 
-### Direct Name Matching
+The shared mentions helper (`skf-comention-pairs.py mentions`) finds every skill the document names, so no stage scans the document for skill names by hand. It matches each skill's name and aliases case-insensitively at word boundaries and reads each occurrence as the longest term that matches there: when both `react` and `react-dom` are skills, the text `react-dom` names `react-dom` only. A skill's aliases are:
 
-Search the architecture document for exact mentions of:
-1. Library names from generated skills (case-insensitive)
-2. Common aliases (e.g., "React" also matches "ReactJS", "react.js")
-3. Framework names that encompass libraries (e.g., "Tauri" encompasses the Tauri ecosystem)
+1. the repository and the folder it was built from (`source_repo_basename` and `source_root_basename` in the inventory), so the document's "Cognee" names a skill called `oms-cognee`;
+2. every other name a persistent fact gives it. Add a fact such as "Our documents call the postgresql skill Postgres or PG." to the workflow's `persistent_facts` (`customize.toml` says where a team or personal override goes): coverage passes both names to the helper, so the document's "PG" covers the skill, and the integrations stage pairs it;
+3. the document's own name for a skill the model matched under a common alias (below): coverage runs the helper a second time with that name added, so the integrations stage pairs that skill too.
+
+## Other Technologies
+
+The model finds the rest, the technologies whose name is no skill's name or alias, so a Missing technology still shows:
 
 ### Section-Based Detection
 
@@ -22,4 +25,10 @@ Parse document section headers for technology groupings:
 - `## Backend Core` → technologies in backend layer
 - `## AI Layer` → AI-related technologies
 
-**Mermaid Diagram Handling:** Do not parse Mermaid diagram syntax (`graph`, `flowchart`, `sequenceDiagram`, etc.) for technology detection — use only prose text (headings, paragraphs, lists, tables). If the architecture document appears to list technologies exclusively inside Mermaid diagrams, note this in the coverage results as a detection limitation and recommend the user add prose-based technology listings.
+### Common Aliases
+
+A technology the model finds this way still matches a skill under a common alias of the skill's name: "ReactJS" or "react.js" for a `react` skill, "PostgreSQL" for a `postgres` skill, "React Query" for a `react-query` skill, a framework name for the skill of a library it encompasses (e.g., "Tauri" encompasses the Tauri ecosystem). The term, as the document writes it, then becomes one of that skill's aliases (item 3 above).
+
+## Fenced Code
+
+Coverage reads only the document's prose (headings, paragraphs, lists, tables). The mentions helper skips every fenced block, so a skill the document names only inside one is in its `fenced_only` list, not `mentioned`: a Mermaid diagram (`graph`, `flowchart`, `sequenceDiagram`, etc.), and also any other code fence, such as an install command. The model's own detection skips fenced code too. When a `fenced_only` skill ends up Extra, the coverage results name it as a detection limitation and recommend listing them in prose; the helper's `fenced_blocks[]` (an `info` string of `mermaid` marks a diagram) says whether a Mermaid diagram is the cause.