bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-audit-skill/references/constituent-freshness.md

@@ -0,0 +1,91 @@
+---
+nextStepFile: 'severity-classify.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
+# This run's stage data folder: step 5 classifies the JSON saved here.
+auditDataFolder: '{forge_version}/.skf-audit/{timestamp}'
+compareConstituentHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
+  - '{project-root}/src/shared/scripts/skf-hash-content.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1c: Constituent Freshness
+
+## STEP GOAL:
+
+Audit a compose-mode stack in place of steps 2 to 4: check whether each constituent skill changed since the stack was composed, save the comparison for step 5, and write the Structural Drift section. A compose-mode stack has no source tree to re-index: its provenance entries record the constituent skills it was composed from, so a source diff would read every one of them as removed.
+
+## Rules
+
+- Run only for a compose-mode stack (`{compose_mode_stack}`, step 1 §4): every other skill runs steps 2 to 4
+- Do not classify severity (step 5) or suggest remediation (step 6)
+
+## MANDATORY SEQUENCE
+
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. 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, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-audit-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+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.
+
+### 1. Compare the Constituents' Hashes
+
+Each constituent's `metadata_hash` is the sha256 of its raw `metadata.json` bytes when the stack was composed, which the model cannot compute itself: run the helper.
+
+**Resolve `{compareConstituentHashesHelper}`** from `{compareConstituentHashesProbeOrder}`; first existing path wins. If no candidate exists, HALT with **exit 3**, `halt_reason: "helper-missing"`, phase `constituent-freshness:compare`: "`skf-hash-content.py` is not installed. Re-install SKF." A relative constituent `skill_path` (e.g. `skills/{skill-dir}/`) is project-root-relative, so the helper resolves it against `{project-root}`. Create the stage data folder first (`mkdir -p "{auditDataFolder}"`), then save the comparison in it:
+
+```bash
+uv run {compareConstituentHashesHelper} compare-constituent-hashes "{provenanceMap}" --skills-root "{project-root}" > "{auditDataFolder}/constituent-freshness.json"
+```
+
+The saved JSON, which step 5 builds its findings from:
+
+```json
+{
+  "drifted":           [{"skill_name": "...", "skill_path": "...", "stored_hash": "sha256:...", "current_hash": "sha256:..."}],
+  "fresh":             [{"skill_name": "..."}],
+  "missing":           [{"skill_name": "...", "skill_path": "...", "stored_hash": "sha256:...", "reason": "metadata-not-found|incomplete-record"}],
+  "skipped_null_hash": [{"skill_name": "..."}],
+  "stats": {"total": N, "drifted": N, "fresh": N, "missing": N, "skipped_null_hash": N}
+}
+```
+
+- `drifted[]`: a constituent whose live `metadata.json` differs from the one the stack was composed from. Step 5 grades each one HIGH.
+- `missing[]`: a constituent whose `metadata.json` cannot be found (`metadata-not-found`), or whose provenance record lacks `skill_name` or `skill_path` (`incomplete-record`). Step 5 grades each one MEDIUM.
+- `skipped_null_hash[]`: no hash was recorded when the stack was composed (a references/ cascade), so there is nothing to compare. Never drift.
+- `fresh[]`: unchanged.
+
+If the command exits non-zero, the map's constituents cannot be compared: HALT with **exit 3**, `halt_reason: "provenance-invalid"`, phase `constituent-freshness:compare`, `"path": "{provenanceMap}"`, showing its stderr. Never hash by hand: a hash made up without the helper would be a finding with no source behind it.
+
+If the stage data folder or the file cannot be written, HALT with **exit 4**, `halt_reason: "write-failed"`, phase `constituent-freshness:save`, `"path": "{auditDataFolder}/constituent-freshness.json"`.
+
+### 2. Compile the Structural Drift Section
+
+Append to {outputFile}, taking every count from `stats` (no recount):
+
+```markdown
+## Structural Drift
+
+**Comparison:** each constituent skill now vs when the stack was composed ({provenance_generated_at})
+**Method:** metadata hash comparison: a compose-mode stack has no source tree to re-index
+
+### Constituent Freshness (drifted {stats.drifted}, missing {stats.missing}, fresh {stats.fresh})
+
+| Constituent | Compose-time Hash | Current Hash |
+|-------------|-------------------|--------------|
+| {skill_name} | `{stored_hash}` | `{current_hash}` |
+
+**Missing constituents:** {skill_name} ({reason}) for each `missing[]` entry, or none.
+**Not compared (no compose-time hash):** {skill_name} for each `skipped_null_hash[]` entry, or none.
+
+## Semantic Drift
+
+**Status:** Skipped: a compose-mode stack has no source tree to compare
+```
+
+### 3. Update Report and Auto-Proceed
+
+Update {outputFile} frontmatter: append `'constituent-freshness'` to `stepsCompleted`. Once both sections have been appended, load, read fully, and execute `{nextStepFile}` (severity classification).

package/src/skf-audit-skill/references/doc-drift.md

@@ -0,0 +1,141 @@
+---
+nextStepFile: 'report.md'
+# A docs-only skill (step 1 §3) goes on to step 5 instead, which grades each
+# changed document: this comparison is the only drift such a skill has.
+classifyStepFile: 'severity-classify.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
+# This run's stage data folder: §2 saves the comparison here.
+auditDataFolder: '{forge_version}/.skf-audit/{timestamp}'
+# §2's comparison helper: the installed SKF module path first, then the src/
+# dev-checkout path.
+compareDocHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
+  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5a: Documentation Drift
+
+## STEP GOAL:
+
+Compare the content hash each tracked document had at compile time (`doc_sources` in metadata.json) with its current upstream state, and report which documents changed, which could not be reached and which were never hashed. For a skill built from source this is informational: doc drift does not move the drift score. A docs-only skill has no other drift, so for it step 5 grades each changed document.
+
+## Rules
+
+- Auto-proceed, no user interaction, and do not classify severity here. Graceful failure: a URL that cannot be fetched is `fetch_failed`, never a halt by itself (a docs-only skill halts only when it could compare no document at all, §2). For a skill built from source, never abort the audit on a failure here: skip the check with a note
+- `{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
+
+**Halt envelope.** Only a docs-only skill halts here (§2), and step 1 read no private source tree for it. 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, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-audit-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+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.
+
+### 1. Check for doc_sources
+
+Check the skill metadata loaded at init (step 1 §3, Load Skill Artifacts) for a `doc_sources` array. A docs-only skill always has one with a recorded `content_hash`: step 1 §3 stops a docs-only skill without it.
+
+**If `doc_sources` is absent:** append the section below to {outputFile}, set `doc_drift_summary = { skipped_entirely: true }`, append `'doc-drift'` to `stepsCompleted` in its frontmatter and auto-proceed to {nextStepFile}:
+
+```markdown
+## Documentation Drift
+
+No doc_sources recorded: skip doc drift check. This skill was compiled before doc tracking was available. Recompile with the current CS pipeline to enable doc drift detection.
+```
+
+**If `doc_sources` is an empty array:** do the same with `doc_drift_summary = { total_tracked: 0, skipped_entirely: false }` and this section:
+
+```markdown
+## Documentation Drift
+
+No documentation sources tracked. The `doc_sources` array is empty: no drift check to perform.
+```
+
+**Otherwise** continue to §2.
+
+### 2. Fetch and Hash Each Tracked Doc
+
+Run the script rather than fetching yourself: the stored hashes are `sha256:{hexdigest}` of each document's raw response bytes, which the model cannot compute. Resolve `{compareDocHashesHelper}` ← first existing path in `{compareDocHashesProbeOrder}` (SKILL.md On Activation checked that one exists) and, from `{project-root}`, save the comparison in the stage data folder:
+
+```bash
+mkdir -p "{auditDataFolder}"
+uv run {compareDocHashesHelper} compare-hashes "{resolved_skill_package}/metadata.json" > "{auditDataFolder}/doc-drift.json"
+```
+
+It fetches each URL whose `content_hash` is set and compares the hashes. A `null` `content_hash` is not fetched (`skipped_null_hash`: there is no baseline), and a network error, a timeout or a non-200 status is `fetch_failed`, which is not drift. The saved JSON:
+
+```json
+{
+  "changed":           [{"url": "...", "old_hash": "sha256:...", "new_hash": "sha256:..."}],
+  "unchanged":         [{"url": "..."}],
+  "fetch_failed":      [{"url": "...", "old_hash": "sha256:...", "reason": "..."}],
+  "skipped_null_hash": [{"url": "..."}],
+  "stats": {"total_tracked": N, "changed": N, "unchanged": N, "fetch_failed": N, "skipped_null_hash": N}
+}
+```
+
+**If the command exits non-zero** (exit 2 is a `doc_sources` it cannot read) or saves no JSON:
+
+- **A skill built from source:** delete the file, append the section below to {outputFile}, set `doc_drift_summary = { skipped_entirely: true }`, append `'doc-drift'` to `stepsCompleted` and auto-proceed to {nextStepFile}:
+
+  ```markdown
+  ## Documentation Drift
+
+  Doc drift check skipped: the comparison failed ({the first stderr line}).
+  ```
+
+- **A docs-only skill** (`{docs_only_skill}`): this comparison is its whole audit, so HALT with **exit 3**, phase `doc-drift:compare`, showing the first stderr line: on exit 2, `halt_reason: "provenance-invalid"` with `"path": "{resolved_skill_package}/metadata.json"` (its `doc_sources` is the record the audit compares against); otherwise `halt_reason: "helper-missing"`.
+
+**Once the comparison is saved, a docs-only skill** (`{docs_only_skill}`) is graded only on the documents it compared:
+
+- **`stats.changed` + `stats.unchanged` is 0:** no document was compared (each one failed to fetch or has no recorded hash), and a CLEAN score would vouch for documents nobody read. HALT with **exit 3**, `halt_reason: "source-unreadable"`, phase `doc-drift:compare`, `"path": "{resolved_skill_package}/metadata.json"`: "**No documentation source of `{skill_name}` could be compared.** {each `fetch_failed` URL with its `reason`, then each `skipped_null_hash` URL with `no hash recorded`}. Re-run once the documents can be reached, or re-create the skill with `[CS] Create Skill` to record their hashes."
+- **Otherwise,** record each of `stats.fetch_failed` and `stats.skipped_null_hash` that is not 0 as a warning, so the envelope shows the score leaves those documents out: `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "doc_fetch_failed: {fetch_failed}"` and `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "doc_not_hashed: {skipped_null_hash}"`.
+
+### 3. Build Drift Findings
+
+Take the four buckets (`changed[]`, `unchanged[]`, `fetch_failed[]`, `skipped_null_hash[]`) and every count from the saved JSON's `stats`: never recount.
+
+### 4. Append to Drift Report
+
+Append the `## Documentation Drift` section to {outputFile}.
+
+**When drift detected:**
+
+```markdown
+## Documentation Drift
+
+| URL | Old Hash | New Hash | Detected At |
+|-----|----------|----------|-------------|
+| {url} | `{old_hash}` | `{new_hash}` | {ISO-8601 timestamp} |
+
+**{changed} of {total_tracked} tracked documentation source(s) have changed since compile.**
+```
+
+Rows, in this order: each `changed` entry with its old and new hash; each `fetch_failed` entry, with `_(fetch failed: {reason})_` as its New Hash; each `skipped_null_hash` entry, with `_(not recorded)_` as its Old Hash and `n/a` in the last two columns. An unchanged entry gets no row, and only the `changed` rows count as drift.
+
+**When no drift detected:**
+
+```markdown
+## Documentation Drift
+
+No documentation drift detected. All {total_tracked} tracked documentation source(s) match their compile-time hashes.
+```
+
+If some entries were `fetch_failed` or `skipped_null_hash`, append a note after the main message listing those entries.
+
+### 5. Store Context and Auto-Proceed
+
+Set `doc_drift_summary` to the saved JSON's `stats` (`total_tracked`, `changed`, `unchanged`, `fetch_failed`, `skipped_null_hash`) plus `skipped_entirely: false`: report.md reads it. Append `'doc-drift'` to `stepsCompleted` in {outputFile}'s frontmatter.
+
+Display: "**Documentation drift check complete. {changed} of {total_tracked} source(s) drifted.**"
+
+Load, read the full file, then execute {nextStepFile}, or `{classifyStepFile}` for a docs-only skill (`{docs_only_skill}`), whose changed documents step 5 grades.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Only after the `## Documentation Drift` section is appended and `doc_drift_summary` is set, load and read fully the next step file.

package/src/skf-audit-skill/references/headless-contract.md

@@ -0,0 +1,29 @@
+# Headless Contract
+
+The outputs, exit codes and result envelope of skf-audit-skill. Each stage's **Halt envelope** paragraph names the exit code, `halt_reason` and phase of every HALT in it and shows the emitter command that prints it.
+
+## Outputs
+
+A run writes in `{forge_version}/`, the audited version's folder: `drift-report-{timestamp}.md`, with the run context, `drift_score` and `nextWorkflow` in its frontmatter; the JSON it was built from, in `.skf-audit/{timestamp}/`; and, from step 6, the result contract `audit-skill-result-{YYYYMMDD-HHmmss}.json` and its `audit-skill-result-latest.json` copy, written by the shared emitter. The shared clone at the recorded source path never changes: an audit of a newer upstream ref reads it from a private tree.
+
+## Exit Codes
+
+Every hard halt in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                                          |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| 0    | success              | step 7 (terminal health-check)                                                                                     |
+| 2    | input-missing        | step 1 §1: no `skill_name` supplied in headless mode (interactive prompt cannot resolve)                           |
+| 3    | resolution-failure   | On Activation (`uv`, or a helper the stages share, is missing → `helper-missing`); step 1 §1 (skill not found at resolved path: missing `SKILL.md` → `skill-not-found`; or a flat `SKILL.md` with no SKF marker in its `metadata.json` → `not-skf-output`); step 1 §2 (`forge-tier.yaml` missing: setup-forge not run → `forge-tier-missing`); step 1 §3 and §4 (the skill records nothing to audit against: a docs-only skill whose `doc_sources` records no hash, any other skill without a provenance map → `no-baseline`); step 1 §4, step 1c, step 3 §1 and, for a docs-only skill, step 5a (the provenance map or `doc_sources` cannot be read → `provenance-invalid`); step 1 §5 (source directory no longer exists / inaccessible → `source-dir-missing`); step 2 §3 (files the snapshot still lists to read after they were read by eye) and, for a docs-only skill, step 5a (no document could be compared: each failed to fetch or has no recorded hash) → `source-unreadable`; any step whose required helper resolves to no path or crashes → `helper-missing` |
+| 4    | write-failure        | step 1 §6 / step 6 §4 (drift report write failed: read-only mount, disk full, permissions denied); step 1c, step 2 §2 and §3, step 3 §1 and step 5 §2 (a file in the stage data folder cannot be written); step 6's result contract (the emitter refuses the result payload twice) → `write-failed` |
+| 6    | user-cancelled       | step 1 §1 manifest-vs-symlink gate `[X]` · step 1's upstream-drift gate `[X]` (`upstream-checkout.md`) · step 1 §7 baseline confirm gate `[X]` |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 6 prints one `SKF_AUDIT_RESULT_JSON: {...}` line on **stdout** before chaining to step 7, and every hard halt one on **stderr** with `status: "error"`. The shared emitter builds each line from the payload the stage stages in `{run_dir}`, folds in the decisions and warnings the run recorded there, stamps `run_id` and `result_path`, and checks it against `{project-root}/_bmad/skf/shared/scripts/schemas/skf-audit-result-envelope.v1.json` (`{project-root}/src/shared/scripts/schemas/skf-audit-result-envelope.v1.json` in a dev checkout), whose descriptions say what each field holds. Never type the line yourself:
+
+```
+SKF_AUDIT_RESULT_JSON: {"status":"success|error","skill_name":"…","drift_score":"CLEAN|MINOR|SIGNIFICANT|CRITICAL|null","report_path":"…|null","next_workflow":"update-skill|null","audit_ref":"…|null","upstream_moved":true|false|null,"upstream_ref":"…|null","exit_code":0,"halt_reason":null,"run_id":"…","result_path":"…|null"}
+```
+
+`next_workflow` is `"update-skill"` when CRITICAL or HIGH findings exist or when `upstream_moved` is true, otherwise `null`; pass `upstream_ref` to update-skill as `--target-ref`. `headless_decisions`, `warnings` and `error` appear when they apply. `halt_reason` is one of: `null` (success), `"input-missing"`, `"skill-not-found"`, `"not-skf-output"`, `"forge-tier-missing"`, `"no-baseline"`, `"source-dir-missing"`, `"provenance-invalid"`, `"source-unreadable"`, `"helper-missing"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.