bmad-module-skill-forge 2.2.0 → 4.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "2.2.0",
+  "version": "4.0.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -27,11 +27,12 @@
   },
   "license": "MIT",
   "author": "armelhbobdad",
-  "main": "tools/cli/skf-cli.js",
   "bin": {
     "bmad-module-skill-forge": "tools/skf-npx-wrapper.js"
   },
   "scripts": {
+    "changes:pr": "node tools/changes.js pr",
+    "changes:preview": "node tools/changes.js preview",
     "docs:build": "node tools/build-docs.js",
     "docs:dev": "npm run --prefix website docs:dev",
     "docs:fix-links": "node tools/fix-doc-links.js --write",
@@ -42,26 +43,34 @@
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
-    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "lint:instructions": "uvx lintlang@0.8.2 scan src --fail-on fail",
+    "lint:md": "markdownlint-cli2 \"**/*.md\" && node tools/changes.js lint",
     "prepare": "husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:rehype && npm run test:docs-links-tool && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run validate:docs-links && npm run docs:validate-drift",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run lint:instructions && npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:rehype && npm run test:docs-links-tool && npm run test:em-dash-tool && npm run test:file-refs-tool && npm run test:changes-tool && npm run test:tool-requirements-tool && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run validate:docs-links && npm run validate:em-dash && npm run validate:changes && npm run validate:tool-requirements && npm run docs:validate-drift",
     "skf:install": "node tools/cli/skf-cli.js install",
     "skf:status": "node tools/cli/skf-cli.js status",
     "skf:uninstall": "node tools/cli/skf-cli.js uninstall",
     "skf:update": "node tools/cli/skf-cli.js update",
-    "test": "npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:rehype && npm run test:docs-links-tool && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run validate:docs-links && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:rehype && npm run test:docs-links-tool && npm run test:em-dash-tool && npm run test:file-refs-tool && npm run test:changes-tool && npm run test:tool-requirements-tool && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run validate:docs-links && npm run validate:em-dash && npm run validate:changes && npm run validate:tool-requirements && npm run lint && npm run lint:md && npm run lint:instructions && npm run format:check",
+    "test:changes-tool": "node test/test-changes.js && node test/test-release-state.js",
     "test:cli": "node test/test-cli-integration.js",
-    "test:docs-links-tool": "node test/test-validate-docs-links.js",
-    "test:install": "node test/test-installation-components.js",
+    "test:docs-links-tool": "node test/test-validate-docs-links.js && node test/test-check-required-checks.js && node tools/check-required-checks.js --releasing",
+    "test:em-dash-tool": "node test/test-validate-no-em-dash.js",
+    "test:file-refs-tool": "node test/test-validate-file-refs.js",
+    "test:install": "node test/test-installation-components.js && node test/test-pack-contents.js && node test/test-validate-skills.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-language-corpora.py test/test-skf-merge-doc-urls.py test/test-skf-derive-assembly-shape.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py test/test-skf-campaign-state.py test/test-skf-campaign-pins.py test/test-skf-campaign-deps.py test/test-skf-campaign-report.py test/test-skf-campaign-stepfiles.py test/test-skf-campaign-validate-state.py test/test-skf-campaign-provenance.py test/test-skf-campaign-parse-manifest.py test/test-skf-campaign-render-kickoff.py test/test-skf-campaign-render-batch.py test/test-skf-shard-body.py test/test-skf-render-metadata-stats.py test/test-skf-comention-pairs.py test/test-skf-count-tokens.py test/test-skf-reconcile-coverage.py test/test-skf-verify-provenance-completeness.py test/test-skf-find-cycles.py test/test-skf-validate-feasibility-report.py test/test-skf-rewrite-skill-name.py test/test-skf-verify-no-trace.py test/test-skf-validate-inventory.py test/test-skf-check-metadata-coherence.py test/test-skf-scan-doc-rot.py test/test-skf-aggregate-coherence.py test/test-skf-dir-sizes.py test/test-skf-parse-pipeline.py test/test-skf-validate-rename-name.py test/test-skf-verify-declared-numerator.py test/test-skf-combine-external-scores.py test/test-skf-new-file-diff.py test/test-skf-coverage-tally.py test/test-skf-report-delta.py test/test-skf-verdict-rollup.py -v",
+    "test:python": "uv run --with pytest --with pyyaml --with jsonschema --with ast-grep-cli==0.45.3 pytest test -o \"python_files=test-*.py test_*.py *_test.py\" -v",
     "test:rehype": "node test/test-rehype-markdown-links.js",
     "test:schemas": "node test/test-agent-schema.js",
+    "test:tool-requirements-tool": "node test/test-tool-requirements.js",
     "test:workflow": "node test/test-workflow-state.js",
+    "validate:changes": "node tools/changes.js check",
     "validate:docs-links": "node tools/validate-docs-links.js --strict",
+    "validate:em-dash": "node tools/validate-no-em-dash.js --strict",
     "validate:refs": "node tools/validate-file-refs.js --strict",
     "validate:schemas": "node test/validate-agent-schema.js",
-    "validate:skills": "node tools/validate-skills.js --strict"
+    "validate:skills": "node tools/validate-skills.js --strict",
+    "validate:tool-requirements": "node tools/tool-requirements.js --check"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [
@@ -97,7 +106,6 @@
     "archiver": "^7.0.1",
     "astro": "^5.16.0",
     "c8": "^10.1.3",
-    "conventional-changelog-cli": "^5.0.0",
     "csv-parse": "^6.1.0",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",

package/src/forger/preferences.yaml

@@ -1,5 +1,5 @@
 # Ferris Sidecar: User Preferences
-# Created by setup workflow on first run
+# Created by the SKF installer (setup reads it, and never writes it)
 # Edit this file to customize Ferris behavior
 
 # Override detected tier (set to Quick, Forge, Forge+, or Deep to force a tier)
@@ -14,6 +14,13 @@ headless_mode: false
 # Compact greeting (set to true to skip the full capabilities table on session start)
 compact_greeting: false
 
+# Tessl Review (off unless set). Set to the name of your Tessl workspace to have
+# create-skill and test-skill send each skill's SKILL.md, references/, scripts/
+# and assets/ to Tessl for an AI-judge review, kept in that workspace's review
+# history. Needs the tessl CLI and `tessl login` (or TESSL_TOKEN); each fresh
+# review spends Tessl credits.
+tessl_review_workspace: ~
+
 # 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

@@ -39,6 +39,7 @@ description: >
   - **Naming convention:** Prefer gerund form (verb + -ing) for clarity: `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`. Noun phrases (`pdf-processing`) and action-oriented forms (`process-pdfs`) are acceptable alternatives. Avoid vague names (`helper`, `utils`, `tools`).
 - `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."
+  - **No XML tags.** The Claude platform does not accept a description that contains XML tags; write `{name}` or `NAME` instead of `<name>`. Create-skill replaces every `<` and `>` in the description with `{` and `}` and checks the result.
 
 **Body:** Free-form markdown — no structural restrictions, but Skill Forge follows a consistent section order (see skill-sections.md in create-skill/assets/).
 
@@ -141,6 +142,7 @@ the user's configuration against the expected structure.
 4. SKILL.md body under 500 lines (warning, not failure)
 5. All relative paths resolve to existing files
 6. No deeply nested subdirectories (max one level)
+7. `description` holds no `<` or `>` (the Claude platform does not accept XML tags in a description)
 
 **Key Points:**
 - Compliance is checked during create-skill, not as a post-hoc audit

package/src/knowledge/ccc-bridge.md

@@ -23,11 +23,11 @@ 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)
-- `ccc_index.status` is `"fresh"` or `"stale"` in forge-tier.yaml (an index exists for the project)
+ccc_bridge operations are available when `tools.ccc: true` in forge-tier.yaml (verified by `ccc --help` + `ccc doctor` in setup). When it 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.
 
-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.
+With ccc available, `ccc_index.status` decides how a step reaches the project index:
+- `"fresh"`, `"created"`, `"skipped"`, or a status the step does not know (such as a `"stale"` an older SKF recorded): the index is usable, and the discovery steps search it with `ccc search --refresh`. After `"skipped"` there may be no index yet, but setup's `--ccc-skip-index` lane still wrote `settings.yml` with the SKF exclusions, so the first refresh search builds the index safely.
+- `"none"` or `"failed"`: setup built no index. Create-skill discovery indexes lazily with `ensure_index`; a step without a lazy path skips ccc silently.
 
 ## Operations
 
@@ -37,13 +37,15 @@ When either condition is false, calling steps skip ccc discovery silently and pr
 
 Returns: list of `{file, score, snippet}` entries ranked by semantic relevance to the query. These are **candidates** for ast-grep extraction — not verified exports.
 
-**Usage context:** Called before ast-grep in Forge+ and Deep tier extraction steps to discover semantically relevant source regions. Results pre-rank the file extraction queue so ast-grep processes the most relevant files first.
+**Usage context:** Called before extraction in Forge+ and Deep tier steps to discover semantically relevant source regions. The ranking orders the files a step reads by hand; the recipe runner reads every file in scope, so its result does not depend on it.
 
 ### `ccc_bridge.ensure_index(path)`
 
-**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.
+**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. Exception: when `{path}` is `{project-root}` and `{project-root}/.cocoindex_code/settings.yml` does not exist, do not run `ccc init` or `ccc index` — setup's `skf-merge-ccc-exclusions.py` owns initializing the project root with the SKF exclusions, and in a project nested inside another git checkout `ccc index` would index the enclosing repository instead. Treat the index as unavailable and suggest re-running `/skf-setup`.
 
-**Usage context:** Called by setup step 1b to ensure the project root is indexed. Called lazily by extraction steps when `ccc_index.status` is `"none"` but ccc is available.
+When `ccc init` exits non-zero with `A parent directory has a project marker`, run `ccc init -f` in `{path}`. Run `ccc index` only once `{path}/.cocoindex_code/settings.yml` exists: without it, `ccc index` initializes the enclosing git checkout with ccc's defaults and none of the SKF exclusions. Afterwards `skf-ccc-git-hygiene.py nested` keeps a project in a subfolder out of git (see Exclusion Patterns).
+
+**Usage context:** Called lazily by extraction steps when `ccc_index.status` is `"none"` or `"failed"` but ccc is available. Setup step 1b does not call it: its helper runs `ccc init` and decides whether to index.
 
 ### `ccc_bridge.status()`
 
@@ -68,20 +70,25 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 ### When Indexing Happens
 
 1. **setup step 1b:** 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.
+2. **Workflow discovery steps:** Create-skill discovery and create-stack-skill integration detection search setup's index with `ccc search --refresh`, which first indexes what changed since (after `--ccc-skip-index`, the whole project). When `ccc_index.status` is `"none"` or `"failed"`, create-skill discovery indexes lazily and integration detection skips ccc. Discovery never blocks.
 3. **ccc daemon:** Incremental indexing means re-indexing unchanged files is a near-no-op.
+4. **create-skill step 7:** Indexes the source of the skill and records it in `ccc_index_registry`: SKF's workspace clone of a remote source, which step 3 moved to the commit the skill was extracted from, or a local source folder, which becomes a ccc project of its own (`ccc init -f`) when it sits inside another git checkout or ccc project.
 
 ### Freshness
 
-- 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 is the designated refresh authority
+- setup is the designated authority for the `ccc_index` status in forge-tier.yaml. It records `"fresh"` (a re-run kept the index), `"created"`, `"failed"`, `"none"` or `"skipped"` (`--ccc-skip-index`); no status records staleness
+- Staleness threshold: 24 hours (configurable via `ccc_index.staleness_threshold_hours` in forge-tier.yaml). A setup re-run compares `last_indexed` against it to decide whether to keep the index or index again
+- A workflow step never computes staleness. Create-skill discovery and create-stack-skill integration detection search setup's index with `ccc search --refresh`, one incremental pass that indexes what changed since and costs almost nothing when nothing did; the refresh does not change the recorded status. Other steps search the index as it stands
 
 ### 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.).
+CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. `ccc init` creates it with `exclude_patterns` and `include_patterns` holding ccc's defaults (hidden directories, `node_modules`, `__pycache__`, its own `.cocoindex_code`, and more) and, at the top of a git checkout, adds `/.cocoindex_code/` to `.gitignore`. An `exclude_patterns` list in the file replaces ccc's default exclusions, so SKF only ever extends a list that `ccc init` wrote.
+
+ccc adds that line only when it creates a project at the top of a git checkout whose `.git` is a folder, and the line matches only that top-level folder; a `ccc index` that finds no `settings.yml` initializes the project the same way. A ccc project in a subfolder of a checkout (the `ccc init -f` case), in a linked worktree or in a submodule, whose `.git` is a file, therefore gets no entry, and git lists its index database as untracked. SKF never edits a project's own `.gitignore`. After create-skill runs ccc in a local source folder other than the project root, `skf-ccc-git-hygiene.py nested` runs `git check-ignore -q --no-index` there, once each for `settings.yml`, `target_sqlite.db` and `cocoindex.db/mdb/data.mdb` under `.cocoindex_code/`, and when any of them is not ignored writes `.cocoindex_code/.gitignore` holding `*` so the folder ignores itself. In an SKF workspace clone, `skf-ccc-git-hygiene.py workspace` instead undoes ccc's `.gitignore` edit and lists `.cocoindex_code/` and `/.skf-workspace.lock` in the clone's `.git/info/exclude` (see Deferred Discovery). ccc reads only `.gitignore` files and excludes `**/.cocoindex_code` by default, so neither changes what it indexes.
+
+ccc reads `settings.yml` again on every index run. After an edit to `exclude_patterns` or `include_patterns`, a plain `ccc index` (or `ccc search --refresh`) drops the files a pattern now leaves out and indexes the ones it brings in, with the daemon already running; the index never needs deleting and the daemon never needs restarting. A plain `ccc search` does not re-index a project the daemon already has loaded, so run `ccc index` before a search that must reflect an edit.
 
-**SKF infrastructure exclusions:** setup step 1b 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 1b runs `skf-merge-ccc-exclusions.py`, which runs `ccc init` when the file is missing, rebuilds a file that lacks the ccc defaults (keeping user entries), and keeps these patterns in it:
 
 | Pattern | Purpose |
 |---------|---------|
@@ -89,24 +96,32 @@ CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. T
 | `**/_bmad-output` | Build output artifacts (TODO files, reports) |
 | `**/.claude` | Claude Code configuration |
 | `**/_skf-learn` | SKF learning materials |
-| `**/{skills_output_folder}` | Generated skill files (from manifest, default: `skills`) |
-| `**/{forge_data_folder}` | Compilation workspace (from manifest, default: `forge-data`) |
+| `{skills_output_folder}` | Generated skill files (default `skills`), anchored to the project root — a nested folder with the same name stays indexed. In a folder that also holds content SKF did not generate, one `{skills_output_folder}/<entry>` pattern per SKF entry instead |
+| `{forge_data_folder}` | Compilation workspace (default `forge-data`), anchored to the project root. Per SKF entry in a folder that also holds other content, as above |
+
+The folder values come from `_bmad/skf/config.yaml` and are used relative to the project root. Setup lists each folder with git, honouring only `.gitignore` files as ccc does. A skill folder in `{skills_output_folder}` counts as SKF output by the rule the workflows use before they write into, move or delete a skill (see `knowledge/version-paths.md` Ownership): its `metadata.json`, or a version's, carries an SKF marker, or it is `_batch`. The versioned layout, an `active` link, a manifest key or a result file do not count on their own, so a module's skills that an earlier SKF moved into that layout stay indexed. A folder in `{forge_data_folder}` counts as SKF output by the rule drop and rename use for a skill's forge folder: its name contains `.skf-`, it is `_campaign` or `improvement-queue`, or it holds a brief, `.brief-draft.json` or `*-result*.json` file directly, or a provenance map, evidence report, extraction rules or `*-result*.json` file in a folder directly inside it. Both rules read the folder on disk, so a file `.gitignore` hides still counts, and a linked folder never does. Setup handles each folder in one of four ways:
+
+- **Only SKF output** (neutral files such as `.gitkeep` or a README do not count, and loose files directly in the folder beside SKF output are excluded with it): the bare folder pattern.
+- **SKF output next to content SKF did not generate**, for example skills installed from elsewhere: one pattern per SKF entry, so the other content stays indexed. The forms are `{folder}/<entry>` for each SKF skill group or file, plus `{folder}/_batch`, `{folder}/.export-manifest.json`, `{folder}/export-skill-result*.json` and `{folder}/drop-skill-result*.json` whether or not they exist yet. The forge folder gets `{folder}/_campaign`, `{folder}/improvement-queue` and one `{folder}/<report prefix>*` per SKF report instead. Glob characters in an entry name are written as character classes, so `[x]` becomes `[[]x[]]`. A skill created there after setup stays indexed, twice through its version folder and its `active` link, until setup runs again. Setup warns and names the other entries.
+- **No SKF output, only other content**, for example a module whose own source lives under `skills/`: setup leaves the folder out and warns, naming the setting to change.
+- **Already in `exclude_patterns`**, added by the user: once a setup run with ccc has saved SKF's record (below), setup leaves it alone and adds no pattern for it. Without that record, setup treats a folder of only SKF output as its own, and keeps a folder that also holds other content with a one-time warning.
 
-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.
+SKF never writes a `!` negation. ccc applies a negation against every exclude pattern, its own defaults included, so it would re-include `node_modules`, hidden folders and the user's own excludes inside the other content. ccc also walks into an excluded folder when a negation matches the folder, matches any name one level inside it (a wildcard such as `*/*` or `**/{folder}/*`; `*/x` is not one), or starts with `{folder}/`, and then indexes everything below it that no other pattern excludes. So a `!{folder}/…` entry, even one that names a single file or a path that does not exist, cancels a bare `{folder}` pattern entirely, for `{skills_output_folder}` and `{forge_data_folder}` alike, and the SKF files there are indexed again (a skill twice, through its version folder and its `active` link) unless another pattern still excludes them, as ccc's `**/.*` does inside a hidden folder. Setup keeps a user's `!` entry but warns on every run while one re-opens a folder pattern it writes (the bare pattern, or the pattern of an SKF entry in a shared folder) and ccc reaches the SKF output below it, including after a shared folder goes back to the bare pattern; the warning reaches the step 4 report and the envelope's `warnings`.
 
-The configured exclusion patterns are stored in `ccc_index.exclude_patterns` in forge-tier.yaml for reference.
+`ccc_index.exclude_patterns` in forge-tier.yaml records the patterns SKF owns, per-entry patterns included. Each setup run removes a recorded pattern the current config no longer produces (for example after `skills_output_folder` changes, after a skill in a shared folder is dropped or renamed, or when a folder starts or stops holding other content), never removes entries it did not add, and keeps the record unchanged on a run without ccc. Ownership goes by the entry's text, so an entry identical to one SKF manages counts as SKF's: a user's copy of a bare folder pattern SKF already writes goes when SKF removes that pattern, and an entry present before a run with ccc first saved the record (an earlier run without ccc leaves it empty, which setup does not trust) is adopted when the folder holds only SKF output. To exclude a folder SKF leaves indexed, the user adds the entry after setup has run with ccc. Once that record exists, a folder value the user lists in `exclude_patterns` that the record does not hold stays the user's: setup never adopts it into the record and never removes it. The one exception is a record that still names per-entry patterns for that folder when none of them is left in `exclude_patterns`: a setup run swapped them for the bare pattern and stopped before it saved its record, so the bare pattern is SKF's and setup checks the folder again.
 
 ### Deferred Discovery (Remote Sources)
 
-For remote repository sources (GitHub URLs), CCC cannot operate during step 2b because no local code exists yet. The workspace clone or ephemeral clone happens in step 3. To provide CCC pre-ranking for remote sources:
+For remote repository sources (GitHub URLs), CCC cannot operate during step 2b because no local code exists yet. Step 3 reads the source into a private tree and moves SKF's workspace clone to the same commit (`skf-source-tree.py resolve`); ccc indexes that clone, which persists, never the tree, which the run removes. To provide CCC pre-ranking for remote sources:
 
 1. **step 2b:** Detects remote source, sets `{ccc_discovery: []}`, displays deferred message
-2. **step 3:** 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 3 (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 3 (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.
+2. **step 3:** 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`); `remote_clone_path` is set only when the clone holds the commit the run reads
+3. **step 3 (workspace reuse):** If `{remote_clone_path}/.cocoindex_code/settings.yml` already exists, `skf-merge-ccc-exclusions.py --clone-root` appends any missing standard exclusions, and step 3 runs a plain `ccc index`. The pass is incremental, so an unchanged repository costs almost nothing, and an edited exclude or include pattern takes effect in the same pass.
+4. **step 3 (first-time path):** If no existing CCC index, `skf-merge-ccc-exclusions.py --clone-root` runs `ccc init -f` in the clone and applies standard build/dependency exclusions (node_modules, dist, .git, vendor, etc.) to `settings.yml`, then step 3 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 3:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
+6. **step 3 (leave the workspace clone clean):** The first `ccc init` in a workspace clone, or a `ccc index` that initializes it, appends `# CocoIndex Code (ccc)` and `/.cocoindex_code/` to the clone's tracked `.gitignore`, a local change that makes git refuse a later checkout of another ref. Once the block is done with a workspace clone, `skf-ccc-git-hygiene.py workspace` restores the tracked `.gitignore` (or deletes one holding only those lines) and lists `.cocoindex_code/` and `/.skf-workspace.lock` in the clone's `.git/info/exclude`. create-skill's `skf-source-tree.py resolve` runs the same check before it moves the clone, and update-skill runs it before it moves the clone to the commit an update recorded; each also repairs a clone an earlier SKF left edited. audit-skill never moves the clone: its `[C]` reads the newer ref into a tree of the run's own. Any other local change is left alone: create-skill and update-skill then leave the clone where it is, and create-skill still reads its own tree. update-skill reads a remote skill's source from a checkout of the run's own, which no ccc index covers, so it runs no ccc search there: re-extraction skips ccc ranking and rename detection keeps its ast-grep comparison. audit-skill's `[C]` tree has no index either, so its relocation check lists the candidate files with `git grep` there.
 
-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.
+For workspace repos, the CCC index persists at `{remote_clone_path}/.cocoindex_code/` and is reused across forges, projects, and sessions. When step 3 could not move the clone to the commit it reads, it indexes nothing and registers nothing in `ccc_index_registry`: an index of that clone would not match the skill's commit, and the private tree is removed at the end of the run.
 
 ### Relationship to QMD Registry
 
@@ -131,8 +146,9 @@ 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 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.)
+- Indexing without configuring exclusions — for project root indexes, apply SKF exclusions (framework/output directories); for workspace repo indexes, apply standard build artifact exclusions in the `**/name` form (`**/node_modules`, `**/dist`, `**/build`, etc.), each written as a single-quoted YAML list item (`- '**/build'`), because ccc matches nothing with a trailing-slash form such as `build/`, and YAML reads an unquoted leading `*` as an alias, so ccc cannot load the file
+- 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.
+- Running `ccc reset` to apply edited patterns or to repair an index missing the source language — a plain `ccc index` applies pattern edits, and a missing language is fixed in `include_patterns`. `ccc reset` deletes the index databases but keeps `settings.yml`; a `ccc index` right after it can fail and leave the project with no index until `ccc daemon restart`; and run from a folder without its own `settings.yml`, it deletes the enclosing project's index. Its real uses (switching the embedding model, or an index database `ccc doctor` reports as unreadable) are outside SKF.
 - Skipping CCC discovery for remote sources without deferring to step 3 — remote repos deserve the same pre-ranking as local sources
 
 ## Related Fragments

package/src/knowledge/confidence-tiers.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-Every extracted claim carries a confidence tier label — T1, T1-low, T2, or T3 — that tells consuming agents how much to trust the information. The tier determines citation format, affects scoring weights, and governs how claims interact during updates and audits.
+Every extracted claim carries a confidence tier label (T1, T1-low, T2, or T3) that tells consuming agents how much to trust the information. The label follows the tool that produced the claim, not the forge tier the run used. It determines citation format and governs how claims interact during updates and audits.
 
 ## Rationale
 
@@ -15,7 +15,7 @@ Without confidence tiers:
 
 With confidence tiers:
 - Each claim transparently declares its evidence strength
-- Scoring weights adjust based on the distribution of tiers
+- Agents and reviewers can tell a signature ast-grep matched from one read by eye
 - Update workflows know which claims to re-verify first
 
 ## Tier Definitions
@@ -142,17 +142,21 @@ Every generated skill includes a confidence distribution in `metadata.json`:
     "t2": 12,
     "t3": 3
   },
-  "confidence_tier": "Deep"  // valid values: "Quick", "Forge", "Forge+", "Deep"
+  "confidence_tier": "Deep"  // single skill: "Quick", "Forge", "Forge+" or "Deep"; stack: "T1", "T1-low", "T2" or "T3"
 }
 ```
 
-This distribution feeds into test-skill scoring — skills with higher T1 ratios score better on signature accuracy.
+`confidence_tier` uses a different scale per `skill_type`. A single skill records the forge tier it was compiled at (Quick, Forge, Forge+ or Deep). A stack skill records the dominant confidence tier of its libraries (T1, T1-low, T2 or T3) and keeps its forge tier in `forge_tier`. The export gate checks the value against the scale of the skill's `skill_type`. An older stack may still hold its forge tier in `confidence_tier`: the gate accepts it with a low warning, and re-running Stack Skill records the dominant tier.
+
+The distribution counts each provenance entry once, by its `signature_source`, so it reports how each signature was obtained. It does not feed test-skill scoring: `compute-score.py` does not read these counts, and for library skills coverage-check §4b checks only that the bins sum to the documented-export count.
+
+A stack skill is the exception to that unit: its `confidence_distribution` counts each library once, in the bin of the tier create-stack-skill's extraction step sets for it (`per_library_extractions[].confidence`: in code mode `T1` only when it recorded exports and an ast-grep rule matched each one, in compose mode the constituent's own tier), so the four bins sum to `library_count`. Its evidence report bins the provenance entries.
 
 ## Anti-Patterns
 
 - Omitting the confidence tier from a citation — every citation must declare its level
 - Using T1 format (`[AST:...]`) when ast-grep was not actually used for that extraction
-- Treating T1-low and T1 as equivalent during scoring — they have different weight impacts
+- Labeling by forge tier instead of by tool: a signature read by eye is T1-low with a `[SRC:...]` citation even at Forge or Deep tier, because nothing structural verified it
 - Adding T2 enrichment without a QMD citation — enrichment without provenance is hallucination
 
 ## Related Fragments

package/src/knowledge/overview.md

@@ -6,7 +6,7 @@ Agent-level knowledge files capture cross-cutting principles and patterns that F
 
 ## Rationale
 
-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.
+The SKF module has 15 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 — workflow connections, artifact flow, decision rules for workflow selection, pipeline invocation syntax and aliases | All 14                             |
+| [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 15                             |
 | [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                 |
@@ -35,7 +35,7 @@ With knowledge files:
 | [architecture-verification.md](architecture-verification.md) | Pre-code verification pipeline, integration verdicts, iteration loop | VS, RA, SS                        |
 | [doc-fetcher.md](doc-fetcher.md)                           | T3 external documentation fetching, quarantine rules, tool-agnostic | CS, QS                             |
 | [split-body-strategy.md](split-body-strategy.md)           | Selective vs full split-body, detection pattern, agent accuracy   | CS, QS, US, TS, EX                |
-| [version-paths.md](version-paths.md)                       | Version-aware storage layout, path templates, export manifest v2, migration | CS, QS, SS, US, AS, TS, EX, VS, RA |
+| [version-paths.md](version-paths.md)                       | Version-aware storage layout, path templates, export manifest v2, ownership gate, flat migration (US, AS, TS, EX) | CS, QS, SS, US, AS, TS, EX, VS, RA |
 | [overview.md](overview.md)                                 | Knowledge map and JiT loading protocol (this file)               | All (entry point)                  |
 
 ## JiT Loading Protocol

package/src/knowledge/progressive-capability.md

@@ -24,7 +24,7 @@ With progressive capability:
 | --- | --- | --- | --- |
 | Quick | No tools required | Fast, template-driven, package-name resolution | Speed-first skill creation |
 | Forge | ast-grep available | AST-backed structural analysis, line-level citations | Precision-focused compilation |
-| Forge+ | ast-grep + ccc | Semantic discovery + AST verification, pre-ranked extraction | Intelligent precision compilation |
+| Forge+ | ast-grep + ccc | Semantic discovery + AST verification | Intelligent precision compilation |
 | Deep | ast-grep + gh + qmd | AST + GitHub exploration + QMD synthesis, maximum provenance | Full intelligence pipeline |
 
 ## Pattern Examples
@@ -81,8 +81,8 @@ Deep:   "Full intelligence pipeline — AST verification plus GitHub exploration
 **Implementation:**
 - **Quick:** Reads source files, applies pattern matching for exports and signatures, produces T1-low citations. Uses `gh_bridge` for file structure when available as a convenience, not a requirement.
 - **Forge:** Uses `ast_bridge.scan_definitions()` for structural parsing, produces T1 citations with exact AST node types. Falls back to source reading for files ast-grep cannot parse.
-- **Forge+:** Identical extraction to Forge, plus ccc semantic pre-discovery narrows the file set before ast-grep runs. For large codebases, `ccc_bridge.search()` produces a ranked candidate list. ast-grep operates on that list rather than the full tree. All results remain T1 (AST-verified) — ccc is upstream, not in the extraction chain.
-- **Deep:** Identical extraction to Forge, plus QMD enrichment in a separate step. T2 annotations layer on top of the T1 base without replacing it.
+- **Forge+:** Identical extraction to Forge, plus ccc semantic pre-discovery: `ccc_bridge.search()` ranks the source files, and the files a step reads by eye follow that order, while the recipe runner reads every file in scope. Labels follow the tool exactly as at Forge (ccc is upstream, not in the extraction chain): an ast-grep match is T1 (AST-verified), an export read by eye is T1-low.
+- **Deep:** Identical extraction to Forge, plus QMD enrichment in a separate step. T2 annotations layer on top of the extracted T1 and T1-low base without replacing it.
 
 *Bridge names (`gh_bridge`, `ast_bridge`, `ccc_bridge`, `qmd_bridge`) are conceptual interfaces. See [tool-resolution.md](tool-resolution.md) for concrete tool resolution per IDE.*
 
@@ -97,9 +97,9 @@ Deep:   "Full intelligence pipeline — AST verification plus GitHub exploration
 
 **Implementation:**
 - **Forge/Deep (Naive mode — individual skill):** Coherence weight (18%) redistributed to remaining categories: Export Coverage 45%, Signature Accuracy 25%, Type Coverage 20%, External Validation 10%. All four active categories are scored with AST-backed data.
-- **Quick (any mode):** Signature Accuracy and Type Coverage are skipped (no AST available). Their weights redistribute proportionally to remaining active categories. For a Quick-tier individual skill (naive mode): after both adjustments (coherence removal + AST-dependent category removal), only Export Coverage and External Validation remain active — approximate redistributed weights: Export Coverage ~82%, External Validation ~18% (exact values depend on proportional redistribution; see scoring-rules.md for the calculation). When external validation tools (skill-check, tessl) are also unavailable, their weight is further redistributed, leaving Export Coverage as the sole scoring axis.
+- **Quick (any mode):** Signature Accuracy and Type Coverage are skipped (no AST available). Their weights redistribute proportionally to remaining active categories. For a Quick-tier individual skill (naive mode): after both adjustments (coherence removal + AST-dependent category removal), only Export Coverage and External Validation remain active, with approximate redistributed weights: Export Coverage ~82%, External Validation ~18% (exact values depend on proportional redistribution; skf-test-skill's `scripts/compute-score.py` computes them). When the external validators (skill-check, and Tessl Review when the user opted in) also produce no score, their weight is further redistributed, leaving Export Coverage as the sole scoring axis.
 - **Forge (Contextual mode):** Export Coverage 36%, Signature Accuracy 22%, Type Coverage 14%, Coherence 18%, External Validation 10%. Full AST-backed verification. When external validation tools are unavailable, their 10% is redistributed proportionally.
-- **Forge+ (Contextual mode):** Same weights as Forge. The improved extraction coverage (from ccc pre-ranking) may increase T1 count and reduce gaps, but the scoring weights themselves do not change.
+- **Forge+ (Contextual mode):** Same weights as Forge.
 - **Deep (Contextual mode):** Same weights as Forge, plus cross-repo verification and QMD coherence checks feed into the coherence score.
 
 **Key Points:**
@@ -117,9 +117,9 @@ When a tool becomes unavailable mid-session (e.g., ast-grep uninstalled between
 
 When source is remote (GitHub URL) and tier is Forge, Forge+, or Deep:
 1. AST extraction requires local files — ast-grep cannot operate on remote URLs
-2. The extraction step attempts an **ephemeral shallow clone** to a system temp path (if `git` is available)
-3. If the clone succeeds: AST extraction proceeds on the local clone, then the temp directory is cleaned up
-4. If the clone fails (or `git` is unavailable): the step warns the user explicitly and degrades to source reading (T1-low) with actionable guidance
+2. The extraction step reads the resolved commit into a **private tree** of the run's own (if `git` is available), from SKF's workspace clone of the repository when it holds the commit and from the remote otherwise
+3. If the tree is read: AST extraction proceeds on it, and the tree is removed at the end of the run
+4. If no tree can be read (or `git` is unavailable): the step warns the user explicitly and degrades to source reading (T1-low) with actionable guidance
 5. Silent degradation is forbidden — the user must always know when AST extraction was skipped and why
 
 ## Anti-Patterns

package/src/knowledge/provenance-tracking.md

@@ -54,7 +54,7 @@ With provenance tracking:
       "source_line": 23,
       "confidence": "T1",
       "extraction_method": "ast-grep",
-      "ast_node_type": "export_statement > function_declaration",
+      "ast_node_type": "export_statement",
       "signature_source": "T1"
     },
     {
@@ -78,6 +78,7 @@ With provenance tracking:
 - Each entry uses structured fields (`export_name`, `params[]`, `return_type`) for incremental updates
 - `ast_node_type` is null for non-AST extractions — never fabricated
 - `extraction_method` distinguishes how the entry was obtained
+- An ast-grep entry's `ast_node_type` is the `kind` the matching pattern or recipe declares in create-skill's `extraction-patterns.md`, copied because ast-grep's output never reports a match's kind. A TypeScript export records `export_statement`: its `export ...` recipe matches the whole export statement, not the `function_declaration` or `class_declaration` inside it. A name exported through a list records `export_specifier`, the one specifier that names it: a re-export (`export { a, b as c } from '...'`, the `js-reexports` recipe) or a local list with no `from` (`export { a, b as c }`, the `js-local-exports` recipe)
 - Confidence tier is recorded per-entry, not per-file
 - `params` is an array of typed strings (e.g., `"userId: string"`) — enables param-by-param diffing
 
@@ -140,19 +141,22 @@ With provenance tracking:
 
 **Implementation:**
 1. Load existing provenance map
-2. Identify claims that need re-extraction (from audit drift report or source change detection)
-3. Re-extract only affected claims using current tier tools
-4. Merge fresh provenance entries into the existing map:
+2. Read the source at one commit: the commit the skill's `source_ref` points to now (or the ref `--target-ref` names), in a checkout of the update's own, so change detection and re-extraction read the same tree
+3. Identify claims that need re-extraction (from audit drift report or source change detection)
+4. Re-extract only affected claims using current tier tools
+5. Merge fresh provenance entries into the existing map:
    - Changed entries: replace with new provenance
    - Unchanged entries: preserve existing provenance (timestamp unchanged)
    - Removed exports: remove from provenance map
    - New exports: add with fresh provenance
-5. Regenerate evidence report reflecting the update
+6. Record the commit the update read as `source_commit` in `metadata.json` and `provenance-map.json` (and the ref as `source_ref` when `--target-ref` re-pinned the skill); a gap-driven update keeps both
+7. Regenerate evidence report reflecting the update
 
 **Key Points:**
 - Selective re-extraction — only changed entries are re-processed
 - Provenance timestamps show when each entry was last verified
 - The merge preserves \[MANUAL\] section provenance (author: "manual", no source location)
+- `source_commit` always names the commit the citations were read from
 
 ### File-Level Provenance (file_entries)
 

package/src/knowledge/qmd-registry.md

@@ -135,15 +135,15 @@ Then append/replace the registry entry in forge-tier.yaml. Failures never block
 
 ### Example 2: Consumer Discovery (audit-skill)
 
-**Context:** Audit-skill needs temporal context for drift detection.
+**Context:** Audit-skill's Deep-tier semantic diff retrieves what the skill documents about each export, then checks each claim against the current source.
 
-**Implementation:** Read `qmd_collections` from forge-tier.yaml. Find entry where `skill_name` matches AND `type` is `"extraction"`. If found, query via qmd_bridge. If not found, log and continue without T2 enrichment — not an error.
+**Implementation:** Read `qmd_collections` from forge-tier.yaml. Find entry where `skill_name` matches AND `type` is `"extraction"`. If found, query via qmd_bridge. If not found, log it and read the skill's own files instead (the direct-content fallback, labeled T1-low-fallback): not an error.
 
 ### Example 3: Janitor Hygiene (setup)
 
 **Context:** Setup-forge verifies QMD health on every run.
 
-**Implementation:** Cross-reference live QMD collections against registry. Classify as healthy (in both), orphaned (in QMD only), or stale (in registry only). Prompt user before removing orphans. Silently clean stale registry entries.
+**Implementation:** Cross-reference live QMD collections against registry. Classify as healthy (in both), orphaned (in QMD only, and indexed from a folder inside this project: QMD's index is shared by every project on the machine, so another project's collections never count), or stale (in registry only). Prompt user before removing orphans, and check each one's folder again just before removing it. Silently clean stale registry entries.
 
 ## Related Fragments
 

package/src/knowledge/skf-knowledge-index.csv

@@ -11,6 +11,6 @@ manual-section-integrity,Manual Section Integrity,"[MANUAL] preservation — mar
 qmd-registry,QMD Collection Registry,"Progressive registry architecture — producer/consumer/janitor roles, collection gate principle, forge-tier.yaml registry schema","qmd,registry,collections,deep,indexing",core,knowledge/qmd-registry.md
 doc-fetcher,Doc Fetcher,"T3 external documentation — tool-agnostic URL fetching, quarantine rules, conflict resolution","doc-fetcher,t3,external,documentation,quarantine",extended,knowledge/doc-fetcher.md
 architecture-verification,Architecture Verification,"Pre-code verification pipeline — VS/RA/SS-compose lifecycle, integration verdicts, coverage analysis, iteration loop","architecture,verification,stack,feasibility,integration,vs,ra,ss,compose",core,knowledge/architecture-verification.md
-split-body-strategy,Split-Body Strategy,"Selective split guidance — detection pattern, recommended approach, impact on tessl scores and snippet anchors","split-body,selective-split,references,body-size",core,knowledge/split-body-strategy.md
+split-body-strategy,Split-Body Strategy,"Selective split guidance — detection pattern, recommended approach, impact on agent accuracy and snippet anchors","split-body,selective-split,references,body-size",core,knowledge/split-body-strategy.md
 tool-resolution,Tool Resolution,"Bridge-to-tool and subprocess-to-tool mapping — ast_bridge, ccc_bridge, qmd_bridge, gh_bridge resolution per IDE, subprocess Pattern 1-4 definitions","bridge,tools,resolution,subprocess,mcp,cli,ide",core,knowledge/tool-resolution.md
-version-paths,Version-Aware Paths,"Version-nested directory structure — path templates, version resolution, export manifest v2, migration from flat layout, version sanitization","version,paths,directory,structure,migration,manifest,symlink",core,knowledge/version-paths.md
+version-paths,Version-Aware Paths,"Version-nested directory structure — path templates, version resolution, export manifest v2, ownership gate for skills SKF did not generate, migration from flat layout, version sanitization","version,paths,directory,structure,migration,manifest,symlink,ownership",core,knowledge/version-paths.md

package/src/knowledge/skill-lifecycle.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-The 14 SKF workflows form an end-to-end pipeline from source discovery through verified export, with a pre-code architecture verification path and post-distribution management operations. Each workflow produces artifacts consumed by downstream workflows. Understanding the lifecycle enables Ferris to recommend the right workflow for a user's situation and to maintain artifact continuity across the pipeline.
+The 15 SKF workflows form an end-to-end pipeline from source discovery through verified export, with a pre-code architecture verification path, post-distribution management operations, and campaigns that drive many skills through the pipeline. Each workflow produces artifacts consumed by downstream workflows. Understanding the lifecycle enables Ferris to recommend the right workflow for a user's situation and to maintain artifact continuity across the pipeline.
 
 ## Rationale
 
@@ -31,6 +31,7 @@ With lifecycle awareness:
 | Verification | TS (Test Skill) | Quality gate — completeness scoring | Test report, pass/fail decision |
 | Distribution | EX (Export Skill) | Package and inject into agent context | agentskills.io bundle, snippets |
 | Management | RS, DS (Rename/Drop) | Rename or retire skills and versions | Renamed skill group, deprecated/purged versions |
+| Orchestration | CA (Campaign) | Drive many skills through the pipeline in dependency order, across sessions | `_campaign-state.yaml`, `campaign-report.md`, and each skill's own artifacts |
 
 ## Typical Flows
 
@@ -115,10 +116,12 @@ RS or DS → EX
 | --- | --- |
 | User knows exactly what to skill, has a brief | CS directly |
 | User knows the library but needs scope guidance | BS → CS |
+| User wants a verified skill from one repo or doc URL, without writing a brief | `forge-auto <repo-or-doc-url>` |
 | User has a package name, wants fast results | QS |
 | User wants to skill their entire project | AN → CS (batch) |
 | User has an existing skill that may be outdated | AS → US |
 | User wants to verify tech stack before building | CS×N → VS → RA → SS (compose) |
+| User needs many skills built in dependency order across sessions | CA |
 
 **Key Points:**
 - SF is always prerequisite (but only needs to run once per project)
@@ -141,7 +144,7 @@ TS → {forge_version}/test-report.md (pass/fail gate)
        ↓ (passing skill consumed by EX — resolved via export manifest v2)
 EX → agentskills.io bundle + context snippets (flat platform paths)
 
-VS → feasibility-report-{project_name}.md (verdict + integration verdicts)
+VS → feasibility-report-{project_slug}-{timestamp}.md + a feasibility-report-{project_slug}-latest.md copy (verdict + integration verdicts)
        ↓ (report consumed by RA)
 RA → refined-architecture-{arch_project_name}.md (gaps filled, issues flagged, improvements suggested)
        ↓ (refined doc consumed by SS compose-mode)
@@ -169,18 +172,22 @@ SS (compose) → SKILL.md (stack skill synthesized from individual skills + arch
 
 ## Pipeline Invocation
 
-Users can chain workflows by providing multiple codes to Ferris:
+Users can chain workflows by providing multiple codes to Ferris, or one of four aliases:
 
 ```
-BS CS TS EX           — space-separated
-forge                 — alias for BS CS TS EX
-forge-quick           — alias for QS TS EX
-onboard               — alias for AN CS TS EX
-maintain              — alias for AS US TS EX
-CS[cocoindex] TS[min:80] EX  — with arguments and circuit breakers
+BS CS TS EX                             # codes, space- or arrow-separated
+forge-auto <repo-or-doc-url>            # auto-scope, auto-brief, compile, test and export
+forge <repo-url-or-path> <skill-name>   # alias for BS CS TS EX
+forge-quick <package-or-url>            # alias for QS TS EX
+maintain <skill>                        # alias for AS US TS EX
+CS[cocoindex] TS[min:80] EX             # a target argument and a circuit-breaker override
 ```
 
-Pipelines automatically activate headless mode. The forger passes data between workflows using the artifact flow described above. Circuit breakers halt the pipeline when output quality falls below a threshold (e.g., TS score < 60 blocks EX). See `shared/references/pipeline-contracts.md` for the full specification.
+A chain of codes whose first workflow lacks its input, such as `QS TS EX`, asks for that input before any workflow runs (`SF` and `SS` take none), and a headless one halts there instead. A leading `SF` is passed over, so `SF QS TS EX` asks for QS's target. A chain led by `BS` gets its target and skill name only as `forge <repo-url-or-path> <skill-name>`, `RS` and `DS` need more than one bracket and run on their own, a first code other than `CS` whose bracket already holds `auto`, or an AN or TS whose bracket holds `min:N` (such as `TS[min:80] EX`), is named as a conflict instead of asked, since a bracket holds one value, and a headless chain led by `CS` leaves the brief to create-skill, which compiles the only one and halts naming them when there are several.
+
+`forge-auto` is the one-command verified path: it needs no brief, and its test step is stricter than the other pipelines'. `CA` (campaign) is not an alias and does not chain with other codes: it is a workflow of its own that drives many skills through this pipeline in dependency order and can resume across sessions.
+
+Pipelines automatically activate headless mode. The forger passes data between workflows using the artifact flow described above. A circuit breaker halts the pipeline on the gate a workflow's result fails: TS on any verdict but PASS, VS on zero coverage. `shared/references/pipeline-contracts.md` holds each alias's expansion and every threshold its gates apply, and Test Skill's `skf-test-skill/references/init.md` §1b the test threshold each pipeline uses.
 
 ## Integration Points
 
@@ -198,4 +205,4 @@ Pipelines automatically activate headless mode. The forger passes data between w
 - [provenance-tracking.md](provenance-tracking.md) — how provenance flows through the pipeline
 - [version-paths.md](version-paths.md) — version-aware storage layout, path templates, and migration rules
 
-_Source: synthesized from all 14 SKILL.md files (including VS, RA, RS, DS) and module-help.csv_
+_Source: synthesized from all 15 workflow SKILL.md files (including VS, RA, RS, DS, CA) and module-help.csv_

package/src/knowledge/split-body-strategy.md

@@ -10,14 +10,12 @@ Vercel research shows inline passive context achieves 100% task accuracy vs 79%
 
 Without selective split awareness:
 - `skill-check split-body --write` extracts everything, reducing agent effectiveness
-- tessl content scores drop dramatically (65% → 38%) because only SKILL.md body is evaluated
 - Context snippet anchors (`#quick-start`, `#key-types`) may break if those sections move to references
 
 With selective split awareness:
 - Only the largest Tier 2 section(s) are extracted (usually Full API Reference or Full Type Definitions)
 - Quick Start, Key API Summary, Key Types, Migration Warnings stay inline
 - Agent accuracy remains high for common tasks
-- tessl scores reflect actual inline content quality
 
 ## Split-Body Detection Pattern
 
@@ -50,6 +48,5 @@ Split-body affects only SKILL.md content movement to `references/`. The `scripts
 
 - [agentskills-spec.md](agentskills-spec.md) — 500-line guideline for SKILL.md body size and the `references/` directory structure
 - [skill-lifecycle.md](skill-lifecycle.md) — where split-body decisions fit in the compilation pipeline
-- `test-skill/references/scoring-rules.md` — tessl/split-body interaction and the pre-split baseline recommendation during test reporting
 
 _Source: derived from agentskills.io split-body guidance and Vercel agent accuracy research (inline vs on-demand retrieval)_