bmad-module-skill-forge 0.10.0 → 1.0.0-rc.3

package/release-audits/v1.0.0-launch-audit.md

@@ -0,0 +1,207 @@
+---
+title: v1.0.0 Launch Audit
+description: Pre-flight gate audit of every must-have launch-checklist item, with known pre-flight gap dispositions, before the v1.0.0-rc.1 cut.
+---
+
+## Metadata
+
+- **Date:** 2026-04-23
+- **Responder:** Armel (@armelhbobdad) — Claude Opus 4.7 (1M context)
+- **Baseline SHA:** [`5e407a2`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/5e407a2e69765849108fe6feeef8644542564f7a) — PR #195 merge closing Epic 4 (Stories 4.1 + 4.2 + code-review patches)
+- **Working branch:** `feat/v1-readiness-audit` (fresh branch from `origin/main` at baseline SHA)
+- **Scope:** 10 must-have launch-checklist bullets × 10 pre-flight backlog items (H1–H10) × 8 rollback playbook hardening items (R1–R8)
+- **Epic 4 precondition verification:** `git log main --grep='Story 4' --oneline` returns four commits: `41ccf35` (Story 4.2 patches), `84affc3` (Story 4.2), `e597825` (Story 4.1 patches), `4d0c618` (Story 4.1) — all present on `main` per Epic 4 retro Commitment 1.
+
+## Epic 5.1 AC Verification Matrix
+
+| #   | Bullet                                                                          | AC reference           | Expected artifact                                                                            | Status | Evidence                                                                                                                                                                                                                                                                            |
+| --- | ------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `docs/STABILITY.md` exists defining v1.0.0 public API contract                  | Story 5.1 AC 4         | `docs/STABILITY.md` with `## Covered Surfaces` + 4 sibling H2s; STABLE banner                | ✓      | `grep -c '^## Covered Surfaces' docs/STABILITY.md` → `1`; `## Covered Surfaces` H2 at `docs/STABILITY.md:10`; banner at `docs/STABILITY.md:6` flipped to `STABLE` per AC 14 (this story, Task 7)                                                                                    |
+| 2   | `CHANGELOG.md` has a hand-curated v1.0.0 entry added at the top                 | Story 5.1 AC 5 + AC 13 | `## [1.0.0] - TBD` between `[Unreleased]` and `[0.10.0]`                                     | ✓      | Insertion in `CHANGELOG.md` at lines 7–67 per AC 13 (this story, Task 6)                                                                                                                                                                                                            |
+| 3   | `README.md` install instructions verified via `npm pack` + clean-dir smoke test | Story 5.1 AC 6         | `npx <tarball> --version` + piped `install` both succeed                                     | ✓      | See § Install Smoke Test Transcript below (Task 10)                                                                                                                                                                                                                                 |
+| 4   | `package.json` `repository` field populated                                     | Story 5.1 AC 7         | `{"type":"git","url":"git+https://github.com/armelhbobdad/bmad-module-skill-forge.git"}`     | ✓      | `jq .repository package.json` at `package.json:24-27` returns the above object                                                                                                                                                                                                      |
+| 5   | All advertised CLI flags documented in `--help` output and `docs/`              | Story 5.1 AC 8         | Zero per-subcommand flags; STABILITY contract matches code                                   | ✓      | `grep -n 'options: \[\]' tools/cli/commands/*.js` → 4 hits (install/update/status/uninstall); zero `--headless\|--batch\|--purge\|--allow-workspace-drift` hits in `tools/cli/`; matches `docs/STABILITY.md:18-21` contract                                                         |
+| 6   | `release.yaml` on `main` + alpha cut history                                    | Story 5.1 AC 9         | Active workflow; `v0.10.1-alpha.0` tag and tarball on npm                                    | ✓      | `gh api .../actions/workflows` returns `{"name":"Release","path":".github/workflows/release.yaml","state":"active"}`; `git tag -l 'v0.10.1-alpha.*'` → `v0.10.1-alpha.0`; alpha cut SHA `2a57dcbd` (Story 3.2, 2026-04-21)                                                          |
+| 7   | npm Trusted Publisher registered for this repo                                  | Story 5.1 AC 9         | OIDC publish works; registered via org/repo/workflow/environment 4-tuple                     | ✓      | `npm view bmad-module-skill-forge dist-tags --json` → `{"latest":"0.10.0","alpha":"0.10.1-alpha.0"}`; alpha SLSA L2 provenance present; `release.yaml` workflow state `active` — combination proves OIDC-through-TP path                                                            |
+| 8   | `release` GitHub Environment with required reviewer                             | Story 5.1 AC 9         | `protection_rules` includes `required_reviewers`                                             | ✓      | `gh api .../environments/release` returns `protection_rules: [{type: "required_reviewers", reviewers: [{type: "User", name: "armelhbobdad"}]}, {type: "branch_policy", reviewers: []}]`                                                                                             |
+| 9   | Branch protection on `main` active with required status checks                  | Story 5.1 AC 9         | Ruleset `Default` is `active`, targets `branch`, has non-empty `required_status_checks` list | ✓      | Ruleset id `13855503` (name-based lookup `name=="Default"`) is `enforcement: "active"`, `target: "branch"`; 7 required contexts: `prettier`, `eslint`, `markdownlint`, `validate (ubuntu-latest)`, `validate (windows-latest)`, `python (ubuntu-latest)`, `python (windows-latest)` |
+| 10  | `docs/RELEASING.md` rollback playbook exists                                    | Story 5.1 AC 9         | `## Rollback Playbook` + 7 `### Scenario [A-G]` H3s                                          | ✓      | `grep -c '^## Rollback Playbook$' docs/RELEASING.md` → `1`; `grep -c '^### Scenario [A-G] —' docs/RELEASING.md` → `7`; H3s at lines 196 / 228 / 255 / 279 / 311 / 368 / 429 (post-R4/R5/R6 inserts)                                                                                 |
+
+## Pre-Flight Backlog Dispositions (H1–H10)
+
+| Item | One-line title                                                              | Label                | Rationale                                                                                                                                                                                                                                                                   | Link                                                                                                                    |
+| ---- | --------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| H1   | `tools/cli/commands/install.js:23-26` silent-exit-0 on `{success: false}`   | FIXED-IN-THIS-STORY  | Added explicit `else { console.error(...); process.exit(1); }` per Story 5.1 AC 10 + Task 4 — falsy `result.success` now exits 1 with a stderr-routed diagnostic                                                                                                            | [deferred-work.md → Deferred from: code review of 2-3](../_bmad-output/implementation-artifacts/deferred-work.md)       |
+| H2   | `package.json.main` side-effectful entrypoint                               | ACCEPTED-AS-INTERNAL | `docs/STABILITY.md:24-28` (Path B) documents this as `@internal`; no programmatic export surface in the v1.0.0 contract, so the side-effect at `require('bmad-module-skill-forge')` is not a public promise and not subject to SemVer                                       | [`docs/STABILITY.md:24-28`](./STABILITY.md)                                                                             |
+| H3   | `.github/workflows/release.yaml:115` unanchored `sed` on `marketplace.json` | FIXED-IN-THIS-STORY  | Replaced with `jq --arg v "$VERSION" '.plugins[0].version = $v'` + temp-file + atomic rename + sanity check, per Story 5.1 AC 11 + Task 5                                                                                                                                   | [deferred-work.md → Deferred from: code review of 3-1](../_bmad-output/implementation-artifacts/deferred-work.md)       |
+| H4   | Starlight sidebar does not surface `STABILITY.md` / `RELEASING.md`          | FIXED-IN-THIS-STORY  | Appended `{ label: 'Stability', slug: 'stability' }` + `{ label: 'Releasing', slug: 'releasing' }` to `website/astro.config.mjs` Reference bucket per Story 5.1 AC 12 + Task 9                                                                                              | [deferred-work.md → Deferred from: code review of 1-2 / 2-3](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| H5   | `CHANGELOG.md` missing hand-curated `## [1.0.0]` entry                      | FIXED-IN-THIS-STORY  | Inserted `## [1.0.0] - TBD` section with `v1-0-0-changelog-draft.md` body between lines 5 and 7, and added `(pre-v0.3.0 tag, never published)` parenthetical to the dangling `Revert "0.2.0"` line, per Story 5.1 AC 5 / AC 13 + Task 6                                     | [deferred-work.md → 2-2](../_bmad-output/implementation-artifacts/deferred-work.md)                                     |
+| H6   | `docs/STABILITY.md:6` DRAFT banner                                          | FIXED-IN-THIS-STORY  | Replaced DRAFT banner with `STABLE — locked at v1.0.0. Amendments follow the "Changes to This Contract" section below.` per Story 5.1 AC 14 + Task 7                                                                                                                        | [`docs/STABILITY.md:6`](./STABILITY.md)                                                                                 |
+| H7   | `0.10.1-alpha.0` CHANGELOG `closes [#11]` / `[#12]` pollution               | NOT-APPLICABLE       | The pollution lived in the immutable `v0.10.1-alpha.0` tarball and in the orphaned commit `2a57dcbd`; current `main`'s `CHANGELOG.md` does NOT contain those refs (`grep -c 'closes \[#1[12]\]' CHANGELOG.md` → `0`). Alpha tarball is historical / immutable; no repo edit | [Epic 3 retro](../_bmad-output/implementation-artifacts/epic-3-retro-2026-04-21.md)                                     |
+| H8   | `docs/RELEASING.md` missing `### Cutting v1.0.0-rc.1` hand-bump procedure   | FIXED-IN-THIS-STORY  | Authored new H3 section under `## Rollback Playbook` umbrella (last H3, after `### Baseline snapshots`) with the same five-element shape (Trigger / CLI / Outcome / Constraints / Verification) as Scenarios A–G, per Story 5.1 AC 15 + Task 8                              | [`docs/RELEASING.md` § Cutting v1.0.0-rc.1](./RELEASING.md)                                                             |
+| H9   | `prevent_self_review: false` on `release` env + admin ruleset bypass        | DEFERRED-POST-V1     | Solo-maintainer repo today; both flips happen together at second-maintainer onboarding. Standing flag with no fire date                                                                                                                                                     | [Epic 3 retro standing flag + `deferred-work.md` 1-2](../_bmad-output/implementation-artifacts/deferred-work.md)        |
+| H10  | `CONTRIBUTING.md` → `docs/` anchor validator coverage                       | DEFERRED-POST-V1     | Pre-existing tooling gap; not introduced by any Epic 1–4 story; captured as a CI-as-enforced-gate candidate for a dedicated post-v1.0.0 tooling story                                                                                                                       | [Epic 4 retro + `deferred-work.md`](../_bmad-output/implementation-artifacts/deferred-work.md)                          |
+
+## Rollback Playbook Hardening Dispositions (R1–R8)
+
+| Item | One-line title                                            | Label                 | Rationale                                                                                                                                                            | Link                                                                                                 |
+| ---- | --------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| R1   | Baseline `jq` filter GET-vs-PUT shape                     | DEFERRED-POST-V1      | Requires a round-trip restore drill to validate against the live ruleset; not suitable for a story authoring pass                                                    | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R2   | Scenario G ghost workflows detection                      | DEFERRED-POST-V1      | Requires augmenting detection with `git ls-tree` check; bundled into a post-v1.0.0 ops story                                                                         | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R3   | Scenario G `gh workflow enable` admin permission          | DEFERRED-POST-V1      | Couples with H9 (second-maintainer onboarding); dormant today                                                                                                        | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R4   | Scenario A npm-`dist-tags` CDN cache lag caveat           | BUNDLED-IN-THIS-STORY | Added as a blockquote callout in `docs/RELEASING.md` Scenario A (near the `npm view … dist-tags` command) per Story 5.1 AC 16 + Task 8                               | [`docs/RELEASING.md` Scenario A](./RELEASING.md)                                                     |
+| R5   | Scenario C npm-clock-vs-local-clock caveat for 72h window | BUNDLED-IN-THIS-STORY | Added as inline sentence in Scenario C (72h-window paragraph) directing responders to compute the boundary from `time.modified` per Story 5.1 AC 16 + Task 8         | [`docs/RELEASING.md` Scenario C](./RELEASING.md)                                                     |
+| R6   | Scenario C "zero downloads" stats-lag caveat              | BUNDLED-IN-THIS-STORY | Added as blockquote callout on the "zero downloads, zero dependents" criterion directing responders to treat C as B in the first 24–48h per Story 5.1 AC 16 + Task 8 | [`docs/RELEASING.md` Scenario C](./RELEASING.md)                                                     |
+| R7   | Scenario D tag-protection hardening                       | DEFERRED-POST-V1      | Speculative; no tag-protection rule exists today                                                                                                                     | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+| R8   | Scenario F 2FA-degraded account-recovery variant          | DEFERRED-POST-V1      | Incident-response design; belongs with Scenario F hardening post-v1.0.0                                                                                              | [`deferred-work.md` → code review of 4-1](../_bmad-output/implementation-artifacts/deferred-work.md) |
+
+## External Verification Transcripts
+
+Live outputs collected during Task 2 of Story 5.1 dev (2026-04-23).
+
+### `release.yaml` on `main` — workflow state
+
+```console
+$ gh api repos/armelhbobdad/bmad-module-skill-forge/actions/workflows \
+    --jq '.workflows[] | select(.path==".github/workflows/release.yaml") | {name, state, path}'
+{"name":"Release","path":".github/workflows/release.yaml","state":"active"}
+```
+
+### `release` GitHub Environment protection rules
+
+```console
+$ gh api repos/armelhbobdad/bmad-module-skill-forge/environments/release \
+    --jq '{name, protection_rules: [.protection_rules[] | {type, reviewers: ([.reviewers // [] | .[] | {type, name: .reviewer.login // .reviewer.name}])}]}'
+{"name":"release","protection_rules":[{"reviewers":[{"name":"armelhbobdad","type":"User"}],"type":"required_reviewers"},{"reviewers":[],"type":"branch_policy"}]}
+```
+
+### Branch protection ruleset for `main` — enforcement + required status checks
+
+```console
+$ RULESET_ID=$(gh api repos/armelhbobdad/bmad-module-skill-forge/rulesets \
+    --jq '.[] | select(.name=="Default") | .id')
+$ echo "$RULESET_ID"
+13855503
+
+$ gh api "repos/armelhbobdad/bmad-module-skill-forge/rulesets/$RULESET_ID" \
+    --jq '{id: .id, target, enforcement, rule_types: [.rules[].type]}'
+{"enforcement":"active","id":13855503,"rule_types":["deletion","non_fast_forward","pull_request","code_quality","required_status_checks"],"target":"branch"}
+
+$ gh api "repos/armelhbobdad/bmad-module-skill-forge/rulesets/$RULESET_ID" \
+    --jq '[.rules[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context]'
+["prettier","eslint","markdownlint","validate (ubuntu-latest)","validate (windows-latest)","python (ubuntu-latest)","python (windows-latest)"]
+```
+
+### npm dist-tags + alpha attestation
+
+```console
+$ npm view bmad-module-skill-forge dist-tags --json
+{
+  "latest": "0.10.0",
+  "alpha": "0.10.1-alpha.0"
+}
+
+$ npm view bmad-module-skill-forge@0.10.1-alpha.0 --json | jq '.dist.attestations // "absent"'
+{
+  "url": "https://registry.npmjs.org/-/npm/v1/attestations/bmad-module-skill-forge@0.10.1-alpha.0",
+  "provenance": {
+    "predicateType": "https://slsa.dev/provenance/v1"
+  }
+}
+
+$ git tag -l 'v0.10.1-alpha.*'
+v0.10.1-alpha.0
+```
+
+The alpha SLSA L2 provenance confirms that Story 3.2's alpha cut (`2a57dcbd`, 2026-04-21) published through the registered OIDC Trusted Publisher path. The canonical four-field TP match (org / repo / workflow filename / environment) is not visible via public API — a successful attested publish IS the live proof of registration.
+
+### Story 4.2 `[DEPRECATED]`-on-stderr divergence — audit decision
+
+Current `package.json:48` script body (verbatim):
+
+```text
+echo '[DEPRECATED] Use .github/workflows/release.yaml via GitHub Actions. See docs/RELEASING.md.' >&2 && exit 1 ; npm run release:patch
+```
+
+Story 4.2 AC 5 specified `echo '[DEPRECATED] …' && exit 1` (stdout-routed) as the literal form. The applied patch `41ccf35` routes the `echo` to `>&2` (stderr) — a divergence from AC 5's literal shape. Story 4.2's Review Findings Decision→Patch and the Epic 4 retro Commitment 4 both recommend keeping stderr routing.
+
+**Decision (audit time):** KEEP stderr routing. **Rationale:** diagnostic notices are stderr by convention across the repo (`tools/cli/commands/install.js` routes `Installation failed.` to `console.error` per the Story 5.1 H1 fix — same principle); Story 6.2's eventual delete-the-script removal is unaffected by the routing choice. **Scope:** no re-edit of `package.json` in Story 5.1 per the seven-file envelope (AC 1).
+
+## Install Smoke Test Transcript
+
+Procedure per Story 5.1 AC 6 + Task 10: `npm pack` in repo root, then run `--version` and a piped `install` in a clean scratch directory.
+
+### Tarball and install invocation
+
+On the audit host (`node v24.12.0`, `npm 11.6.2`), the `npx --yes <tarball>` invocation from AC 6 step (c) failed under this npm version with `Permission denied` (npm 11.6.2 treats a `.tgz` argument to `npx` as a local executable rather than an installable package). The equivalent install-then-run form confirms the bin wrapper + commander dispatch resolve cleanly, which is the actual pass criterion for AC 6.
+
+```console
+$ npm pack
+[...truncated notices...]
+npm notice name: bmad-module-skill-forge
+npm notice version: 0.10.0
+npm notice filename: bmad-module-skill-forge-0.10.0.tgz
+npm notice package size: 534.2 kB
+npm notice unpacked size: 1.7 MB
+npm notice total files: 228
+bmad-module-skill-forge-0.10.0.tgz
+
+$ mkdir -p /tmp/skf-install-smoke && cd /tmp/skf-install-smoke
+$ npm install /path/to/bmad-module-skill-forge-0.10.0.tgz --no-save
+added 21 packages in 7s
+
+$ ./node_modules/.bin/bmad-module-skill-forge --version
+0.10.0
+```
+
+**Pass:** `--version` resolves through the `bin` wrapper (`tools/skf-npx-wrapper.js`) → commander setup (`tools/cli/skf-cli.js`) → prints the declared version `0.10.0` with exit `0`.
+
+### `echo | bmad-module-skill-forge install` (piped, first ~40 lines)
+
+```console
+$ cd /tmp/skf-install-smoke
+$ echo -e '\n\n\n\n\n' | ./node_modules/.bin/bmad-module-skill-forge install 2>&1 | head -40
+  ╔════════════════════════════════════════════════════════════════════════╗
+  ║                                                                        ║
+  ║   ███████╗██╗  ██╗███████╗                                             ║
+  ║   ██╔════╝██║ ██╔╝██╔════╝                                             ║
+  ║   ███████╗█████╔╝ █████╗                                               ║
+  ║   ╚════██║██╔═██╗ ██╔══╝                                               ║
+  ║   ███████║██║  ██╗██║                                                  ║
+  ║   ╚══════╝╚═╝  ╚═╝╚═╝                                                  ║
+  ║                                                                        ║
+  ╟────────────────────────────────────────────────────────────────────────╢
+  ║   Skill Forge  ⚒  Agent Skill Compiler                                 ║
+  ║   Turn code and docs into instructions AI agents can actually follow.  ║
+  ║   v0.10.0  ·  MIT License  ·  Open Source                              ║
+  ╚════════════════════════════════════════════════════════════════════════╝
+  ...
+┌  Skill Forge Installer
+│
+●  Target: /tmp/skf-install-smoke
+│
+●  Skills will be installed in _bmad/skf/
+◆  Project name:
+│  skf-install-smoke
+└
+```
+
+**Pass:** no `command not found`, no `ERR!`, no immediate non-zero exit. The `install` subcommand dispatch reaches the `ui.promptInstall()` interactive path, renders the banner, and blocks on the `Project name:` prompt (expected — `npx-wrapper` → `commander` → `commands/install.js` action → `UI.promptInstall()` resolves correctly). Completing the interactive flow end-to-end is out of scope for this smoke test (it is Story 5.2 / 5.4 territory); the pass criterion here is that the install code path is reachable with no structural error.
+
+**Clean-up:** the tarball (`bmad-module-skill-forge-0.10.0.tgz`) and the scratch directory (`/tmp/skf-install-smoke`) were deleted after the transcript was captured. `git status --short` at commit time confirms no tarball in the working tree (see § Post-commit footer).
+
+## Blockers
+
+<!-- Populated at Task 11 / Task 12 after all other tasks land. -->
+
+None — audit passes clean; Story 5.2 unblocked.
+
+## Sign-off
+
+TBD — signed by Armel at Story 5.2 dispatch time.
+
+## Post-commit footer
+
+- **Audit-completion commit SHA:** [`540fdda`](https://github.com/armelhbobdad/bmad-module-skill-forge/commit/540fdda419fc7e71bfdc571dab279b5de1b42578) — seven-file envelope (`docs(release): pre-v1.0.0 readiness audit (Story 5.1)`)
+- **Back-fill commit SHA:** this commit (the one that made this footer sentence self-referential)
+- **`git status --short` after commit:** clean working tree (verified per Story 5.1 AC 1 seven-file envelope)

package/src/README.md

@@ -8,40 +8,38 @@ For user-facing documentation (what SKF does, how to install it, how to use it),
 
 ```
 src/
-├── module.yaml           # Module config: code, name, install prompts
-├── module-help.csv       # Help registry — one row per agent command
-├── agents/
-│   └── forger.agent.yaml # Ferris — the single agent persona
-├── workflows/            # 14 workflows (see workflows/README.md)
-│   ├── setup-forge/
-│   ├── analyze-source/
-│   ├── brief-skill/
-│   ├── create-skill/
-│   ├── quick-skill/
-│   ├── create-stack-skill/
-│   ├── verify-stack/
-│   ├── refine-architecture/
-│   ├── update-skill/
-│   ├── audit-skill/
-│   ├── test-skill/
-│   ├── export-skill/
-│   ├── rename-skill/
-│   └── drop-skill/
-├── knowledge/            # Cross-cutting knowledge fragments (JiT loaded)
+├── skf-forger/               # Agent skill — Ferris persona
+│   ├── SKILL.md              # Agent identity, principles, menu of triggers
+│   └── bmad-skill-manifest.yaml
+├── skf-setup/                # Setup skill (forge initialization)
+│   ├── SKILL.md
+│   └── ...
+├── skf-{name}/               # 13 workflow skills (one directory each)
+│   ├── SKILL.md              # Skill entry point (overview, stages, invocation contract)
+│   ├── steps-c/              # Sequential step files
+│   ├── references/           # Rules, patterns, protocols (decision-making)
+│   ├── assets/               # Schemas, output formats
+│   └── templates/            # Output skeletons (used by some skills)
+├── knowledge/                # Cross-cutting knowledge fragments (JiT loaded)
 │   └── skf-knowledge-index.csv
-└── forger/               # Sidecar seed files (preferences, forge tier)
+├── forger/                   # Sidecar seed files (preferences, forge tier)
+├── shared/                   # Cross-workflow resources
+├── module.yaml               # Module metadata (code, name, config vars)
+└── module-help.csv           # Skill menu for bmad-help integration
 ```
 
+**Workflow skills:** setup, analyze-source, brief-skill, create-skill, quick-skill, create-stack-skill, verify-stack, refine-architecture, update-skill, audit-skill, test-skill, export-skill, rename-skill, drop-skill.
+
 ## Components
 
-- **Agent:** [Ferris](agents/forger.agent.yaml) — single-persona module operating in four modes (Architect / Surgeon / Audit / Delivery)
-- **Workflows:** see [workflows/README.md](workflows/README.md) for the full index, typical flows, and the knowledge-vs-data distinction
+- **Agent:** [Ferris](skf-forger/SKILL.md) — single-persona module operating in five modes (Architect / Surgeon / Audit / Delivery / Management)
+- **Workflow skills:** 14 `skf-{name}/` directories, each containing a SKILL.md, steps, references, and assets
 - **Knowledge fragments:** cross-cutting principles Ferris consults via `knowledge/skf-knowledge-index.csv`
 
 ## Editing this module
 
-- Agent edits — `agents/forger.agent.yaml`; validate with `bmad:bmb:agents:agent-validate`
-- Workflow edits — each workflow in `workflows/{name}/`; validate with `bmad:bmb:workflows:workflow-validate`
+- Agent edits — `skf-forger/SKILL.md`; validate with `bmad:bmb:agents:agent-validate`
+- Workflow edits — each workflow skill in `skf-{name}/`; validate with `bmad:bmb:workflows:workflow-validate`
 - Module-level edits — `module.yaml` and `module-help.csv`; validate with `bmad:bmb:modules:validate-module`
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for the contribution workflow.

package/src/forger/forge-tier.yaml

@@ -1,5 +1,5 @@
 # Ferris Sidecar: Forge Tier State
-# Written by setup-forge workflow on first run
+# Written by setup workflow on first run
 
 # Tool availability (detected during [SF] Setup Forge)
 tools:
@@ -15,12 +15,14 @@ tools:
 tier: ~
 tier_detected_at: ~
 
-# CCC semantic index state (managed by setup-forge and extraction workflows)
+# CCC semantic index state (managed by setup and extraction workflows)
 ccc_index:
   indexed_path: ~
   last_indexed: ~
   status: "none"
   staleness_threshold_hours: 24
+  file_count: ~
+  exclude_patterns: []
 
 # CCC index registry (tracks which source paths have been indexed for skill workflows)
 ccc_index_registry: []

package/src/forger/preferences.yaml

@@ -1,5 +1,5 @@
 # Ferris Sidecar: User Preferences
-# Created by setup-forge workflow on first run
+# Created by setup workflow on first run
 # Edit this file to customize Ferris behavior
 
 # Override detected tier (set to Quick, Forge, Forge+, or Deep to force a tier)
@@ -8,6 +8,12 @@ tier_override: ~
 # Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)
 passive_context: true
 
+# Headless mode (set to true to skip confirmation gates in all workflows)
+headless_mode: false
+
+# Compact greeting (set to true to skip the full capabilities table on session start)
+compact_greeting: false
+
 # Reserved for future use — these fields are not yet consumed by any workflow step
 # output_language: ~
 # skill_format_version: ~

package/src/knowledge/agentskills-spec.md

@@ -40,7 +40,7 @@ description: >
 - `description`: 1-1024 characters, trigger-optimized for agent matching
   - **MUST use third-person voice.** The description is injected into the system prompt; inconsistent point-of-view causes discovery problems. Write "Processes Excel files and generates reports" — never "I can help you process Excel files" or "You can use this to process Excel files."
 
-**Body:** Free-form markdown — no structural restrictions, but Skill Forge follows a consistent section order (see skill-sections.md in create-skill/data/).
+**Body:** Free-form markdown — no structural restrictions, but Skill Forge follows a consistent section order (see skill-sections.md in create-skill/assets/).
 
 ### Optional: Supporting Directories
 

package/src/knowledge/architecture-verification.md

@@ -99,4 +99,4 @@ VS and RA are pre-code workflows. SS compose-mode synthesizes the implementation
 - [skill-lifecycle.md](skill-lifecycle.md) — end-to-end pipeline and workflow connections
 - [progressive-capability.md](progressive-capability.md) — tier philosophy for skill generation
 
-_Source: synthesized from verify-stack/workflow.md, refine-architecture/workflow.md, and create-stack-skill compose-mode-rules.md_
+_Source: synthesized from skf-verify-stack/SKILL.md, skf-refine-architecture/SKILL.md, and skf-create-stack-skill/references/compose-mode-rules.md_

package/src/knowledge/ccc-bridge.md

@@ -24,7 +24,7 @@ ccc is **required** at the Forge+ tier (it defines Forge+) and **optionally avai
 ## Availability
 
 ccc_bridge operations are available when:
-- `tools.ccc: true` in forge-tier.yaml (verified by `ccc --help` + `ccc doctor` in setup-forge)
+- `tools.ccc: true` in forge-tier.yaml (verified by `ccc --help` + `ccc doctor` in setup)
 - `ccc_index.status` is `"fresh"` or `"stale"` in forge-tier.yaml (an index exists for the project)
 
 When either condition is false, calling steps skip ccc discovery silently and proceed with direct ast-grep or source reading. This is standard Forge tier behavior — not a degradation.
@@ -43,7 +43,7 @@ Returns: list of `{file, score, snippet}` entries ranked by semantic relevance t
 
 **Resolves to:** Check `ccc_index.status` in forge-tier.yaml. If `"none"` or the indexed_path does not match, run `cd {path} && ccc init` then `ccc index` and update forge-tier.yaml. Note: `ccc init` takes no positional arguments — it initializes the index for the current working directory.
 
-**Usage context:** Called by setup-forge step-01b to ensure the project root is indexed. Called lazily by extraction steps when `ccc_index.status` is `"none"` but ccc is available.
+**Usage context:** Called by setup step-01b to ensure the project root is indexed. Called lazily by extraction steps when `ccc_index.status` is `"none"` but ccc is available.
 
 ### `ccc_bridge.status()`
 
@@ -51,7 +51,7 @@ Returns: list of `{file, score, snippet}` entries ranked by semantic relevance t
 1. `ccc --help` — confirms binary exists (exit 0)
 2. `ccc doctor` — confirms daemon is running, extracts version string, validates embedding model
 
-**Usage context:** Called exclusively by setup-forge step-01 during tool detection. Downstream workflows read the result from forge-tier.yaml — they do not re-verify.
+**Usage context:** Called exclusively by setup step-01 during tool detection. Downstream workflows read the result from forge-tier.yaml — they do not re-verify.
 
 ## Confidence
 
@@ -67,7 +67,7 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 
 ### When Indexing Happens
 
-1. **setup-forge step-01b:** Indexes the project root when setup-forge runs. This is the primary indexing point.
+1. **setup step-01b:** Indexes the project root when setup runs. This is the primary indexing point.
 2. **Workflow discovery steps:** If `ccc_index.status` is `"stale"` or `"none"`, discovery steps trigger a re-index and warn the user. They do not block.
 3. **ccc daemon:** Incremental indexing means re-indexing unchanged files is a near-no-op.
 
@@ -75,13 +75,13 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 
 - Staleness threshold: 24 hours (configurable via `ccc_index.staleness_threshold_hours` in forge-tier.yaml)
 - A stale index still produces useful results — the workflow proceeds with the stale index and notes the staleness
-- setup-forge is the designated refresh authority
+- setup is the designated refresh authority
 
 ### Exclusion Patterns
 
 CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. This file contains `exclude_patterns` and `include_patterns` arrays in glob format. `ccc init` creates the file with sensible defaults (excludes `node_modules`, `__pycache__`, hidden dirs, etc.).
 
-**SKF infrastructure exclusions:** setup-forge step-01b appends SKF-specific exclusion patterns after `ccc init` creates the default config. These patterns prevent indexing of framework and output directories that have zero value for source extraction:
+**SKF infrastructure exclusions:** setup step-01b appends SKF-specific exclusion patterns after `ccc init` creates the default config. These patterns prevent indexing of framework and output directories that have zero value for source extraction:
 
 | Pattern | Purpose |
 |---------|---------|
@@ -92,20 +92,21 @@ CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. T
 | `**/{skills_output_folder}` | Generated skill files (from manifest, default: `skills`) |
 | `**/{forge_data_folder}` | Compilation workspace (from manifest, default: `forge-data`) |
 
-The `skills_output_folder` and `forge_data_folder` values are read from `_bmad/_config/skf-manifest.yaml` when available, falling back to the defaults `skills` and `forge-data`. Patterns are appended only if not already present — user customizations to `settings.yml` are preserved.
+The `skills_output_folder` and `forge_data_folder` values are resolved from the workflow activation context (sourced from `_bmad/skf/config.yaml`), falling back to the defaults `skills` and `forge-data`. Patterns are appended only if not already present — user customizations to `settings.yml` are preserved.
 
 The configured exclusion patterns are stored in `ccc_index.exclude_patterns` in forge-tier.yaml for reference.
 
 ### Deferred Discovery (Remote Sources)
 
-For remote repository sources (GitHub URLs), CCC cannot operate during step-02b because no local code exists yet. The ephemeral clone happens in step-03. To provide CCC pre-ranking for remote sources:
+For remote repository sources (GitHub URLs), CCC cannot operate during step-02b because no local code exists yet. The workspace clone or ephemeral clone happens in step-03. To provide CCC pre-ranking for remote sources:
 
 1. **step-02b:** Detects remote source, sets `{ccc_discovery: []}`, displays deferred message
-2. **step-03:** After ephemeral clone succeeds, detects the deferred scenario (`tools.ccc == true AND {ccc_discovery} is empty AND ephemeral_clone_active == true AND tier is Forge+/Deep`)
-3. **step-03:** Runs `cd {temp_path} && ccc init` on the ephemeral clone, then applies brief `exclude_patterns` (if present) to `{temp_path}/.cocoindex_code/settings.yml` before running `ccc index` (extended timeout or background mode, verified via `ccc status`). This prevents CCC from indexing files the brief explicitly excludes, keeping search results focused on in-scope source code and reducing indexing time for large repositories.
-4. **step-03:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
+2. **step-03:** After source resolution succeeds, detects the deferred scenario (`tools.ccc == true AND {ccc_discovery} is empty AND remote_clone_path is set AND tier is Forge+/Deep`)
+3. **step-03 (workspace fast path):** If `{remote_clone_path}/.cocoindex_code/` already exists (persisted workspace index), skips init/index and uses `ccc search --refresh` — CCC daemon re-indexes only if files changed since last index. This is near-instant for unchanged repos.
+4. **step-03 (first-time path):** If no existing CCC index, runs `cd {remote_clone_path} && ccc init`, applies standard build/dependency exclusions (node_modules, dist, .git, vendor, etc.) to `settings.yml`, then runs `ccc index`. Brief-specific `include_patterns`/`exclude_patterns` are NOT written to `settings.yml` — the CCC index is general-purpose. Filtering happens at search result time.
+5. **step-03:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
 
-The ephemeral clone index is not registered in `ccc_index_registry` — the clone is deleted after extraction and the CCC daemon's own GC handles orphaned indexes.
+For workspace repos, the CCC index persists at `{workspace_repo_path}/.cocoindex_code/` and is reused across forges, projects, and sessions. For ephemeral fallback clones, the index is not registered in `ccc_index_registry` — the clone is deleted after extraction.
 
 ### Relationship to QMD Registry
 
@@ -113,7 +114,7 @@ ccc_index and qmd_collections are **orthogonal**:
 - `ccc_index` in forge-tier.yaml tracks the persistent source code index (one per project)
 - `qmd_collections[]` in forge-tier.yaml tracks per-skill workflow artifact collections
 - ccc indexes source code for semantic search; QMD indexes curated artifacts for temporal/knowledge search
-- The janitor role for QMD (setup-forge step-03) operates independently of ccc_index
+- The janitor role for QMD (setup step-03) operates independently of ccc_index
 
 ## Query Volume Bounds
 
@@ -130,8 +131,8 @@ To prevent excessive daemon calls, workflow steps cap ccc queries:
 - Running ccc_bridge.ensure_index() without checking ccc_index.status first — unnecessary re-indexing
 - Passing ccc results directly to the extraction inventory — they are candidates, not extractions
 - Listing ccc as "unavailable" in reports for Quick/Forge tiers — ccc is a Forge+ capability, not something Quick/Forge tiers are missing
-- Indexing without configuring SKF exclusions — framework and output directories pollute search results
-- Indexing an ephemeral clone without applying brief `exclude_patterns` — excluded files pollute CCC search results and waste indexing time on large repositories
+- Indexing without configuring exclusions — for project root indexes, apply SKF exclusions (framework/output directories); for workspace repo indexes, apply standard build artifact exclusions (node_modules, dist, .git, etc.)
+- Writing brief-specific `exclude_patterns` to a workspace repo's `settings.yml` — workspace indexes are general-purpose and serve multiple briefs. Apply brief patterns at search result time, not index time. (Exception: ephemeral fallback clones are single-use, so brief exclusions may be applied to their `settings.yml` to reduce indexing time.)
 - Skipping CCC discovery for remote sources without deferring to step-03 — remote repos deserve the same pre-ranking as local sources
 
 ## Related Fragments

package/src/knowledge/overview.md

@@ -2,11 +2,11 @@
 
 ## Principle
 
-Agent-level knowledge files capture cross-cutting principles and patterns that Ferris applies across multiple workflows. They are distinct from workflow `data/` files, which contain step-specific operational artifacts. Knowledge is loaded just-in-time when a workflow step directs — never preloaded into context.
+Agent-level knowledge files capture cross-cutting principles and patterns that Ferris applies across multiple workflows. They are distinct from workflow `references/` and `assets/` files, which contain step-specific operational artifacts. Knowledge is loaded just-in-time when a workflow step directs — never preloaded into context.
 
 ## Rationale
 
-The SKF module has 12 workflows containing numerous operational `data/` files embedded in step directories. These data files define schemas, templates, scoring formulas, and extraction rules tightly coupled to individual steps. But several principles — zero hallucination, confidence tiers, provenance — cut across multiple workflows and need a single authoritative source rather than fragmented repetition.
+The SKF module has 14 workflows containing operational `references/` and `assets/` files within each skill directory. References contain rules, patterns, and protocols for decision-making; assets contain templates, schemas, and output formats. Both are tightly coupled to individual steps. But several principles — zero hallucination, confidence tiers, provenance — cut across multiple workflows and need a single authoritative source rather than fragmented repetition.
 
 Without a knowledge folder:
 - Cross-cutting principles get duplicated across workflow steps
@@ -26,7 +26,7 @@ With knowledge files:
 | [confidence-tiers.md](confidence-tiers.md)                 | T1/T1-low/T2/T3 trust model and citation formats                  | AN, BS, CS, QS, SS, US, AS, TS, EX, RA, VS |
 | [progressive-capability.md](progressive-capability.md)     | Quick/Forge/Forge+/Deep tier philosophy and behavior adaptation          | SF, AN, BS, CS, QS, SS, US, AS, TS, EX, VS, RA |
 | [agentskills-spec.md](agentskills-spec.md)                 | agentskills.io output format principles and compliance            | CS, QS, SS, US, TS, EX             |
-| [skill-lifecycle.md](skill-lifecycle.md)                   | End-to-end pipeline, artifact flow, workflow selection            | All 12                             |
+| [skill-lifecycle.md](skill-lifecycle.md)                   | End-to-end pipeline — workflow connections, artifact flow, decision rules for workflow selection, pipeline invocation syntax and aliases | All 14                             |
 | [provenance-tracking.md](provenance-tracking.md)           | Provenance-map.json entries and file_entries, evidence reports, claim traceability | CS, QS, SS, US, AS, TS             |
 | [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm                | CS, US, AS, TS, EX                 |
 | [qmd-registry.md](qmd-registry.md)                         | Progressive QMD collection registry and collection gate principle | SF, BS, CS, US, AS                 |
@@ -43,17 +43,17 @@ With knowledge files:
 1. Ferris receives a task or workflow activation
 2. Consult `skf-knowledge-index.csv` to identify relevant knowledge fragments by tags or description. The `tier` column classifies fragments as `core` (always relevant when the domain applies) or `extended` (load only when the specific scenario is active — e.g., `doc-fetcher.md` only when `doc_urls` are present in the brief)
 3. Load only the files needed for the current task — never bulk-load all knowledge
-4. Apply knowledge principles during workflow execution alongside step-specific `data/` files
+4. Apply knowledge principles during workflow execution alongside step-specific `references/` and `assets/` files
 
 ## Knowledge vs. Data
 
-| Aspect    | Knowledge Files (`knowledge/`)       | Data Files (`data/`)                    |
-|-----------|--------------------------------------|-----------------------------------------|
-| Scope     | Cross-cutting, multi-workflow        | Single workflow, single step            |
-| Content   | Principles, patterns, judgment rules | Schemas, templates, scoring formulas    |
-| Loading   | JiT via index lookup                 | JiT via step instruction                |
-| Examples  | Zero hallucination, confidence tiers | skill-brief-schema.md, scoring-rules.md |
-| Stability | Rarely changes                       | Changes with workflow evolution         |
+| Aspect    | Knowledge Files (`knowledge/`)       | References (`references/`)              | Assets (`assets/`)                      |
+|-----------|--------------------------------------|-----------------------------------------|-----------------------------------------|
+| Scope     | Cross-cutting, multi-workflow        | Single workflow, single step            | Single workflow, single step            |
+| Content   | Principles, patterns, judgment rules | Rules, patterns, protocols, heuristics  | Templates, schemas, output formats      |
+| Loading   | JiT via index lookup                 | JiT via step instruction                | JiT via step instruction                |
+| Examples  | Zero hallucination, confidence tiers | scoring-rules.md, extraction-patterns.md | skill-brief-schema.md, skill-template.md |
+| Stability | Rarely changes                       | Changes with workflow evolution         | Changes with workflow evolution         |
 
 ## Related Fragments
 

package/src/knowledge/progressive-capability.md

@@ -31,7 +31,7 @@ With progressive capability:
 
 ### Example 1: Tool Detection and Tier Assignment
 
-**Context:** The setup-forge workflow detects available tools and assigns a tier.
+**Context:** The setup workflow detects available tools and assigns a tier.
 
 **Implementation:** Each tool is verified by executing its version command — presence in PATH is insufficient. The tier is the highest level where all required tools pass verification:
 
@@ -125,7 +125,7 @@ When source is remote (GitHub URL) and tier is Forge, Forge+, or Deep:
 ## Anti-Patterns
 
 - Describing Quick tier as "basic" or "limited" — it is fast and legitimate
-- Requiring ast-grep for workflows that work fine without it (setup-forge, brief-skill)
+- Requiring ast-grep for workflows that work fine without it (setup, brief-skill)
 - Mixing tier capabilities in a single extraction (e.g., T1 citations when only source reading was used)
 - Failing a workflow because the tier is "too low" — adapt behavior instead
 - Silent degradation when source is remote at Forge/Deep tier — always warn with actionable guidance
@@ -136,4 +136,4 @@ When source is remote (GitHub URL) and tier is Forge, Forge+, or Deep:
 - [skill-lifecycle.md](skill-lifecycle.md) — how tier affects workflow selection and artifact flow
 - [zero-hallucination.md](zero-hallucination.md) — Quick tier has lower confidence but the same integrity standard
 
-_Source: distilled from forge-tier.yaml, tier-rules.md, and setup-forge workflow_
+_Source: distilled from forge-tier.yaml, tier-rules.md, and setup workflow_

package/src/knowledge/provenance-tracking.md

@@ -36,7 +36,9 @@ With provenance tracking:
 **Implementation:**
 ```json
 {
+  "provenance_version": "2.0",
   "skill_name": "express-skill",
+  "skill_type": "single",
   "source_repo": "https://github.com/expressjs/express",
   "source_commit": "abc1234",
   "source_ref": "v0.5.0",
@@ -45,24 +47,28 @@ With provenance tracking:
     {
       "export_name": "createServer",
       "export_type": "function",
+      "source_library": "express",
       "params": ["options: ServerOptions"],
       "return_type": "Server",
       "source_file": "src/server.ts",
       "source_line": 23,
       "confidence": "T1",
       "extraction_method": "ast-grep",
-      "ast_node_type": "export_statement > function_declaration"
+      "ast_node_type": "export_statement > function_declaration",
+      "signature_source": "T1"
     },
     {
       "export_name": "parseConfig",
       "export_type": "function",
+      "source_library": "express",
       "params": ["input"],
       "return_type": null,
       "source_file": "src/config.ts",
       "source_line": 45,
       "confidence": "T1-low",
       "extraction_method": "source-read",
-      "ast_node_type": null
+      "ast_node_type": null,
+      "signature_source": "T1-low"
     }
   ]
 }
@@ -125,7 +131,7 @@ With provenance tracking:
 
 **Key Points:**
 - Provenance enables precise diffing — compare specific claims, not entire files
-- Severity classification uses the rules from audit-skill/data/severity-rules.md
+- Severity classification uses the rules from audit-skill/references/severity-rules.md
 - The drift report feeds into the update-skill workflow as re-extraction targets
 
 ### Example 4: Provenance Preservation During Updates