bmad-module-skill-forge 1.8.0 → 1.9.0

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

@@ -0,0 +1,147 @@
+---
+nextStepFile: 'report.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5a: Documentation Drift
+
+## STEP GOAL:
+
+Compare documentation content hashes stored at compile time (in `doc_sources` within metadata.json) against the current upstream state. Produce a drift section that reports which tracked docs have changed, which are unreachable, and which were never hashed. This step is informational — doc drift does not affect the source code drift score.
+
+## Rules
+
+- Auto-proceed step — no user interaction
+- Graceful failure — if doc fetching fails for any URL, mark as `fetch_failed`, do not block the audit
+- Do not classify severity — doc drift is informational alongside source drift
+- If no `doc_sources` in metadata, skip with notice and auto-proceed
+- Never abort the audit pipeline on any failure in this step
+
+## MANDATORY SEQUENCE
+
+### 1. Check for doc_sources
+
+Check the skill metadata loaded at init (step 1 §3 — Load Skill Artifacts) for a `doc_sources` array.
+
+**If `doc_sources` is absent or metadata lacks the field:**
+
+Append to {outputFile}:
+
+```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.
+```
+
+Set `doc_drift_summary = { skipped_entirely: true }` in workflow context. Update {outputFile} frontmatter: append `'doc-drift'` to `stepsCompleted`. Auto-proceed to {nextStepFile}.
+
+**If `doc_sources` is present but an empty array:**
+
+Append to {outputFile}:
+
+```markdown
+## Documentation Drift
+
+No documentation sources tracked. The `doc_sources` array is empty — no drift check to perform.
+```
+
+Set `doc_drift_summary = { total_tracked: 0, skipped_entirely: false }` in workflow context. Update {outputFile} frontmatter: append `'doc-drift'` to `stepsCompleted`. Auto-proceed to {nextStepFile}.
+
+**If `doc_sources` is present and non-empty:** Continue to §2.
+
+### 2. Fetch and Hash Each Tracked Doc
+
+For each entry in `doc_sources`:
+
+1. Read `url` and `content_hash` from the entry
+2. **If `content_hash` is `null`:** Skip this entry — there is no baseline to compare against. Record it for the report as a null-hash entry. Do not attempt to fetch the URL.
+3. **If `content_hash` is non-null:** Attempt HTTP GET of the URL with a reasonable timeout (10s)
+   - **On success:** Compute `sha256:{hexdigest}` of the response body bytes (UTF-8 encoding). Compare against the stored `content_hash`. If they differ, record as drifted. If they match, record as unchanged.
+   - **On failure (network error, timeout, non-200 status):** Record the entry as `status: "fetch_failed"` with the failure reason. Do not report as drift.
+
+If URL fetching is unavailable in the current environment, skip doc drift check entirely with:
+
+```markdown
+## Documentation Drift
+
+Doc drift check skipped — URL fetching unavailable in current environment.
+```
+
+Set `doc_drift_summary = { skipped_entirely: true }` and auto-proceed.
+
+### 3. Build Drift Findings
+
+Categorize results:
+- **changed:** entries where `content_hash` differs from newly computed hash
+- **unchanged:** entries where hashes match
+- **fetch_failed:** entries where the URL could not be reached
+- **skipped_null_hash:** entries where `content_hash` was `null`
+
+Compute totals:
+- `total_tracked` = length of `doc_sources`
+- `changed` = count of drifted entries
+- `unchanged` = count of matching entries
+- `fetch_failed` = count of fetch failures
+- `skipped_null_hash` = count of null-hash entries
+
+### 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.**
+```
+
+Include rows for ALL entries, in order:
+- Drifted entries: show old and new hash
+- Unchanged entries: omit from table (only drifted entries appear)
+- Fetch-failed entries: `| {url} | \`{old_hash}\` | _(fetch failed: {reason})_ | {timestamp} |`
+- Null-hash entries: `| {url} | _(not recorded)_ | — | — |`
+
+Fetch-failed entries are clearly marked and excluded from the drift count.
+
+**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
+
+Store `doc_drift_summary` in workflow context for report.md to reference:
+
+```
+doc_drift_summary = {
+  total_tracked: N,
+  changed: N,
+  unchanged: N,
+  fetch_failed: N,
+  skipped_null_hash: N,
+  skipped_entirely: false
+}
+```
+
+Update {outputFile} frontmatter:
+- Append `'doc-drift'` to `stepsCompleted`
+
+Display: "**Documentation drift check complete. {changed} of {total_tracked} source(s) drifted. Proceeding to report generation...**"
+
+Load, read the full file, then execute {nextStepFile}.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the ## Documentation Drift section has been appended to {outputFile} and workflow context updated will you then load and read fully `{nextStepFile}` to begin final report generation.

package/src/skf-brief-skill/SKILL.md

@@ -73,17 +73,21 @@ These rules apply to every step in this workflow:
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 1 | Gather Intent | references/gather-intent.md | No (interactive) |
+| 1a | Auto-Brief Generation (auto mode only) | references/step-auto-brief.md | Yes |
+| 1b | Auto-Brief Validation (auto mode only) | references/step-auto-validate.md | No (interactive gate — headless auto-approves) |
 | 2 | Analyze Target | references/analyze-target.md | Yes |
 | 3 | Scope Definition | references/scope-definition.md | No (interactive) |
 | 4 | Confirm Brief | references/confirm-brief.md | No (confirm) |
 | 5 | Write Brief | references/write-brief.md | Yes |
 | 6 | Workflow Health Check (terminal) | references/health-check.md | Yes |
 
+Stages 1a-1b are conditional — they replace stages 2-5 when BS is invoked with the `[auto]` flag via pipeline context. The routing decision is made in stage 1 (gather-intent.md §1b). In auto mode, the chain is: gather-intent.md §1 (forge tier) → §1b (auto check) → step-auto-brief.md → step-auto-validate.md → health-check.md (on [A]pprove or [E]dit) or → confirm-brief.md → write-brief.md → health-check.md (on [R]eject).
+
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting], `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify* — when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer in place] |
+| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting], `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify* — when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer in place], `[auto]` [optional: bracket modifier passed via pipeline context — when present, BS loads the upstream brief from `brief_path` in pipeline data, enriches it with doc detection, and writes through the canonical writer; requires `brief_path` from AN's `SKF_ANALYZE_RESULT_JSON`] |
 | **Gates** | step 1: Input Gate [use args] | step 3: Confirm Gate [C] | step 4: Confirm Gate [C] |
 | **Outputs** | `skill-brief.yaml` at `{forge_data_folder}/{skill-name}/skill-brief.yaml`; final `SKF_BRIEF_RESULT_JSON` line on stdout when `{headless_mode}` is true |
 | **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; pre-supplied inputs consumed at the gates that would otherwise prompt; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise); supplying `from_brief <path>` instead routes the step 1 GATE to a ratify path that schema-validates the pre-authored brief, skips analyze-target/scope-definition, and writes through the canonical writer (overwriting in place, no `--force` needed) rather than deriving a new brief |
@@ -108,7 +112,7 @@ Every HARD HALT in this workflow exits with a stable code so headless automators
 When `{headless_mode}` is true, step 5 emits a single-line JSON envelope on **stdout** before chaining to step 6, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
-SKF_BRIEF_RESULT_JSON: {"status":"success|error","brief_path":"…|null","skill_name":"…","version":"…|null","language":"…|null","scope_type":"…|null","exit_code":0,"halt_reason":null}
+SKF_BRIEF_RESULT_JSON: {"status":"success|error","brief_path":"…|null","skill_name":"…","version":"…|null","language":"…|null","scope_type":"…|null","exit_code":0,"halt_reason":null,"mode":"auto|null"}
 ```
 
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"target-inaccessible"`, `"gh-auth-failed"`, `"write-failed"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above.
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"target-inaccessible"`, `"gh-auth-failed"`, `"write-failed"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above. `mode` is `"auto"` when BS was invoked with the `[auto]` flag (pipeline auto-brief generation), `null` otherwise (interactive or headless-without-auto).

package/src/skf-brief-skill/references/gather-intent.md

@@ -63,6 +63,20 @@ Attempt to load `{forgeTierFile}`:
 - "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
 - HALT (exit code 3, `halt_reason: "forge-tier-missing"`) — do not proceed.
 
+### 1b. Auto Mode Check
+
+**Check for `[auto]` flag:** If `[auto]` was passed as a bracket modifier in the pipeline context (e.g., `BS[auto]`), set `{auto_mode}` = true.
+
+**IF `{auto_mode}` is true:**
+
+1. **Load upstream brief path:** Read `brief_path` from the pipeline data context (passed by the forger from AN's `SKF_ANALYZE_RESULT_JSON` `brief_paths[]`). If `brief_path` is not available, HARD HALT with exit code 2 (`input-missing`): "**Auto mode requires `brief_path` in pipeline context — AN must run before BS[auto].**"
+2. **Load source repo:** Read `source_repo` from the pipeline data context (the target repo URL or path, forwarded by the forger). If not available, attempt to extract it from the upstream brief at `brief_path`.
+3. "**Auto mode activated — bypassing interactive brief workflow.**"
+4. **Route to auto-brief:** Load, read fully, then execute `references/step-auto-brief.md`. **STOP HERE** — do not continue to §2 or any subsequent section.
+
+**IF `{auto_mode}` is NOT true:**
+Continue to §2 as normal — the entire interactive flow below is unchanged.
+
 ### 2. Welcome and Explain
 
 "**Welcome to Brief Skill — the skill scoping workflow.**

package/src/skf-brief-skill/references/step-auto-brief.md

@@ -0,0 +1,171 @@
+---
+nextStepFile: 'step-auto-validate.md'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+detectDocsScript: 'src/shared/scripts/skf-detect-docs.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1a: Auto-Brief Generation
+
+## STEP GOAL:
+
+To enrich an upstream skill brief (produced by AN auto-scope) with documentation URLs discovered via `skf-detect-docs.py`, validate the enriched brief, and write it through the canonical writer. Envelope emission is deferred to step-auto-validate.md, which presents the brief for user approval before continuing. This step replaces the interactive gather-intent → analyze-target → scope-definition → confirm-brief → write-brief chain when `[auto]` mode is active.
+
+## Rules
+
+- Auto-proceed step — no user interaction required
+- This step is conditional — only loaded when `[auto]` flag is present in the pipeline context
+- Must produce the same output artifact as the interactive chain: a validated `skill-brief.yaml`
+- Doc detection is best-effort — failures do not halt the pipeline
+- Do NOT re-derive scope fields from the upstream brief — AN already set them correctly
+- Do NOT render YAML or JSON envelopes in the LLM — delegate to deterministic scripts
+
+## MANDATORY SEQUENCE
+
+### 1. Load Upstream Brief
+
+Read the upstream brief path from `{brief_path}` (passed by the forger from AN's `SKF_ANALYZE_RESULT_JSON` `brief_paths[]`).
+
+**IF `{brief_path}` is not set or the file does not exist:**
+- HARD HALT with exit code 2 (`input-missing`): "**Auto-brief requires an upstream brief — `brief_path` is missing or the file does not exist at `{brief_path}`.**"
+- Emit error envelope per §6 with `halt_reason: "input-missing"`.
+
+**Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Validate the upstream brief against the schema:
+
+```bash
+uv run {validateBriefSchemaHelper} {brief_path}
+```
+
+The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}`.
+
+- **`valid: false`** — the upstream brief is malformed. HARD HALT with exit code 2 (`input-invalid`): "**Upstream brief at `{brief_path}` is invalid: {first error message}.**" Emit error envelope per §6 with `halt_reason: "input-invalid"`.
+- **`valid: true`** — proceed with the parsed `brief` payload. Surface any non-empty `warnings[]` to the log.
+
+Extract from the parsed brief:
+- `skill_name` ← `brief.name`
+- `version` ← `brief.version`
+- `source_repo` ← `brief.source_repo`
+- `language` ← `brief.language`
+- `scope_type` ← `brief.scope.type`
+- `forge_tier` ← `brief.forge_tier`
+- `description` ← `brief.description`
+- `created` ← `brief.created`
+- `created_by` ← `brief.created_by`
+- All scope fields: `scope.include`, `scope.exclude`, `scope.notes`, `scope.rationale`, `scope.amendments`, `scope.tier_a_include`
+- Optional fields: `source_type`, `source_authority`, `doc_urls`, `target_version`, `target_ref`, `source_ref`, `scripts_intent`, `assets_intent`
+
+**Docs-only check:** If `source_type` is `docs-only` in the parsed brief, skip §2 (Run Doc Detection) and §3 (Enrich Brief with Detected Docs) — the doc URL is already in the brief's `doc_urls`. Log: "Docs-only brief — skipping repo-based doc detection. Doc URLs provided by upstream." Proceed directly to §4 (Validate Enriched Brief). All brief fields (`source_type`, `source_authority`, `doc_urls`, `scope_type`) must pass through unmodified.
+
+### 2. Run Doc Detection
+
+Invoke doc detection to discover documentation URLs for the source repo:
+
+```bash
+uv run python {project-root}/{detectDocsScript} --repo-url {source_repo}
+```
+
+`--repo-url` is always required (the script uses it for GitHub API calls). If a local clone is also available at `{local_clone_path}`, add `--local-path {local_clone_path}` to enable docs-folder scanning in addition to API-based detection.
+
+**Handle exit codes:**
+
+- **Exit 0 (found docs):** Parse the JSON output array. Each entry has `{url, detected_via, content_hash, content_type}`. Proceed to §3 with the detected docs.
+- **Exit 1 (none found):** Log: "No external documentation found — brief generated from source analysis only." Proceed to §4 with no doc enrichment.
+- **Exit 2 (error):** Log warning: "Doc detection failed — proceeding without doc enrichment." Do NOT halt — doc enrichment is best-effort. Proceed to §4 with no doc enrichment.
+
+### 3. Enrich Brief with Detected Docs
+
+For each detected doc entry, create a brief `doc_urls` entry:
+
+- `url` ← `url` (direct copy)
+- `label` ← derive from `content_type` if available:
+  - `"api-docs"` → `"API Documentation"`
+  - `"guide"` → `"Guide"`
+  - `"reference"` → `"Reference"`
+  - Otherwise derive from `detected_via`:
+    - `"homepageUrl"` → `"Homepage"`
+    - `"readme_link"` → `"README Link"`
+    - `"pages_api"` → `"GitHub Pages"`
+    - `"docs_folder"` → `"Docs Folder"`
+
+If the upstream brief already has `doc_urls`, merge the detected docs with the existing entries (deduplicate by URL — existing entries take precedence).
+
+### 4. Validate Enriched Brief
+
+Assemble the enriched brief context as a flat JSON object following the write-brief §3 contract:
+
+```json
+{
+  "name":             "{skill_name}",
+  "target_version":   "{target_version or null}",
+  "detected_version": null,
+  "source_type":      "{source_type or 'source'}",
+  "source_repo":      "{source_repo}",
+  "language":         "{language}",
+  "description":      "{description}",
+  "forge_tier":       "{forge_tier}",
+  "created":          "{created}",
+  "created_by":       "{created_by}",
+  "scope_type":       "{scope_type}",
+  "scope_include":    ["{scope.include patterns}"],
+  "scope_exclude":    ["{scope.exclude patterns}"],
+  "scope_notes":      "{scope.notes or ''}",
+  "scope_rationale":  null,
+  "scope_tier_a_include": null,
+  "scope_amendments":     null,
+  "doc_urls":         [{"url": "...", "label": "..."}],
+  "scripts_intent":   "{scripts_intent or null}",
+  "assets_intent":    "{assets_intent or null}",
+  "source_authority": "{source_authority or null}",
+  "target_ref":       "{target_ref or null}",
+  "source_ref":       "{source_ref or null}",
+  "version_resolved": "{version}"
+}
+```
+
+The `version_resolved` key pins the output to the upstream brief's version — without it, the writer's precedence logic falls through to `1.0.0` since `target_version` and `detected_version` are both null on the auto path.
+
+### 5. Write Enriched Brief
+
+**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Write the enriched brief through the canonical writer:
+
+```bash
+echo '<context-json>' | uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --from-flat
+```
+
+**On script failure (non-zero exit):**
+- Exit 1 (validation/invariant): Emit error envelope per §6 with `halt_reason: "input-invalid"`, then HARD HALT.
+- Exit 2 (I/O failure): Emit error envelope per §6 with `halt_reason: "write-failed"`, then HARD HALT.
+
+**On success:** Capture `brief_path` and `version` from the response envelope for step-auto-validate's envelope emission.
+
+### 6. Error Envelope (Canonical)
+
+Every HARD HALT in this step emits the error envelope on stderr:
+
+**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+```bash
+echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{reason}","mode":"auto"}' | \
+  uv run {emitBriefEnvelopeHelper} emit --target stderr
+```
+
+### 7. Chain to Auto-Validate
+
+Load, read fully, then execute {nextStepFile} to present the auto-brief validation gate, where the user can approve, edit, or reject the brief before the pipeline continues.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the enriched brief has been written and validated will you load and read fully {nextStepFile} to begin the auto-brief validation gate.

package/src/skf-brief-skill/references/step-auto-validate.md

@@ -0,0 +1,209 @@
+---
+nextStepFile: 'health-check.md'
+rejectTargetFile: 'confirm-brief.md'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1b: Auto-Brief Validation
+
+## STEP GOAL:
+
+To present the user with a concise summary of the auto-generated brief and offer three actions — approve, edit, or reject — before the pipeline continues. On approve or edit, the result envelope is emitted and the pipeline chains to the health check. On reject, the pipeline falls back to the interactive brief review cycle with pre-populated fields.
+
+## Rules
+
+- This step is conditional — only loaded from step-auto-brief.md when `[auto]` mode is active
+- The brief MUST already exist on disk (written by step-auto-brief §5) before this step runs
+- Do NOT render YAML or JSON envelopes in the LLM — delegate to deterministic scripts
+- Do NOT modify confirm-brief.md or write-brief.md — the [R]eject path reuses them as-is
+- The 10-line summary is always displayed, even in headless mode, for logging transparency
+
+## MANDATORY SEQUENCE
+
+### 1. Load Auto-Brief
+
+Read the brief from `{forge_data_folder}/{skill_name}/skill-brief.yaml` (written by step-auto-brief §5).
+
+**Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Validate the brief against the schema:
+
+```bash
+uv run {validateBriefSchemaHelper} {forge_data_folder}/{skill_name}/skill-brief.yaml
+```
+
+The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}`.
+
+- **`valid: false`** — HARD HALT with exit code 2 (`input-invalid`): "**Auto-brief at `{forge_data_folder}/{skill_name}/skill-brief.yaml` is invalid: {first error message}.**" Emit error envelope per §7 with `halt_reason: "input-invalid"`.
+- **`valid: true`** — proceed with the parsed `brief` payload. Surface any non-empty `warnings[]` to the log.
+
+**IF the file does not exist:**
+- HARD HALT with exit code 2 (`input-missing`): "**Auto-brief not found at `{forge_data_folder}/{skill_name}/skill-brief.yaml` — step-auto-brief must write the brief before this step runs.**" Emit error envelope per §7 with `halt_reason: "input-missing"`.
+
+Extract from the parsed brief:
+- `skill_name` ← `brief.name`
+- `version` ← `brief.version`
+- `source_repo` ← `brief.source_repo`
+- `language` ← `brief.language`
+- `scope_type` ← `brief.scope.type`
+- `scope_include` ← `brief.scope.include`
+- `scope_exclude` ← `brief.scope.exclude`
+- `forge_tier` ← `brief.forge_tier`
+- `description` ← `brief.description`
+- `doc_urls` ← `brief.doc_urls`
+
+### 2. Present 10-Line Summary
+
+Render a concise summary from the brief fields for rapid scanning:
+
+```
+Auto-Brief Summary: {skill_name}
+─────────────────────────────────
+Source:       {source_repo}
+Language:     {language}
+Scope:        {scope_type} ({N} include, {M} exclude patterns)
+Docs:         {doc_urls count} sources detected | "None detected"
+Version:      {version}
+Forge Tier:   {forge_tier}
+Quality:      90% target (deepwiki pipeline)
+Description:  "{description}"
+```
+
+Where `{N}` is the count of `scope_include` patterns and `{M}` is the count of `scope_exclude` patterns. If `doc_urls` is null or empty, display "None detected".
+
+### 3. Validation Gate
+
+**GATE: [A]pprove** — Present `[A]pprove` / `[E]dit` / `[R]eject` to user.
+
+"**Review the auto-generated brief above.**
+
+Select an action:
+  [A] Approve — accept the brief as-is and continue the pipeline
+  [E] Edit — modify specific fields before continuing
+  [R] Reject — fall back to interactive brief review with pre-populated fields"
+
+If `{headless_mode}`: auto-proceed with `[A]pprove`, log: "headless: auto-approve auto-brief".
+
+Wait for user response. Branch on the response:
+
+- `[A]` or `approve` → §4 ([A]pprove path)
+- `[E]` or `edit` → §5 ([E]dit path)
+- `[R]` or `reject` → §6 ([R]eject path)
+- Any other input → answer briefly, re-display the menu
+
+### 4. [A]pprove Path
+
+**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Emit the `SKF_BRIEF_RESULT_JSON` envelope with `mode: "auto"`:
+
+```bash
+echo '{"status":"success","brief_path":"{brief_path}","skill_name":"{skill_name}","version":"{version}","language":"{language}","scope_type":"{scope_type}","halt_reason":null,"mode":"auto"}' | \
+  uv run {emitBriefEnvelopeHelper} emit
+```
+
+Where `{brief_path}` is `{forge_data_folder}/{skill_name}/skill-brief.yaml`.
+
+Chain to {nextStepFile} (health-check.md) — load, read fully, then execute.
+
+### 5. [E]dit Path
+
+Present each brief field with its current value and accept natural language modification requests.
+
+"**Editable fields:**
+
+1. **Name:** {skill_name}
+2. **Source:** {source_repo}
+3. **Language:** {language}
+4. **Scope type:** {scope_type}
+5. **Include patterns:** {scope_include}
+6. **Exclude patterns:** {scope_exclude}
+7. **Description:** {description}
+8. **Doc URLs:** {doc_urls or "None"}
+9. **Version:** {version}
+10. **Forge tier:** {forge_tier}
+
+Tell me what to change (e.g. 'change scope type to public-api', 'add doc URL https://...')."
+
+Wait for user response. Apply changes to the brief context.
+
+**Re-write the modified brief** through the canonical writer:
+
+**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins.
+
+Assemble the modified brief context as a flat JSON object (same format as step-auto-brief §4):
+
+```bash
+echo '<modified-flat-json>' | uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --from-flat
+```
+
+The canonical writer validates the brief internally — on non-zero exit, surface the error and re-prompt for corrections. The edit loop allows multiple modifications — each write re-validates before accepting.
+
+**Re-validate the written brief** against the schema to confirm correctness:
+
+**Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins.
+
+```bash
+uv run {validateBriefSchemaHelper} {forge_data_folder}/{skill_name}/skill-brief.yaml
+```
+
+If validation fails (the writer missed a constraint), surface the error and re-prompt for corrections.
+
+Re-present the 10-line summary (§2 format) with updated values so the user can verify the change.
+
+"Updated brief written. **Select:** [A] Approve and continue · [E] Edit more · [R] Reject"
+
+- `[A]` → emit envelope per §4, chain to {nextStepFile}
+- `[E]` → repeat §5 edit loop
+- `[R]` → §6 ([R]eject path)
+
+### 6. [R]eject Path
+
+"**Falling back to interactive brief — fields pre-populated from auto-detection.**"
+
+Hydrate brief context variables from the auto-brief on disk, using the same field mapping as the ratify path in gather-intent §3.1a:
+
+- `name` ← `brief.name`; `version` ← `brief.version`; `target_version` ← `brief.target_version`
+- `target_ref` ← `brief.target_ref`; `source_ref` ← `brief.source_ref` (optional git refs; preserve when present)
+- `source_repo` ← `brief.source_repo`; `source_type` ← `brief.source_type`; `source_authority` ← `brief.source_authority`; `doc_urls` ← `brief.doc_urls`
+- `language` ← `brief.language`; `description` ← `brief.description`; `forge_tier` ← `brief.forge_tier`
+- `created` ← `brief.created`; `created_by` ← `brief.created_by`
+- `scope.type` / `scope.include` / `scope.exclude` / `scope.tier_a_include` / `scope.notes` / `scope.rationale` / `scope.amendments` ← `brief.scope.*` (preserve `tier_a_include` and the `amendments` log verbatim — do not re-derive or drop them)
+- `scripts_intent` ← `brief.scripts_intent`; `assets_intent` ← `brief.assets_intent`
+
+Set `ratify_mode: true` and `ratify_source_path: {forge_data_folder}/{skill_name}/skill-brief.yaml` in workflow context.
+
+Chain to {rejectTargetFile} (confirm-brief.md) — load, read fully, then execute. The user gets the full interactive review experience: view, adjust fields inline, revise scope via [R], or approve via [C] → write-brief.md → health-check.md.
+
+The interactive chain's write-brief.md handles its own envelope emission with `mode: null` (interactive), which is correct since the user explicitly chose to leave auto mode.
+
+### 7. Error Envelope (Canonical)
+
+Every HARD HALT in this step emits the error envelope on stderr:
+
+**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins.
+
+```bash
+echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{reason}","mode":"auto"}' | \
+  uv run {emitBriefEnvelopeHelper} emit --target stderr
+```
+
+### 8. Chain
+
+Load, read fully, then execute the appropriate next step file based on the user's choice:
+- [A]pprove or [E]dit (after final approve): {nextStepFile} (health-check.md)
+- [R]eject: {rejectTargetFile} (confirm-brief.md)
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the user has made their choice (approve, edit-then-approve, or reject) and the appropriate action has been taken (envelope emitted or context hydrated) will you load and read fully the next step file.

package/src/skf-create-skill/SKILL.md

@@ -43,6 +43,9 @@ These rules apply to every step in this workflow:
 | 3d | Component Extraction | references/component-extraction.md | Conditional |
 | 4 | Enrich | references/enrich.md | Yes |
 | 5 | Compile | references/compile.md | Yes |
+| 5a | Doc Sources | references/step-doc-sources.md | Yes |
+| 5b | Auto-Shard | references/step-auto-shard.md | Yes |
+| 5c | Doc-Rot | references/step-doc-rot.md | Yes |
 | 6 | Validate | references/validate.md | Conditional |
 | 7 | Generate Artifacts | references/generate-artifacts.md | Yes |
 | 8 | Report | references/report.md | Yes |

package/src/skf-create-skill/assets/skill-sections.md

@@ -230,6 +230,8 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   // scripts[] and assets[] — include ONLY when inventories are non-empty; omit entirely otherwise
   // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
   // "assets": [{ "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
+  // doc_sources[] — include ONLY when doc detection ran; omit if detection was skipped entirely
+  // "doc_sources": [{ "url": "https://...", "detected_via": "homepageUrl|readme_link|pages_api|docs_folder|readme_always", "content_hash": "sha256:{hex}|null", "recorded_at": "ISO-8601" }],
   "generated_by": "{quick-skill|create-skill}",
   "dependencies": [],
   "compatibility": "{semver-range}"

package/src/skf-create-skill/references/compile.md

@@ -1,5 +1,5 @@
 ---
-nextStepFile: 'validate.md'
+nextStepFile: 'step-doc-sources.md'
 skillSectionsData: 'assets/skill-sections.md'
 assemblyRulesData: 'assets/compile-assembly-rules.md'
 ---