bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-audit-skill/references/semantic-diff.md

@@ -1,6 +1,8 @@
 ---
 nextStepFile: 'severity-classify.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
+# This run's stage data folder: §4 saves the findings step 5 classifies.
+auditDataFolder: '{forge_version}/.skf-audit/{timestamp}'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -9,14 +11,14 @@ outputFile: '{forge_version}/drift-report-{timestamp}.md'
 
 ## STEP GOAL:
 
-Compare QMD knowledge context between the original skill creation and current state to detect meaning-level changes that structural diff cannot catch. This step executes ONLY at Deep tier — at Quick, Forge, and Forge+ tiers, it appends a skip notice and auto-proceeds.
+Compare what the skill documents about each export (retrieved from its QMD extraction collection) against the current source under `{source_root}` to detect meaning-level changes that structural diff cannot catch. This step executes ONLY at Deep tier: at Quick, Forge, and Forge+ tiers, it appends a skip notice and auto-proceeds.
 
 ## Rules
 
 - At Quick/Forge/Forge+ tier, skip the entire analysis — append the skip notice only
-- Focus only on semantic/meaning-level changes via QMD context — do not repeat structural findings from Step 03
+- Find meaning-level changes in the current source; QMD only retrieves what the skill says. Do not repeat structural findings from Step 03
 - Do not classify severity (Step 05)
-- Use subprocess Pattern 3 when available for QMD queries; if unavailable, query in main thread
+- Use subprocess Pattern 3 when available for §2 items 2 to 4 (the QMD query and the source reads); if unavailable, run them in the main thread
 
 ## MANDATORY SEQUENCE
 
@@ -31,7 +33,7 @@ Append to {outputFile}:
 
 **Status:** Skipped — Semantic diff requires Deep tier (current tier: {tier})
 
-Semantic analysis compares QMD knowledge context for meaning-level changes that structural diff cannot detect. To enable semantic diff, run setup with QMD available to unlock Deep tier.
+Semantic analysis checks what the skill documents (retrieved from its QMD collection) against the current source for meaning-level changes that structural diff cannot detect. To enable semantic diff, run setup with QMD available to unlock Deep tier.
 ```
 
 Update frontmatter: append `'semantic-diff'` to `stepsCompleted`
@@ -46,26 +48,24 @@ Continue to section 2.
 
 ### 2. Query Original Knowledge Context
 
-Launch a subprocess (Pattern 3 — data operations) that:
+Run item 1 in the main thread, because only the main thread can end this step, then launch a subprocess (Pattern 3, data operations) for items 2 to 4:
 1. Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`. Find the entry where `skill_name` matches `{skill_name}` AND `type` is `"extraction"`. Three cases must be handled distinctly — collapsing them into "found vs. not found" silently degrades semantic diff when a collection is registered but never indexed.
 
-   - **Registry entry missing.** Log: "No QMD extraction collection found for `{skill_name}`. Semantic diff skipped." → Auto-proceed to {nextStepFile}.
+   - **Registry entry missing.** Log: "No QMD extraction collection found for `{skill_name}`. Semantic diff skipped." Append a `## Semantic Drift` section holding `**Status:** Skipped: no QMD extraction collection is registered for {skill_name}` to {outputFile}, append `'semantic-diff'` to `stepsCompleted`, and auto-proceed to {nextStepFile}.
    - **Registry entry present but collection empty.** Run a pre-query probe — `qmd ls {collection_name}` (CLI) or the equivalent MCP call. If it reports zero files (`Files: 0 (updated never)` or an empty listing), the collection is registered but has never been indexed. Do **not** proceed to querying — queries will return nothing and the step would silently degrade.
      - Log: "QMD collection `{collection_name}` is registered but empty. Run `qmd update` to (re-)index `{collection.path}`, then re-audit for full Deep-tier semantic coverage."
      - Fall through to the **direct-content fallback** below instead of skipping outright.
    - **Registry entry present and populated.** Use the `name` field from the registry entry as the collection to query. Proceed to bullet 2.
 
-   **Direct-content fallback** (used when the collection is registered but empty): load `SKILL.md` and `references/*.md` from the audited skill, then spot-check each documented export against the current source tree under `{source_root}` using the Deep-tier AST tooling this step already requires (ast_bridge; see step 2 §1 "Deep tier"). This fallback is reachable only from Deep tier — §1 short-circuits Quick/Forge/Forge+ before §2 runs, so AST tooling is guaranteed available here. Record findings with confidence label `T1-low-fallback` rather than T2 — this is direct content inspection, not QMD-backed semantic analysis. The step's output schema is otherwise unchanged; set `qmd_collection = null` in the Semantic Drift header and annotate: "Semantic diff ran in direct-content fallback mode — QMD collection was registered but empty."
+   **Direct-content fallback** (used when the collection is registered but empty): read what the skill documents about each export from `SKILL.md` and `references/*.md` of the audited skill in place of item 2's query, then run items 3 and 4 on those claims, checking the current source under `{source_root}` with the Deep-tier AST tooling this step already requires (ast_bridge; see step 2 §1 "Deep tier"). This fallback is reachable only from Deep tier: §1 short-circuits Quick/Forge/Forge+ before §2 runs, so AST tooling is guaranteed available here. Record findings with confidence label `T1-low-fallback` rather than T2: the claims come from reading the skill's files, not from its QMD collection. The step's output schema is otherwise unchanged; set `qmd_collection = null` in the Semantic Drift header and annotate: "Semantic diff ran in direct-content fallback mode: QMD collection was registered but empty."
 
-2. Queries for knowledge context around each export documented in the skill
-3. Retrieves: usage patterns, conventions, architectural context, dependency relationships
-4. Returns structured findings to parent
-
-**If subprocess unavailable:** Query QMD in main thread.
+2. Query the collection for what the skill documents about each export (usage, conventions, dependencies, architecture): the original side
+3. For each claim, read the export's current definition and call sites under `{source_root}` at the file and line `{forge_version}/extraction-snapshot.json` records for it: the current side (an export the snapshot no longer holds is a removed export step 3 already reports: skip it)
+4. Return each claim the source no longer supports with that file:line
 
 ### 3. Compare Knowledge Context
 
-For each export in the skill, compare original context (from skill creation) against current context (from QMD):
+For each export in the skill, compare original context (from skill creation, item 2) against the current source under `{source_root}` (item 3):
 
 **Detect:**
 - **New patterns:** Usage patterns that have emerged since skill was created
@@ -76,7 +76,7 @@ For each export in the skill, compare original context (from skill creation) aga
 
 For each finding, record:
 - What changed (description)
-- Evidence (QMD reference or source citation)
+- Evidence (the current source file:line; a claim with no source line is not recorded)
 - Affected exports
 - Confidence: T2
 
@@ -87,7 +87,7 @@ Append to {outputFile}:
 ```markdown
 ## Semantic Drift
 
-**Method:** QMD knowledge context comparison (Deep tier)
+**Method:** the skill's claims (from QMD) checked against the current source (Deep tier)
 **QMD Collection:** {collection_name}
 
 ### New Patterns Detected ({count})
@@ -104,9 +104,15 @@ Append to {outputFile}:
 
 ### Dependency Shifts ({count})
 
-| Export | Original Dependencies | Current Dependencies | Change | Confidence |
-|--------|---------------------|---------------------|--------|------------|
-| {export} | {old_deps} | {new_deps} | {description} | T2 |
+| Export | Original Dependencies | Current Dependencies | Change | Evidence | Confidence |
+|--------|---------------------|---------------------|--------|----------|------------|
+| {export} | {old_deps} | {new_deps} | {description} | {evidence} | T2 |
+
+### Architectural Changes ({count})
+
+| Change | Description | Affected Exports | Evidence | Confidence |
+|--------|-------------|------------------|----------|------------|
+| {change} | {description} | {exports} | {evidence} | T2 |
 
 ### Deprecated Patterns ({count})
 
@@ -121,10 +127,13 @@ Append to {outputFile}:
 | New patterns | {count} |
 | Changed conventions | {count} |
 | Dependency shifts | {count} |
+| Architectural changes | {count} |
 | Deprecated patterns | {count} |
 | **Total Semantic Items** | {total} |
 ```
 
+Save the same rows to `{auditDataFolder}/semantic-findings.json`: step 5 classifies this file, not the tables. It is a JSON array with one object per row, `{"type": "semantic", "category", "name", "detail", "file", "line", "confidence"}`. `category` is its table's: New Patterns `pattern`, Changed Conventions `convention`, Dependency Shifts `dependency`, Architectural Changes `architecture` and Deprecated Patterns `deprecated_pattern`. `name` is the row's first cell, `detail` its description or change, `file` and `line` the current source line its evidence cites, and `confidence` the row's (T2, or T1-low-fallback).
+
 ### 5. Update Report and Auto-Proceed
 
 Update {outputFile} frontmatter — append `'semantic-diff'` to `stepsCompleted`. Once the ## Semantic Drift section (or skip notice) has been appended, load, read fully, and execute `{nextStepFile}` (severity classification).

package/src/skf-audit-skill/references/severity-classify.md

@@ -1,10 +1,21 @@
 ---
-nextStepFile: 'step-doc-drift.md'
+nextStepFile: 'doc-drift.md'
+# A docs-only skill reaches this step after step 5a, so it goes on to the
+# report.
+reportStepFile: 'report.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
-severityRulesFile: '{severityRulesPath}'
+# This run's stage data folder, where the earlier steps saved the helpers'
+# JSON; this step writes the findings and their classification beside it.
+auditDataFolder: '{forge_version}/.skf-audit/{timestamp}'
 severityClassifyProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-severity-classify.py'
   - '{project-root}/src/shared/scripts/skf-severity-classify.py'
+# Every HALT after the [C] of upstream-checkout.md closes the private tree with it.
+sourceTreeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-source-tree.py'
+  - '{project-root}/src/shared/scripts/skf-source-tree.py'
+# §3: this skill's renderer of the severity tables, from the skill root.
+renderDriftTablesScript: 'scripts/render-drift-tables.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -13,114 +24,117 @@ severityClassifyProbeOrder:
 
 ## STEP GOAL:
 
-Grade every drift finding from Steps 03 and 04 by severity (CRITICAL/HIGH/MEDIUM/LOW), derive the overall drift score, and produce a categorized findings table with confidence-tier labels.
+Grade every drift finding from Steps 03 and 04 (step 1c for a compose-mode stack, step 5a for a docs-only skill) by severity (CRITICAL/HIGH/MEDIUM/LOW), derive the overall drift score, and produce a categorized findings table with confidence-tier labels.
 
 ## Rules
 
 - Only classify existing findings — do not discover new drift items or suggest remediation
-- Reading each change and assigning its `type` / `category` is judgment; mapping those to a severity, reducing the set to the drift score, and counting per level are deterministic and delegated to the shared helper so the classification cannot drift from {severityRulesFile} between runs
-- The confidence tier (T1 / T1-low / T2) travels with each finding from Steps 03/04 — the helper never touches it
+- Build the findings from the JSON the earlier steps saved, never from the report's tables: the helper projects each saved source into one finding per item, with its type, file, line, confidence and detail, and fixes every category the source decides. Judgment is left for the categories a finding leaves open (`category_choices`) and the ambiguous names
+- Mapping each type and category to a severity, reducing the set to the drift score and counting per level have one answer each: the helper does them with its rule table, which states the rules of the bundled `references/severity-rules.md` (`--rules` prints it), so the grades cannot change between runs
+- The confidence tier (T1 / T1-low / T2) travels with each finding from Steps 03/04 unchanged: the helper never touches it
+- A provenance label difference (step 3's **Provenance label differences (not drift)** table) is never a finding: do not classify it, count it or let it move the drift score
+- `{docs_only_skill}` is the `docs_only_skill` value step 1 §6 wrote into {outputFile}'s frontmatter: read it there, not from memory, so a compacted session still takes the docs-only route
 
 ## MANDATORY SEQUENCE
 
-### 1. Collect and Categorize Findings
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. When `{source_tree}` is set (the [C] of `upstream-checkout.md`), first run `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` and go on whatever it prints. In headless mode, stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "skill_name": "{skill_name}", "report_path": "{outputFile}"}`, adding `"path"` when the halt names one, and `"drift_score"` once §2 saved the classification, then run:
 
-Gather every drift item already recorded in the report:
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-audit-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
 
-**From ## Structural Drift (Step 03):** added, removed, changed, and moved exports (plus any Script/Asset Drift rows).
-**From ## Semantic Drift (Step 04, Deep tier only):** new patterns, changed conventions, dependency shifts, deprecated patterns.
+Display the line it prints, then stop with the halt's exit code. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
 
-For each finding, read {severityRulesFile} and assign the two interpretive fields the rules key on — this is the judgment step, where the nuance of the change lives:
+### 1. Build the Findings File
 
-- `type`: `removed` / `added` / `changed` / `moved` / `renamed` / `deprecated` / `semantic`
-- `category`: what the change is about — e.g. `export`, `module`, `class`, `interface`, `signature`, `parameter_count`, `return_type`, `inheritance`, `internal_helper`, `default_value`, `required_parameter`, `implementation`, `optional_parameter`, `function` (for a move), or a LOW bucket (`style`, `convention`, `comment`, `documentation`, `whitespace`, `test`, `private`, `internal`). The category carries the interpretation: a removed helper referenced in a documented pattern is `internal_helper` (→ HIGH); a new private function is `private` (→ LOW).
+**Resolve `{severityClassifyHelper}`** from `{severityClassifyProbeOrder}`; first existing path wins (SKILL.md On Activation checked that one exists).
 
-Build one JSON array of `{type, category, detail, confidence, file, line}` objects — carry each finding's `confidence`, `file`, `line`, and human `detail` through untouched.
+Print the rule table once. It lists the only type and category pairs the helper grades, each with the rule it implements:
 
-### 2. Classify, Score, and Count (deterministic)
+```bash
+uv run {severityClassifyHelper} --rules --format markdown
+```
 
-Mapping type/category to a severity, reducing the severities to an overall drift score, and counting per level each have exactly one correct answer for a given finding set — delegate them to the shared helper, which encodes {severityRulesFile} directly.
+Project the JSON the earlier steps saved into the findings file:
 
-**Resolve `{severityClassifyHelper}`** from `{severityClassifyProbeOrder}`; first existing path wins.
+```bash
+uv run {severityClassifyHelper} --from-diff "{auditDataFolder}/structural-diff.json" --file-drift "{auditDataFolder}/file-drift.json" --semantic "{auditDataFolder}/semantic-findings.json" -o "{auditDataFolder}/findings.json"
+```
 
-Pipe the findings array from §1 to the helper on stdin:
+A compose-mode stack has no structural diff: step 1c saved its constituents' freshness instead, so its command projects that file alone:
 
 ```bash
-echo '{findings_json}' | uv run {severityClassifyHelper} -
+uv run {severityClassifyHelper} --constituents "{auditDataFolder}/constituent-freshness.json" -o "{auditDataFolder}/findings.json"
 ```
 
-Parse the emitted JSON:
+A docs-only skill (`{docs_only_skill}`) has neither: step 5a saved its documents' comparison, so its command projects that file alone:
 
-```json
-{
-  "status": "ok",
-  "drift_score": "CLEAN|MINOR|SIGNIFICANT|CRITICAL",
-  "total_findings": N,
-  "by_severity": {"CRITICAL": N, "HIGH": N, "MEDIUM": N, "LOW": N},
-  "findings": [ {"type": "...", "category": "...", "detail": "...", "confidence": "...", "severity": "CRITICAL|HIGH|MEDIUM|LOW"} ]
-}
+```bash
+uv run {severityClassifyHelper} --doc-drift "{auditDataFolder}/doc-drift.json" -o "{auditDataFolder}/findings.json"
 ```
 
-Consume `by_severity`, `drift_score`, and each finding's assigned `severity` directly — do not recount or recompute the score in prose.
-
-**If `uv`/the helper cannot execute** (e.g. claude.ai web): fall back to classifying in the main thread — apply {severityRulesFile}'s severity levels to each finding's type/category, then reduce with its Overall Drift Score table (CLEAN = no findings; MINOR = LOW only; SIGNIFICANT = any MEDIUM/HIGH, no CRITICAL; CRITICAL = any CRITICAL present).
+The helper writes one finding per item, with its `type`, `category`, `name`, `detail`, `file`, `line` and `confidence` (and `source_library` for a stack): each export the diff lists, each Script/Asset Drift file (step 3 §4b), each drifted or missing constituent (step 1c), each Semantic Drift row (step 4) and each changed document of a docs-only skill (step 5a). A stage that did not run saved no file (no `file_entries`, a tier without semantic diff): the helper skips that file, and its summary line's `sources` says which files it read. Exit 1 saved nothing: an `error` that starts `Cannot write output` is a failed write (§2), and any other names the file to fix before running the command again.
 
-### 3. Compile Severity Classification Section
+Then edit `{auditDataFolder}/findings.json`, keeping every field the helper wrote unless a rule below changes it:
 
-**Rollup inherits from step 3.** If step 3 §5 collapsed ≥ 10 same-kind findings into a single rollup row (deleted source file, renamed module, entire package tree removed), carry that rollup through to the matching severity table as one row — do not re-expand it here. Keep the 6-column severity table shape; the rollup encodes root cause, count, and representative symbols **inline in the `Finding` cell** rather than adding columns, so rollup and per-item rows render cleanly in one table. Changed-signature and cross-file findings remain per-row; they were not eligible for rollup in step 3 and are not eligible here.
+1. **Open categories.** A finding with `category_choices` holds its first choice as `category`: replace it with the choice that names the change when another fits better. A removed export stays `export` unless it is an internal helper the skill's documented patterns reference (`internal_helper`); a changed signature takes the choice that names what changed (for example `required_parameter` for a new required parameter, `style` or `whitespace` for a reformatted one).
+2. **Ambiguous names.** A finding with `ambiguous_name: true` (step 3's Ambiguous Names table) stays `removed` or `added`, unless you judge a removed and an added finding of one name to be one export that moved. Then record the move as the helper would: the added finding becomes `{type: "moved", category: "export", detail: "moved from {removed file:line} to {file:line}"}` without `ambiguous_name`, and the removed finding is deleted.
 
-**Rollup row form (any severity table):**
+Keep one finding per item: a rollup belongs to the tables §3 renders, after classification.
 
-| # | Finding | Type | Detail | Location | Confidence |
-|---|---------|------|--------|----------|------------|
-| N | {root cause} (×{Count}; rep: `{sym1}`, `{sym2}`, `{sym3}`, …) | {structural/semantic} | {shared detail} | {root-cause path} | {T1/T2} |
+### 2. Classify, Score, and Count (deterministic)
 
-Append to {outputFile}, filling the counts from `by_severity` and each finding's assigned `severity`:
+Classify the findings file:
 
-```markdown
-## Severity Classification
+```bash
+uv run {severityClassifyHelper} "{auditDataFolder}/findings.json" -o "{auditDataFolder}/severity.json"
+```
 
-**Overall Drift Score: {drift_score}**
+- **Exit 0:** the helper saved the result and printed one line with `drift_score`, `total_findings`, `total_items` and `by_severity`.
+- **Exit 1 with `problems[]`:** some findings fit no rule. Each problem names the finding (its `index` in the findings file), its `type` and `category`, and why. Re-categorize exactly those findings (a pair from the rule table, a category from the finding's `category_choices`, an ambiguous finding back to `removed` or `added`), then run the command again.
+- **Exit 1 without `problems[]`:** nothing was saved. An `error` that starts `Cannot write output` (here or in §1) is a failed write: HALT with **exit 4**, `halt_reason: "write-failed"`, phase `severity-classify:save`, `"path": "{auditDataFolder}"`. Any other `error` names a findings file the helper could not read: fix it, then run the command again.
+- **Exit 2:** a usage error in the command itself.
 
-### CRITICAL ({by_severity.CRITICAL})
+The saved result, CRITICAL first:
 
-| # | Finding | Type | Detail | Location | Confidence |
-|---|---------|------|--------|----------|------------|
-| 1 | {finding} | {structural/semantic} | {detail} | {file}:{line} | {T1/T2} |
+```json
+{
+  "status": "ok",
+  "drift_score": "CLEAN|MINOR|SIGNIFICANT|CRITICAL",
+  "total_findings": N,
+  "total_items": N,
+  "added_export_count": N,
+  "by_severity": {"CRITICAL": N, "HIGH": N, "MEDIUM": N, "LOW": N},
+  "findings": [ {"type": "...", "category": "...", "name": "...", "detail": "...", "file": "...", "line": N, "confidence": "...", "severity": "CRITICAL|HIGH|MEDIUM|LOW", "rule": "..."} ]
+}
+```
 
-### HIGH ({by_severity.HIGH})
+Consume `drift_score`, `by_severity`, the totals and each finding's `severity` directly: do not recount or recompute the score in prose. `total_findings` counts the findings (the rows), and `by_severity` sums to `total_items`.
 
-| # | Finding | Type | Detail | Location | Confidence |
-|---|---------|------|--------|----------|------------|
-| 1 | {finding} | {structural/semantic} | {detail} | {file}:{line} | {T1/T2} |
+### 3. Compile Severity Classification Section
 
-### MEDIUM ({by_severity.MEDIUM})
+Render the section from the saved classification, never by hand. `{renderDriftTablesScript}` resolves relative to the skill root; from `{project-root}`, run:
 
-| # | Finding | Type | Detail | Location | Confidence |
-|---|---------|------|--------|----------|------------|
-| 1 | {finding} | {structural/semantic} | {detail} | {file}:{line} | {T1/T2} |
+```bash
+uv run {renderDriftTablesScript} severity "{auditDataFolder}/severity.json"
+```
 
-### LOW ({by_severity.LOW})
+It prints the section's tables (`--help` lists them). A rollup changes no count: the headings and the summary come from the JSON.
 
-| # | Finding | Type | Detail | Location | Confidence |
-|---|---------|------|--------|----------|------------|
-| 1 | {finding} | {structural/semantic} | {detail} | {file}:{line} | {T1/T2} |
+Append to {outputFile}:
 
-### Classification Summary
+```markdown
+## Severity Classification
 
-| Severity | Count |
-|----------|-------|
-| CRITICAL | {by_severity.CRITICAL} |
-| HIGH | {by_severity.HIGH} |
-| MEDIUM | {by_severity.MEDIUM} |
-| LOW | {by_severity.LOW} |
-| **Total** | {total_findings} |
+{what the command printed, unchanged}
 ```
 
+When the command exits non-zero, its JSON `error`, else its first stderr line, says what it could not read: write `Severity tables not rendered: {error}` in place of its output and go on, since §4 and step 6 read the saved classification, not these tables.
+
 ### 4. Update Report and Auto-Proceed
 
 Update {outputFile} frontmatter:
 - Append `'severity-classify'` to `stepsCompleted`
 - Set `drift_score` to `{drift_score}` from the helper
 
-Once the ## Severity Classification section has been appended with all findings classified, load, read fully, and execute `{nextStepFile}` (documentation drift).
+Once the ## Severity Classification section has been appended with all findings classified, load, read fully, and execute `{nextStepFile}` (documentation drift), or `{reportStepFile}` for a docs-only skill (`{docs_only_skill}`), whose step 5a already ran.

package/src/skf-audit-skill/references/severity-rules.md

@@ -4,6 +4,8 @@
 
 ## Severity Levels
 
+Each line below is one rule of `skf-severity-classify.py`, which grades a finding by its type and category: `--rules` prints the pairs each line accepts.
+
 ### CRITICAL — Breaking Changes
 - Removed or renamed public exports (functions, classes, types)
 - Changed function signatures (parameter count, parameter types, return type)
@@ -17,6 +19,8 @@
 - Changed default parameter values that affect documented behavior
 - New required parameters added to documented functions
 - Deprecated APIs still documented as current in skill
+- Constituent skills changed since the stack was composed (compose-mode stacks)
+- Changed documentation sources of a docs-only skill (doc drift)
 - **Impact:** Skill is incomplete or contains outdated guidance
 
 ### MEDIUM — Moderate Drift
@@ -25,12 +29,15 @@
 - New public exports not in skill (1-3 new exports)
 - Moved functions between files (same API, different location)
 - Changed internal implementation patterns documented in skill conventions
+- Added or changed script, asset or doc files (Script/Asset Drift)
+- Constituent skills that can no longer be found (compose-mode stacks)
 - **Impact:** Skill is functional but not fully current
 
 ### LOW — Minor Drift
 - Style or convention changes (formatting, naming patterns)
 - Comment or documentation changes in source
 - Whitespace or structural reorganization
+- Line-only changes (same export and file, only the line number changed)
 - New private/internal functions not affecting public API
 - Test file changes
 - **Impact:** Cosmetic — skill remains accurate for practical use
@@ -46,9 +53,11 @@
 
 ## Confidence Tier Labels
 
-| Label  | Source                           | Reliability                             |
-|--------|----------------------------------|-----------------------------------------|
-| T1     | AST extraction (ast-grep)        | High — structural truth                 |
-| T1-low | Text pattern matching (no AST)   | Moderate — pattern-based                |
-| T2     | QMD semantic context             | High — evidence-backed temporal context |
-| T3     | External documentation reference | Variable — secondary source             |
+| Label  | Source                                                         | Reliability                             |
+|--------|----------------------------------------------------------------|-----------------------------------------|
+| T1     | An ast-grep match (`extraction_method: ast-grep`), at any tier | High: structural truth                  |
+| T1-low | Read by eye (`extraction_method: source-read`), at any tier    | Moderate: read, not matched by ast-grep |
+| T2     | Deep-tier semantic diff: a skill claim checked in the source   | High: cites the current source line     |
+| T3     | External documentation reference                               | Variable: secondary source              |
+
+A label names the tool that produced an export, not the forge tier: Quick tier reads every export by eye, and at Forge, Forge+ and Deep an export is read by eye when ast-grep cannot parse its file, a rule misses it, or its file is read instead of matched. A difference between the provenance map's label and the re-index label is not drift and has no severity.