bmad-module-skill-forge 7.0.0 → 8.0.0

package/src/skf-test-skill/references/coverage-check-tiers.md

@@ -4,13 +4,13 @@ Load this file only from coverage-check.md §2, and follow the one section §2 n
 
 ## Quick Tier
 
-- **A skill quick-skill built** (`metadata.json` `generated_by` is `quick-skill`), or **any skill in Python, JavaScript or TypeScript**, **from local source** (State 1): parse the entry points with `{extractPublicApiHelper}` `--mode quick`. quick-skill built its export list with that parser, so both sides count one surface, and in those three languages it gives each name the file that defines it (`defined_in`), so the brief's globs place the name as the recipe runner does. Resolve it ← first existing path in `{extractPublicApiProbeOrder}` and run it once per package in scope, with its manifest and one `--entry-file` for each entry-point file the Source API Surface Definition makes its surface, each path relative to `{source_path}` (`<n>` counts the packages from 1):
+- **A skill quick-skill built** (`metadata.json` `generated_by` is `quick-skill`), or **any skill in Python, JavaScript or TypeScript**, **from local source** (State 1): parse the entry points with `{extractPublicApiHelper}` `--mode quick`. quick-skill built its export list with that parser, so both sides count one surface (except names quick-skill took from a README for a star re-export from another package: the parser gives that star no name, so those names read as stale), and in those three languages it gives each name the file that defines it (`defined_in`), so the brief's globs place the name as the recipe runner does. Resolve it ← first existing path in `{extractPublicApiProbeOrder}` and run it once per package in scope, with its manifest and one `--entry-file` for each entry-point file the Source API Surface Definition makes its surface, each path relative to `{source_path}` (`<n>` counts the packages from 1):
 
   ```bash
   uv run {extractPublicApiHelper} --mode quick --language <language> --source-root "{source_path}" --manifest-file <manifest path> --entry-file <entry path> > "{run_dir}/quick-<n>.json"
   ```
 
-  Its `warnings` name each statement whose names the entry file alone cannot give. Read by eye only the statements its warnings name, save the names they give as a per-file result for the entry file that holds the statement, `{"file": "<entry path>", "exports_found": [<each name>], "signature_mismatches": []}`, and list those names in the Coverage Analysis section as read by eye. Give `surface` one `--quick` per package, one `--per-file` per saved result, the brief when the skill has one (its globs give the `scope.include` and `tier_a_include` sets), the metadata and, when init.md §2 bound one, the provenance map (the baselines of the §2b candidates and guards; they add no name):
+  Its `warnings` name each statement whose names the entry file alone cannot give. Read by eye only the statements its warnings name, save the names they give as a per-file result for the entry file that holds the statement, `{"file": "<entry path>", "exports_found": [<each name>], "signature_mismatches": []}`, and list those names in the Coverage Analysis section as read by eye. A warning on an `export *` or `export type *` from another package (a specifier that is no relative path; the warning writes either as `export *`) gives no name, as the recipe runner leaves such a star unresolved: list the statement as the source writes it, `<line>: <statement>`, in the `unresolved_stars` of that entry file's per-file result, and in the Coverage Analysis section as unresolved. Give `surface` one `--quick` per package, one `--per-file` per saved result that lists a name, the brief when the skill has one (its globs give the `scope.include` and `tier_a_include` sets), the metadata and, when init.md §2 bound one, the provenance map (the baselines of the §2b candidates and guards; they add no name):
 
   ```bash
   uv run {coverageInputsScript} surface --quick "{run_dir}/quick-<n>.json" [--per-file "{run_dir}/per-file-<n>.json"] [--brief "{forge_data_folder}/{skill_name}/skill-brief.yaml"] --metadata "{resolved_skill_package}/metadata.json" [--provenance "{forge_provenance_map}"] [--monorepo] [--pattern-reference-intent] [--curated-subset] [--barrel <state>] --output "{run_dir}/surface.json"
@@ -26,7 +26,7 @@ The recipe runner cannot be used, so subagents read the files in scope one at a
 uv run {scoreSignaturesScript} plan --inventory "{run_dir}/inventory.json" --output "{run_dir}/signature-plan.json"
 ```
 
-For each source file that defines public API exports, delegate a subagent that gets that map with the file and the absolute path of `{signatureRulesFile}` (under `{skill-root}`). It gets the `documentedAlternatives` map too, whose forms it compares as that file says. It extracts the symbols the file exports, with their full signatures, with ast-grep (or reads the file when `extraction.fallback.reason` says no ast-grep can run; list those files in the Coverage Analysis section as read by eye), leaves out a name the file only passes on from another module of the source being tested (`export { x } from './x'`, `export * from`, an `__init__.py` import, a Rust `pub use`), which that module's own result counts, keeps a name it passes on from another package (`export { z } from 'zod'`), which no other result counts, compares each with the map's entry by the rules of that file (overload sets and `difference` tags included), gives each mismatch the `line` that defines the export, and returns only `{"file", "exports_found": [...], "types_found": [<the exported interfaces, type aliases, enums and classes>], "signature_mismatches": [...]}`, each mismatch in the shape §2's signature comparison returns. Save each response to `{run_dir}/per-file-<n>.txt` with the Write tool and build the surface from them, one `--per-file` each and `--fallback-scan` (each names the file that defines its exports, so a `scope.tier_a_include` list that counts none of them does not turn the guards off), with the same baselines as at Quick tier, and `--extraction` when the runner's JSON sent you here (`extraction.fallback.needed`): it adds no name, only its scope and the globs it lists as matching no file, so the guards still run:
+For each source file that defines public API exports, delegate a subagent that gets that map with the file and the absolute path of `{signatureRulesFile}` (under `{skill-root}`). It gets the `documentedAlternatives` map too, whose forms it compares as that file says. It extracts the symbols the file exports, with their full signatures, with ast-grep (or reads the file when `extraction.fallback.reason` says no ast-grep can run; list those files in the Coverage Analysis section as read by eye), leaves out a name the file only passes on from another module of the source being tested (`export { x } from './x'`, `export * from`, an `__init__.py` import, a Rust `pub use`), which that module's own result counts, keeps a name it passes on from another package (`export { z } from 'zod'`), which no other result counts, gives no name for an `export * from` or `export type * from` another package (a specifier that is no relative path; `export * as ns` still gives `ns`), which the recipe runner leaves unresolved, listing each such statement as `<line>: <statement>` in `unresolved_stars`, compares each with the map's entry by the rules of that file (overload sets and `difference` tags included), gives each mismatch the `line` that defines the export, and returns only `{"file", "exports_found": [...], "types_found": [<the exported interfaces, type aliases, enums and classes>], "signature_mismatches": [...], "unresolved_stars": [...]}`, each mismatch in the shape §2's signature comparison returns. List each response's `unresolved_stars` in the Coverage Analysis section as unresolved. Save each response to `{run_dir}/per-file-<n>.txt` with the Write tool and build the surface from them, one `--per-file` each and `--fallback-scan` (each names the file that defines its exports, so a `scope.tier_a_include` list that counts none of them does not turn the guards off), with the same baselines as at Quick tier, and `--extraction` when the runner's JSON sent you here (`extraction.fallback.needed`): it adds no name, only its scope and the globs it lists as matching no file, so the guards still run:
 
 ```bash
 uv run {coverageInputsScript} surface --per-file "{run_dir}/per-file-<n>.txt" --fallback-scan [--extraction "{run_dir}/extract-full.json"] [--brief "{forge_data_folder}/{skill_name}/skill-brief.yaml"] --metadata "{resolved_skill_package}/metadata.json" [--provenance "{forge_provenance_map}"] [--monorepo] [--pattern-reference-intent] [--curated-subset] [--barrel <state>] --output "{run_dir}/surface.json"

package/src/skf-test-skill/references/coverage-check.md

@@ -107,7 +107,7 @@ Only when the validated inventory's `references` is non-empty. Each `cross_check
 
 ### 2. Analyze Source Code (Tier-Dependent)
 
-Identify the public API surface from the package entry points (0b), as deep as the tier allows. Whichever branch runs, `{coverageInputsScript} surface` writes it to `{run_dir}/surface.json`, which §2b, §2c, §4 and step 5 read. Names read by eye reach it as per-file results, `{"file": "<path>", "exports_found": [<each name>], "signature_mismatches": []}` for each file, saved to `{run_dir}/per-file-<n>.json` with the Write tool and given to `surface` with one `--per-file` each.
+Identify the public API surface from the package entry points (0b), as deep as the tier allows. Whichever branch runs, `{coverageInputsScript} surface` writes it to `{run_dir}/surface.json`, which §2b, §2c, §4 and step 5 read. Names read by eye reach it as per-file results, `{"file": "<path>", "exports_found": [<each name>], "signature_mismatches": []}` for each file, saved to `{run_dir}/per-file-<n>.json` with the Write tool and given to `surface` with one `--per-file` each. An `export * from` or `export type * from` another package adds no name: list `<line>: <statement>` in `unresolved_stars` and Coverage Analysis.
 
 **Exits.** Every `{coverageInputsScript}` and `{scoreSignaturesScript}` command in §2 and §2b exits 0, or exits 1 with its error on stderr: HALT with it (`halt_reason: "helper-failed"`, phase `coverage-check:surface`). `surface` with a `--per-file`, and `score`, also exit 2 when a subagent response breaks the schema: re-dispatch that subagent once with its `violations[]` appended (or correct a result the main thread wrote), save the new response over the old one and run the command again; a second failure HALTs the same way.
 
@@ -298,7 +298,7 @@ uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coverage-check -
 uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coverage-check --from guards --input "{run_dir}/surface.json" --metadata "{resolved_skill_package}/metadata.json"
 uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coverage-check --from numerator --input "{run_dir}/numerator.json" --metadata "{resolved_skill_package}/metadata.json"
 uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coverage-check --from metadata-coherence --input "{run_dir}/metadata-coherence.json" --metadata "{resolved_skill_package}/metadata.json"
-uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coverage-check --from provenance-line --input "{run_dir}/provenance-verify.json"
+uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coverage-check --from provenance-line --input "{run_dir}/provenance-verify.json" [--stale "{run_dir}/stale.json"]
 ```
 
 **A split-body mismatch's Source** is a line inside the skill package: when §1b found one, load `{coverageBranchesFile}` and follow its **Split-Body Sources** section.

package/src/skf-test-skill/references/invocation-contract.md

@@ -59,7 +59,7 @@ When the emitter itself is not installed (init.md §0), no line can be printed:
 
 ## Result Files
 
-report.md §4c runs the emitter with `--result-dir "{forge_version}"`. It writes the per-run record `skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name, `-2`, `-3` appended when a run already took that second's name) and then its copy `skf-test-skill-result-latest.json`, the record of the last run whose emitter wrote this copy, at a stable path (a copy, not a symlink), each atomically. The record holds the envelope's fields, plus `skill`, `outputs[]` (the published report), `summary` (`score`, `threshold`, `result` (`PASS`, `PASS_WITH_DRIFT`, `FAIL` or `INCONCLUSIVE`), `testMode`, `activeCategories[]`, `inconclusiveReasons[]` when present, `threshold_fallback`, `original_threshold` and `evidence_report_path` when the threshold fallback fired, `gapCounts` with the gap ledger's gaps by severity, and `hardGate`), `runId` and `healthCheckDispatched`, and the emitter stamps `timestamp`, `run_id`, `headless_decisions` and `warnings` into it. A run the hard gate blocked writes it too, as a FAIL record, so its `skf-test-skill-result-latest.json` holds that FAIL, not an earlier run's verdict. A HALT writes no result file, and neither does a run cut off before report.md §4c: the copy then still holds an earlier run's verdict.
+report.md §4c runs the emitter with `--result-dir "{forge_version}"`. It writes the per-run record `skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name, `-2`, `-3` appended when a run already took that second's name) and then its copy `skf-test-skill-result-latest.json`, the record of the last run whose emitter wrote this copy, at a stable path (a copy, not a symlink), each atomically. The record holds the envelope's fields, plus `skill`, `outputs[]` (the published report), `summary` (`score`, `threshold`, `result` (`PASS`, `PASS_WITH_DRIFT`, `FAIL` or `INCONCLUSIVE`), `testMode`, `activeCategories[]`, `inconclusiveReasons[]` when present, `threshold_fallback`, `original_threshold` and `evidence_report_path` when the threshold fallback fired, `gapCounts` with the gap ledger's gaps by severity, and `hardGate`), `runId` and `healthCheckDispatched`, and the emitter stamps `timestamp`, `run_id`, `headless_decisions` and `warnings` into it. A run the hard gate blocked writes it too, as a FAIL record, so its `skf-test-skill-result-latest.json` holds that FAIL, not an earlier run's verdict, unless the run's line holds a `result_file_write_failed` warning (the emitter stops at the first write that fails). A HALT writes no result file, and neither does a run cut off before report.md §4c: the copy then still holds an earlier run's verdict.
 
 ## Emitting a Halt
 

package/src/skf-test-skill/references/report.md

@@ -235,7 +235,7 @@ and bind `{report_file}` ← `{publishedReportFile}`. If the move fails, HALT (`
 uv run {emitEnvelopeHelper} emit --workflow skf-test-skill --run-dir "{run_dir}" --result-dir "{forge_version}" --target {emit_target} < "{run_dir}/result-context.json"
 ```
 
-It writes `{forge_version}/skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and then its `skf-test-skill-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path: a copy, not a symlink; a caller reads its own run's `SKF_TEST_RESULT_JSON` line), each atomically, so a partial write is never observable; stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both; and prints the `SKF_TEST_RESULT_JSON:` line. Bind `{result_line}` ← that line and `{result_path}` ← its `result_path`. A run the hard gate blocked writes the record too, as a FAIL (`status: "error"`, `verdict: "FAIL"`, `halt_reason: "hard-gate-blocked"`, `exit_code` 2), so after a blocked run `skf-test-skill-result-latest.json` holds its FAIL, never an earlier run's verdict. A result file that could not be written leaves `result_path` null and a `result_file_write_failed` warning in the line, and the run still finishes. If the emitter exits non-zero, run it once more; if it fails again, HALT (`halt_reason: "write-failed"`, phase `report:result-contract`) with its stderr: the run's result contract could not be written. `references/invocation-contract.md` lists the record's fields.
+It writes `{forge_version}/skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and then its `skf-test-skill-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path: a copy, not a symlink; a caller reads its own run's `SKF_TEST_RESULT_JSON` line), each atomically, so a partial write is never observable; stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both; and prints the `SKF_TEST_RESULT_JSON:` line. Bind `{result_line}` ← that line and `{result_path}` ← its `result_path`. A run the hard gate blocked writes the record too, as a FAIL (`status: "error"`, `verdict: "FAIL"`, `halt_reason: "hard-gate-blocked"`, `exit_code` 2), so after a blocked run `skf-test-skill-result-latest.json` holds its FAIL, never an earlier run's verdict, unless the run's line holds a `result_file_write_failed` warning (the emitter stops at the first write that fails). A per-run record that could not be written leaves `result_path` null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to the line, and the run still finishes. If the emitter exits non-zero, run it once more; if it fails again, HALT (`halt_reason: "write-failed"`, phase `report:result-contract`) with its stderr: the run's result contract could not be written. `references/invocation-contract.md` lists the record's fields.
 
 Once the result files are written, append `'report'` to `stepsCompleted` in the `{outputFile}` frontmatter (it stays out of the expected set above).
 

package/src/skf-test-skill/references/scoring-rules.md

@@ -45,7 +45,7 @@ This table is the single source of truth for classifying a gap. Every stage reco
 | Low      | `metadata`                  | Missing optional metadata or examples |
 | Low      | `description`               | Description trigger optimization recommended (third-person voice, negative triggers, or keyword coverage gaps), a Tessl Review description suggestion included |
 | Low      | `external-validator`        | A skill-check diagnostic or a Tessl Review validation finding the run left unresolved (external-validators §5b) |
-| Info     | `observation`               | Style suggestions, non-blocking observations, and a documented extra: a documented name outside the enumerated surface that is not a fabricated signature and that the source still declares at column 0 (a module so named counts, unless the inventory gives the name a `function`, `hook`, `class`, `interface`, `enum` or `type` kind, no provenance map entry of the name types it a `module` or `package` and the module is not a TS/JS file that is itself the export, with an `export default` or a `module.exports =`; among several declaring files, the one the skill cites on a line naming it; an `aliased` name, which an export-list item or a Python `from X import` item renames from a name its cited file declares, at that item's line, a multi-line list's item at its own line), found only in a Python or TS/JS source where classify-stale ran (the Forge, Forge+ or Deep tier, `analysis_confidence` `full`, `workspaceDrift` not `overridden` and a bound provenance map) and `surface.json` has a complete `extraction`: `Documented extra: {name}`, at that line, which update-skill never routes (coverage-check §2c). Also a partial signature: a mismatch the signature judge tags `omitted-optional` (defined in signature-comparison-rules.md, Difference tags) on a form the skill labels partial (simplified, key parameters, a `...` that stands in for omitted members, not rest or variadic syntax), which the inventory marks `signature_form: "partial"`, as score-signatures.py checks: `Partial signature: {name}`, at the declaration, counted as matching in Signature Accuracy (coverage-check §2 and §2b). Also a return annotation the body contradicts: a mismatch the signature judge tags `annotation-contradicted` (defined in signature-comparison-rules.md, Difference tags) whose documented signature states a return type and writes the source's parameters, and whose `evidence_line`, the body line that returns the documented type, comes after the declaration and before the next one and, with the local source, starts with `return` (or is a one-line declaration's own expression body), as score-signatures.py checks: `Annotation contradicted: {name}`, at the declaration, counted as matching in Signature Accuracy, with no change to the skill (the annotation is reported upstream) (coverage-check §2 and §2b) Also a documentation error a Deep-tier run sees that no script checks (an import path whose module does not export the name, a type member that differs from its declaration): `Not checked by script: {name}`, at the documenting line, written by hand (coverage-check §2 and §5b) |
+| Info     | `observation`               | Style suggestions, non-blocking observations, and a documented extra: a documented name outside the enumerated surface that is not a fabricated signature and that the source still declares at column 0 (a module so named counts, unless the inventory gives the name a `function`, `hook`, `class`, `interface`, `enum` or `type` kind, no provenance map entry of the name types it a `module` or `package` and the module is not a TS/JS file that is itself the export, with an `export default` or a `module.exports =`; among several declaring files, the one the skill cites on a line naming it; an `aliased` name, which a line elsewhere renames from the declaration its cited file holds (an export-list item `L as NAME` (`export { default as NAME } from` included, a whole-string side unquoted, a comment allowed before `export`), a plain `export { NAME }` of an import that renames (`import { L as NAME }`, `import NAME from`), a `const`, `let`, `var` or `type NAME = L` with a bare identifier `L`, a Python `from X import L as NAME` at column 0 or one level in a module-level `try`, `except`, `else`, `if` or `elif` block, or a Python `NAME = L`), at that line, a multi-line list's item at its own line; when the rename's relative or in-package `from` module, or the import that binds `L`, resolves to a file that declares `L`, that file must be the cited one, so a rename of another file's same-named declaration stays a fabricated signature, as do a type assertion, any other expression and an import inside a function or a class), found only in a Python or TS/JS source where classify-stale ran (the Forge, Forge+ or Deep tier, `analysis_confidence` `full`, `workspaceDrift` not `overridden` and a bound provenance map) and `surface.json` has a complete `extraction`: `Documented extra: {name}`, at that line, which update-skill never routes (coverage-check §2c). Also a partial signature: a mismatch the signature judge tags `omitted-optional` (defined in signature-comparison-rules.md, Difference tags) on a form the skill labels partial (simplified, key parameters, a `...` that stands in for omitted members, not rest or variadic syntax), which the inventory marks `signature_form: "partial"`, as score-signatures.py checks: `Partial signature: {name}`, at the declaration, counted as matching in Signature Accuracy (coverage-check §2 and §2b). Also a return annotation the body contradicts: a mismatch the signature judge tags `annotation-contradicted` (defined in signature-comparison-rules.md, Difference tags) whose documented signature states a return type and writes the source's parameters, and whose `evidence_line`, the body line that returns the documented type, comes after the declaration and before the next one and, with the local source, starts with `return` (or is a one-line declaration's own expression body), as score-signatures.py checks: `Annotation contradicted: {name}`, at the declaration, counted as matching in Signature Accuracy, with no change to the skill (the annotation is reported upstream) (coverage-check §2 and §2b) Also a documentation error a Deep-tier run sees that no script checks (an import path whose module does not export the name, a type member that differs from its declaration): `Not checked by script: {name}`, at the documenting line, written by hand (coverage-check §2 and §5b) |
 | Info     | `provenance-unverified`     | Provenance line not verified: the line-check rules found no definition line, or the recorded line is not a line number (`line-invalid`) (coverage-check §4c) |
 | Info     | `migration-section`         | Historical migration content in Section 4b with no T2-future annotation (Case 2 of `migration-section-rules.md`) |
 | Info     | `multi-denominator`         | Multi-denominator reporting: barrel and documented-surface clusters diverge by design (>10% cross-cluster) |

package/src/skf-test-skill/references/signature-comparison-rules.md

@@ -26,6 +26,8 @@ The names of Python's `*args` and `**kwargs` are never compared (`**kwargs` agai
 
 The source's declaration decides: the documented form is compared with the parameters, the optionality and the annotations the signature declares, with one exception, a return annotation the body contradicts (Annotations).
 
+A const annotated with a function type declares that type's parameters: `export const build: ViteBuilder['build'] = async ({ options }) => ...` takes the one parameter `ViteBuilder['build']` names, and the arrow's destructuring is that same parameter. A form may name it as the type does or destructure it as the arrow does, and a destructuring that names only some of the type's properties, in the arrow or in the form, does not read as a narrower type. A declaration whose parameter list is written only in a package outside the source tree (a binding destructured from a value cast to `typeof domTestingLibrary`, or `const spyOn: typeof vitestSpyOn = (...args) => ...`) has its parameters, their optionality and its return left uncompared and counts as matching, as a component whose props type lives there does (Components).
+
 In the split-body cross-check both forms are documented: each is read by these rules, a type, return type or type arguments one of them leaves out are not compared, and a parameter's optionality is compared only when both forms state it. An ellipsis claims nothing about the members it stands for, required ones included. A call, a list of bare names or a form its own file labels partial (each side's label is read from that side's file, not from the export's one `signature_form`) may leave out a parameter the other form does not state as required, unless leaving it out shifts a caller's positions (a language without keyword arguments, as above); any other form claims its list is complete, so leaving out a parameter the other writes is a mismatch (inventory-contract.md's examples). Each export's form is read alone: what the rows of other exports write, in the same table or file, states nothing about it, so `(action, sink, tracking_record, child_invalidation)` matches `child_invalidation: X | None = None` even when every other row of its table writes its defaults.
 
 A name the skill documents in several forms (a brief usage in SKILL.md, a full props list in a reference file) comes with `alternatives`: coverage-check.md §2's check lists them after its `documented` form, and the fallback per-file scan's `documentedAlternatives` holds them by name. Compare the declaration with each form the check offers, each by its own reading rules, and report a mismatch for each form that does not match, with its index as `form` (0 is `documented`, 1 the first alternative), its `documented_sig` written as that form and its `difference` tagged against it. With `candidates`, a form matches when it matches any candidate, and its mismatch is reported at the closest candidate.
@@ -38,7 +40,7 @@ A component is an export the source declares as one: a function that takes one p
 
 A component's own props are the members written in its package: its interface or object type, object literals intersected into it, and members computed from its own code (`VariantProps<typeof buttonVariants>`). Members of a type from another package (`React.ComponentProps<"button">`, `HTMLAttributes<...>`, `ComponentProps<typeof Link>`) are inherited, as are the `ref` a `forwardRef` result takes and the optional `children` of `PropsWithChildren<P>`. A prop the form writes must exist on `P`, own or inherited. A component whose props type lives in a package outside the source tree (`const Tabs = TabsPrimitive.Root`) has its props left uncompared: only that it is a component is checked.
 
-A prop the form writes that `P` lacks, or a type or an optionality it writes that the source contradicts, is a mismatch. So is a required own prop it leaves out, and a required inherited one (a `Link`'s `href`) left out of a full form. An optional own prop a typed props list or a table leaves out is an `omitted-optional` difference; one a list of bare names or a usage leaves out, and an optional inherited prop, is no difference. `| null` and `| undefined` on an optional prop are no difference (`VariantProps` adds both). A props type name the form writes that the source does not declare (`Button(props: ButtonProps)` against a source with no `ButtonProps`) is not compared by name, only the props the form lists. Values in a usage example (`variant="subtle"`) are not compared.
+A prop the form writes that `P` lacks, or a type or an optionality it writes that the source contradicts, is a mismatch. So is a required own prop it leaves out, and a required inherited one (a `Link`'s `href`) left out of a full form. An optional own prop a typed props list or a table leaves out is an `omitted-optional` difference; one a list of bare names or a usage leaves out, and an optional inherited prop, is no difference. A rest element in a component's destructured props form (`({ className, variant = "default", ...props }: NativeButtonProps)`) stands for every prop of `P` the form does not name, own or inherited, required ones included, so the form leaves none of them out, and the rest's own name is not compared as a prop. `| null` and `| undefined` on an optional prop are no difference (`VariantProps` adds both). A props type name the form writes that the source does not declare (`Button(props: ButtonProps)` against a source with no `ButtonProps`) is not compared by name, only the props the form lists. Values in a usage example (`variant="subtle"`) are not compared.
 
 A props list states optionality as Reading a form says: `({ of, meta, story })`, or a list of names, states none, and in an object type literal (`{ of?: X; meta: M }`) that states it for any member, each member written with no mark claims to be required. A table states optionality by a Required column, a `?` on a prop's name or a Default cell that gives a value; its Type column states types, never optionality. A Default cell with a value marks only its own row optional and an empty one states nothing, so Create Skill's `| Prop | Type | Default | Description |` table never reads a prop with an empty Default cell as required. A destructuring default (`({ of, meta = {} })`) likewise marks only its own member, and the others state no optionality.
 
@@ -46,6 +48,7 @@ A props list states optionality as Reading a form says: `({ of, meta, story })`,
 
 - A parameter written without a type is not compared on type: its name and order are, and its optionality as Reading a form says. Bare `*args` matches `*args: P.args`, and `**kwargs` matches `**kwargs: P.kwargs`.
 - A return type the form does not state is not compared. A form states one when its entry has a non-blank `return_type` or the form writes one: after `->`, `=>`, `→` or `):`, or in its language's own position (Go's result list after the parameters, the type before the name in C, C++ and Java). A blank `return_type` (`""`) states none, so an entry with `params: ""` and no return type matches `def f() -> None`.
+- A return written as names of values rather than types, a parenthesized list of names such as `→ (nodes, edges)` (after the arrow or in `return_type`), states no return type, so no return is compared. A type name written alone stays a type, lowercase ones included: `-> list` and `→ str` state one.
 - A type the source leaves unannotated, on a parameter or a return, is not compared, except that a TS/JS parameter with a literal default has that literal's type: `pageSize = 20` is a `number`, so `pageSize?: string` is a mismatch. An unannotated return stays uncompared.
 - A documented parameter type that names some of the members of the source's union is no mismatch, since a caller passing it makes a valid call (`schema: VectorSchemaProvider` against `VectorSchemaProvider | MultiVectorSchemaProvider`); a documented return type must cover every member the source can return.
 - Type arguments the form leaves out are not compared: `dict` matches `dict[str, Any]`, and `list[dict]` matches `list[dict[str, Any]]`. Type arguments it writes are: `dict[str, int]` against `dict[str, str]` is a mismatch.

package/src/skf-test-skill/scripts/gap-ledger.py

@@ -115,25 +115,46 @@ cites (never read; default `metadata.json`):
             name it (outside the citations), or on the next non-blank line
             after one, cite exactly one of those files: the gap
             is at that file's `declared_in` item, and two cited or none
-            leave it Medium. The documented extra's issue names the line
-            that documents it (with --skill-dir) and its remediation asks no
+            leave it Medium. The documented extra's remediation asks no
             change (update-skill never routes it) and says whether signature
             scoring compared its documented signature (a name the
             --signatures result lists in `comparedNames`). `excluded` is
             read once a stale name that is not fabricated needs it, and a
             malformed one is then INVALID_INPUT. Any other is a Medium `stale-documentation` gap
-            `Stale documentation: {name}` at the first line of SKILL.md,
-            then of references/*.md in path order, that writes the name
-            (validate-inventory.py's match, with --skill-dir), else
-            `SKILL.md`. One whose `excluded.outsideScope` row says the brief
+            `Stale documentation: {name}` at the line that documents the
+            name (with --skill-dir), else `SKILL.md`. That line is the
+            first that writes it as an export, the first tier that holds
+            the name winning: (1) its first origin in the documented
+            inventory's floor (load-coverage-inputs.py floor); (2) a
+            column-0 declaration of it in a fenced block of a language
+            floor's `_declared_names` reads (JS/TS, Python, Rust, Go),
+            cited or not, outside an HTML comment and a data block (json, yaml...);
+            (3) a heading, or the first cell of a table whose header's
+            first cell names exports (floor's table headers), whose text is
+            the name or holds a code span floor reads as the name; (4) a
+            line whose inline code span is the name, or the name directly
+            followed by `(`. Tiers 2 to 4 read SKILL.md, then every .md file
+            under references/, subfolders included, in path order, outside
+            the frontmatter (3 and 4 outside fenced code and HTML comments
+            too); within a tier the first file, then its lowest line, wins.
+            A bare word, or a span that holds the name among other words
+            (`uitripled add`), documents nothing; with no such line, or
+            without --skill-dir, the Source is `SKILL.md`. Floor's
+            InputError (no SKILL.md, or a top-level file it cannot read or
+            decode) leaves tier 1 empty, and a skill file that cannot be
+            read leaves tiers 2 to 4 empty. One whose
+            `excluded.outsideScope` row says the brief
             scopes its file out (`excludeGlob`, the `scope.exclude` glob
             that matches it, or `outsideInclude`, no `scope.include` glob
             covering it) has its own issue, naming the entry point and the
             file and line, and remediation: to keep the documentation,
             narrow that exclude glob (a removal needs a `demoted-exclude`
             amendment) or widen `scope.include`, else remove it. A row the
-            brief does not explain keeps the wording above. Scalar and
-            stack branches: a
+            brief does not explain keeps the wording above. Every stale
+            name's issue (fabricated, documented extra, stale documentation
+            or scoped out) opens with the line that documents it, as
+            `file:line` (with --skill-dir), else with `the skill`, whatever
+            its Source. Scalar and stack branches: a
             `missingCount` above 0 is one Medium `missing-export` gap
             `{missingCount} of {denominator} exports not documented` at
             `{meta}`, except that a scalar count taken from the verified
@@ -194,15 +215,26 @@ cites (never read; default `metadata.json`):
             entries its counts differ by; a barrel one sends the fix to
             Create Skill, which rebuilds `exports[]` from the source.
   provenance-line
-            --input skf-verify-provenance-completeness.py verify's result.
+            --input skf-verify-provenance-completeness.py verify's result;
+            --stale.
             Each `stale[]` item, at its `{source_file}:{source_line}` with
             `export`, by `reason`: `line-not-definition` is a Low
             `provenance-line` gap `Provenance line is not the definition of
             {export_name}` when `definition_lines` holds a line, else an Info
             `provenance-unverified` gap `Provenance line not verified for
             {export_name}`, and its issue names the base of a `folded_to`
-            variant; `file-missing` is a Low `provenance-line` gap
-            `Provenance file is missing for {export_name}`;
+            variant. When the --stale result (classify-stale) marks
+            `{export_name}` `aliased` with a `file:line` `defined_at`, that
+            Info gap's issue and remediation name the alias at `defined_at`,
+            and the remediation asks first to record the rename if no other
+            entry already has its `export_name` (`export_name` the item's
+            `renames`, else "a name a cited file declares", `reexported_as`
+            the export), else to cite the alias, moving the citations either
+            way; when `renames` is `default`, which the map keys on
+            `export_name` and so holds once, it asks only to cite the alias.
+            A --stale result that is not a list is INVALID_INPUT.
+            `file-missing` is a Low `provenance-line`
+            gap `Provenance file is missing for {export_name}`;
             `line-out-of-bounds` a Low `provenance-line` gap `Provenance line
             is out of range for {export_name}`; `line-invalid` an Info
             `provenance-unverified` gap `Provenance line not verified for
@@ -747,7 +779,7 @@ ADAPTER_OPTIONS: dict[str, frozenset[str]] = {
     "guards": frozenset({"metadata"}),
     "numerator": frozenset({"metadata"}),
     "metadata-coherence": frozenset({"metadata"}),
-    "provenance-line": frozenset(),
+    "provenance-line": frozenset({"stale"}),
     "coherence": frozenset(),
     "structure": frozenset({"served"}),
 }
@@ -776,8 +808,10 @@ _SIBLINGS: dict[str, object] = {}
 
 def _sibling(filename: str):
     """A script beside this one, loaded once: validate-inventory.py (the
-    documented-name match the stale-documentation Source uses, and the
-    skill-citation scan the homonym pick reads)."""
+    skill-citation scan the homonym pick reads), load-coverage-inputs.py
+    (the documented inventory's floor, and its fence and table readers)
+    and locate-export-segments.py (the skill's files and line model), the
+    last two for the line that documents a stale name."""
     module = _SIBLINGS.get(filename)
     if module is None:
         path = Path(__file__).resolve().parent / filename
@@ -872,21 +906,90 @@ def _provenance_sources(provenance: dict | None) -> dict[str, str]:
     return sources
 
 
+def _documenting_lines(skill_dir: Path) -> dict[str, str]:
+    """name -> the `file:line` that documents it as an export, the first tier
+    that holds the name winning:
+
+      1. its first origin in the documented inventory's floor
+         (load-coverage-inputs.py `floor`: SKILL.md and the top-level
+         references/*.md);
+      2. a column-0 public declaration of it in a fenced code block (floor's
+         `_declared_names`), cited or not, outside an HTML comment and a data
+         block;
+      3. a heading, or the first cell of a table whose header's first cell is
+         one of floor's `FLOOR_TABLE_HEADERS`, whose stripped text is the name
+         or holds a code span floor's `_floor_name` reads as the name;
+      4. a line whose inline code span, stripped, is the name, or the name
+         directly followed by `(`.
+
+    Tiers 2 to 4 read SKILL.md, then every .md file under references/,
+    subfolders included, in path order (locate-export-segments.py
+    `skill_files`), never the frontmatter, tiers 3 and 4 outside fenced code
+    and HTML comments; within a tier the first file, then its lowest line,
+    wins. A bare word, or a span that holds the name among other words
+    (`uitripled add`), documents nothing. An input a tier cannot read is
+    skipped: floor's InputError (no SKILL.md, a file that is not UTF-8)
+    leaves tier 1 empty, an unreadable file tiers 2 to 4."""
+    coverage = _sibling("load-coverage-inputs.py")
+    segments = _sibling("locate-export-segments.py")
+    tiers: list[dict[str, str]] = [{}, {}, {}, {}]
+    try:
+        for entry in coverage.floor(str(skill_dir))["names"]:
+            origin = entry["origins"][0]
+            tiers[0].setdefault(entry["name"], f"{origin['file']}:{origin['line']}")
+    except coverage.InputError:
+        pass
+    try:
+        files = segments.skill_files(skill_dir)
+    except OSError:
+        files = []
+    # floor's fence filter: a fence in an HTML comment or a data block declares nothing, and a Svelte block's
+    # `export let` is a component prop. Unlike floor, an unheaded fence counts.
+    js_family = segments.JS_FAMILY - {"svelte"}
+    for rel, lines in files:
+        start = segments._frontmatter_end(lines)
+        blocks, code = segments._fenced_blocks(lines, start)
+        comments = coverage._html_comment_lines(lines, start, code)
+        for opening, closing, info in blocks:
+            language = segments._language(info)
+            if opening in comments or language in segments.DATA_LANGUAGES:
+                continue
+            masked = segments.mask_code("\n".join(lines[opening + 1:closing]), language).split("\n")
+            for offset, declared in coverage._declared_names(masked, language, js_family):
+                tiers[1].setdefault(declared, f"{rel}:{opening + offset + 2}")
+        headings, prose = segments._prose(lines, start, code)
+        shaped = [(index, text) for index, _level, text, _above in headings]
+        written = list(shaped)
+        for block in prose:
+            written += [(i, lines[i]) for i in range(block["start"], block["end"] + 1)]
+            if block["kind"] == "table-row" and block["header"] is not None:
+                if coverage._header_word(coverage._cells(block["header"])[0]) in coverage.FLOOR_TABLE_HEADERS:
+                    shaped.append((block["start"], coverage._cells(lines[block["start"]])[0]))
+        for index, text in sorted(shaped):
+            for key in [text.strip()] + [coverage._floor_name(span) for span in segments._inline_code(text)]:
+                if key:
+                    tiers[2].setdefault(key, f"{rel}:{index + 1}")
+        for index, text in sorted(written):
+            for span in map(str.strip, segments._inline_code(text)):
+                for key in (span, span.split("(", 1)[0] if "(" in span else None):
+                    if key:
+                        tiers[3].setdefault(key, f"{rel}:{index + 1}")
+    found: dict[str, str] = {}
+    for tier in tiers:
+        for key, line in tier.items():
+            found.setdefault(key, line)
+    return found
+
+
 def _documenting_line(skill_dir: Path, name: str) -> str | None:
-    """The first line of SKILL.md, then of references/*.md in path order,
-    that writes `name` (validate-inventory.py's match), as `file:line`."""
-    pattern = _sibling("validate-inventory.py").name_pattern(name)
-    refs = skill_dir / "references"
-    files = [skill_dir / "SKILL.md"] + (sorted(refs.glob("*.md")) if refs.is_dir() else [])
-    for path in files:
-        try:
-            text = path.read_bytes().decode("utf-8-sig", errors="replace")
-        except OSError:
-            continue
-        for number, line in enumerate(text.split("\n"), start=1):
-            if pattern.search(line):
-                return f"{path.relative_to(skill_dir).as_posix()}:{number}"
-    return None
+    """The `file:line` that documents `name` as an export in the skill at
+    `skill_dir` (`_documenting_lines`), else None."""
+    return _documenting_lines(skill_dir).get(name)
+
+
+def _documents(doc: str | None, name: str) -> str:
+    """The subject of a stale name's Issue: the line that documents it, else the skill."""
+    return f"{f'`{doc}`' if doc else 'the skill'} documents `{name}`"
 
 
 def _scoped_out_by(row: dict) -> bool:
@@ -1069,8 +1172,8 @@ def _scoped_out_gap(name: str, row: dict, doc: str | None, brief: str) -> dict:
         f"Decide whether `{name}` belongs on the surface: `{brief}` scopes out `{at}`, where it is defined, since "
         f"{' and '.join(causes)}. To keep its documentation, {' and '.join(fixes)}; else remove the documentation "
         f"of `{name}` at {doc or 'SKILL.md'}.",
-        issue=f"{f'`{doc}`' if doc else 'SKILL.md'} documents `{name}`, which {who} exports and `{at}` defines, a "
-              f"file `{brief}` scopes out (`excluded.outsideScope`)",
+        issue=f"{_documents(doc, name)}, which {who} exports and `{at}` defines, a file `{brief}` scopes out "
+              "(`excluded.outsideScope`)",
         export=name)
 
 
@@ -1113,9 +1216,13 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
         if not isinstance(stale, list):
             raise AdapterError("--stale is not classify-stale JSON (a list)")
         classified = {i["name"]: i for i in stale if isinstance(i, dict) and isinstance(i.get("name"), str)}
-    for name in _names(cov, "stale", "--input"):
+    names = _names(cov, "stale", "--input")
+    # the lines that document each name, read once for every stale name
+    documenting = _documenting_lines(Path(skill_dir)) if skill_dir and names else {}
+    for name in names:
         item = classified.get(name) or {}
         cited = item.get("source")
+        doc = documenting.get(name)
         if item.get("fabricated") is True:
             if not isinstance(cited, str) or not cited:
                 # a Critical gap needs the line it cites: never downgrade it
@@ -1124,14 +1231,13 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
                 "Critical", "fabricated-signature", f"Fabricated signature: {name}", cited,
                 f"Remove `{name}` from SKILL.md and references/, or correct it to the export the source "
                 f"defines: no file its provenance cites defines it (`{cited}`).",
-                issue=f"SKILL.md documents `{name}`, which the source API surface lacks and the cited "
-                      "file does not define",
+                issue=f"{_documents(doc, name)}, which the source API surface lacks and the cited file does "
+                      "not define",
                 export=name))
             continue
         if not outside_read:
             outside, outside_read = _outside_scope(surface), True
         extra = _documented_extra_at(name, item, outside, skill_dir)
-        doc = _documenting_line(Path(skill_dir), name) if skill_dir else None
         if extra:
             declared, among = extra
             # a homonym: the one declaring file the skill's own citations name
@@ -1146,8 +1252,8 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
                 "Info", "observation", f"Documented extra: {name}", declared,
                 f"No change: `{name}` is a documented extra, a name the source still declares at "
                 f"`{declared}` outside the enumerated surface, and its documentation stays. {checked}",
-                issue=f"{f'`{doc}`' if doc else 'the skill'} documents `{name}`, which the enumerated source API "
-                      f"surface lacks and the source still declares{picked}",
+                issue=f"{_documents(doc, name)}, which the enumerated source API surface lacks and the source "
+                      f"still declares{picked}",
                 export=name))
             continue
         if outside is not None and name in outside and _scoped_out_by(outside[name]):
@@ -1158,7 +1264,7 @@ def _stale_gaps(cov: dict, surface: dict | None, stale: object, scored: set[str]
             "Medium", "stale-documentation", f"Stale documentation: {name}", doc or "SKILL.md",
             f"Check `{name}` against the source and update or remove its documentation at "
             f"{doc or 'SKILL.md'}: the enumerated source surface does not export it.",
-            issue=f"SKILL.md documents `{name}`, which the enumerated source API surface lacks",
+            issue=f"{_documents(doc, name)}, which the enumerated source API surface lacks",
             export=name))
     return records
 
@@ -1448,10 +1554,48 @@ def from_metadata_coherence(result: object, metadata: str | None = None) -> list
     return records
 
 
-def from_provenance_line(result: object) -> list[dict]:
+def _aliased_items(stale: object) -> dict[str, dict]:
+    """name -> its classify-stale item (`--stale`) when it is `aliased` with a `file:line` `defined_at`: a rename
+    elsewhere declares the name, so a provenance line gap of it names the alias. Raises AdapterError, as the
+    coverage adapter does, when the result is not a list."""
+    if stale is None:
+        return {}
+    if not isinstance(stale, list):
+        raise AdapterError("--stale is not classify-stale JSON (a list)")
+    return {i["name"]: i for i in stale
+            if isinstance(i, dict) and isinstance(i.get("name"), str) and i.get("reason") == "aliased"
+            and isinstance(i.get("defined_at"), str) and i["defined_at"].rpartition(":")[0]
+            and i["defined_at"].rpartition(":")[2].isdigit()}
+
+
+def _alias_fix(name: str, file: str, item: dict) -> str:
+    """The remediation of an unverified provenance line of a name classify-stale found `aliased` (`item`): record
+    the rename if no other entry already has its `export_name`, else cite the alias. The map keys on
+    `export_name`, so it holds one `default` entry at most (a barrel of `export { default as X }` lines renames
+    several): a rename of `default` takes the alias alone. It never says which cited file declares the renamed
+    name: any checked entry's may."""
+    alias, local = item["defined_at"], item.get("renames")
+    alias_file, _, alias_line = alias.rpartition(":")
+    named = isinstance(local, str) and bool(local)
+    renamed = f"`{local}`" if named else "a name a cited file declares"
+    head = f"`{name}` is an alias: `{alias}` renames {renamed} to it, and no line of `{file}` defines `{name}`. "
+    cite = (f"the alias: set `source_file` to `{alias_file}` and `source_line` to `{alias_line}`, and move the "
+            f"citations of `{name}` there.")
+    if local == "default":
+        return f"{head}Cite {cite}"
+    guard = f"`export_name` {renamed}" if named else "that name as its `export_name`"
+    return (f"{head}If no other entry already has {guard}, record the rename in this provenance entry: set "
+            f"`export_name` to {renamed}, add `reexported_as` `{name}`, cite the line that declares {renamed} and "
+            f"move the citations of `{name}` to that line. Or cite {cite}")
+
+
+def from_provenance_line(result: object, stale: object = None) -> list[dict]:
     """verify's `stale[]` items: provenance line gaps, one per citation that does not resolve or is not the
-    definition line."""
+    definition line. `stale` (classify-stale's result, `--stale`, or None) gives the names a rename declares: an
+    unverified line of one names the alias and, unless the name it renames is `default`, how to record the rename
+    (#911)."""
     result = _object(result, "--input (skf-verify-provenance-completeness.py verify)", "stale")
+    aliased = _aliased_items(stale)
     records: list[dict] = []
     for item in _list(result, "stale", "--input"):
         if not isinstance(item, dict):
@@ -1506,12 +1650,16 @@ def from_provenance_line(result: object) -> list[dict]:
                       f"it; the lines that define it are {lines}.{folded}",
                 export=name))
         else:
-            records.append(_gap(
-                "Info", "provenance-unverified", f"Provenance line not verified for {name}", where,
+            alias = aliased[name] if isinstance(name, str) and name in aliased else None
+            fix = _alias_fix(name, file, alias) if alias else (
                 f"Open `{file}` and confirm that line {line} defines `{base or name}`; if another line does, set "
-                "the provenance `source_line` to it.",
-                issue=f"the line-check rules found no definition line for `{name}` in `{file}`; check by hand"
-                      + (f".{folded}" if folded else ""),
+                "the provenance `source_line` to it.")
+            issue = (f"no line of `{file}` defines `{name}`: the source declares it only as the alias at "
+                     f"`{alias['defined_at']}`" if alias else
+                     f"the line-check rules found no definition line for `{name}` in `{file}`; check by hand")
+            records.append(_gap(
+                "Info", "provenance-unverified", f"Provenance line not verified for {name}", where, fix,
+                issue=issue + (f".{folded}" if folded else ""),
                 export=name))
     return records
 
@@ -1680,7 +1828,8 @@ def build_records(args: argparse.Namespace) -> list[dict]:
     if kind == "metadata-coherence":
         return from_metadata_coherence(data, args.metadata)
     if kind == "provenance-line":
-        return from_provenance_line(data)
+        stale = read_result(args.stale, "--stale") if args.stale is not None else None
+        return from_provenance_line(data, stale)
     return from_coherence(data)
 
 
@@ -1897,7 +2046,8 @@ def _build_parser() -> argparse.ArgumentParser:
                                      "the names outside scope)")
     p.add_argument("--signatures", help="coverage: score-signatures.py score's result (missingTypes)")
     p.add_argument("--numerator", help="coverage: verify-declared-numerator.py's result (absent names)")
-    p.add_argument("--stale", help="coverage: classify-stale's result (fabricated signatures, documented extras)")
+    p.add_argument("--stale", help="coverage: classify-stale's result (fabricated signatures, documented extras); "
+                                   "provenance-line: the same (the names a rename declares)")
     p.add_argument("--provenance", help="coverage: the provenance map (an absent name's Source)")
     p.add_argument("--skill-dir", help="coverage: the skill package (a stale name's documenting line)")
     p.add_argument("--metadata", help="the metadata.json path a record cites as its Source (not read)")

package/src/skf-test-skill/scripts/load-coverage-inputs.py

@@ -25,9 +25,11 @@ reading files and writing one JSON object:
             signature is read only where the place writes it in a fixed
             form (Signatures, below). A name is a plain
             identifier (`[A-Za-z_$][\\w$]*`) once a leading `new ` and
-            everything from the first `(` or `<` are cut, so `Meta<T>`,
-            `fetch(url): Promise<T>` and `new Client(opts)` give `Meta`,
-            `fetch` and `Client`. A dotted or `::` name gives none, so a
+            everything from the first `(`, `<` or `[` are cut, so
+            `Meta<T>`, `App[P, R]`, `fetch(url): Promise<T>` and
+            `new Client(opts)` give `Meta`, `App`, `fetch` and `Client`;
+            an empty `[]` at the cut (a TS array type, `Foo[]`) gives
+            none. A dotted or `::` name gives none, so a
             namespace-style skill such as zod (`z.object`) gets no table
             floor. The forms, read outside the frontmatter and HTML
             comments (a table row or heading inside fenced code gives none):
@@ -614,12 +616,16 @@ def census(skill_dir: str) -> dict:
 
 
 def _floor_name(text: str) -> str | None:
-    """The plain identifier `text` writes once a leading `new ` and everything from the first `(` or `<` are
-    cut; None for any other text, a dotted or `::` name among them."""
+    """The plain identifier `text` writes once a leading `new ` and everything from the first `(`, `<` or `[` are
+    cut; None for any other text, a dotted or `::` name and an array type (`Foo[]`, an empty `[]` at the cut)
+    among them."""
     text = text.strip()
     if text.startswith("new "):
         text = text[4:]
-    text = re.split(r"[(<]", text, maxsplit=1)[0].strip()
+    cut = re.match(r"([^(<\[]*)(\[\s*\])?", text)
+    if cut.group(2):
+        return None
+    text = cut.group(1).strip()
     return text if PLAIN_IDENTIFIER_RE.fullmatch(text) else None
 
 

package/src/skf-update-skill/references/gap-driven.md

@@ -99,7 +99,7 @@ Read the gaps of the test report at `{test_report_path}` and translate them into
 
 - `stale-documentation` (the skill documents a name the source's enumerated surface lacks and that is not a documented extra, an Info `observation`): the source has no line to repair the name from, so a person removes its documentation when the name is gone from the source, fixes the brief's scope when the surface missed it, or, when the source still declares the name, keeps the documentation and re-runs Test Skill at a tier that classifies it.
 - `metadata-drift` (divergent export counts in the metadata): update-skill recounts `stats.exports_public_api`, `stats.exports_documented` and `stats.effective_denominator` each time it writes metadata.json, so a metadata patch to them does not hold (under `--allow-workspace-drift` and for a docs-only skill it keeps the recorded public API counts and `stats.effective_denominator` instead); Create Skill rebuilds diverging barrel counts from the source and recounts a `stats.effective_denominator` the brief's `scope.tier_a_include` set disagrees with (denominator drift), a person fixes denominator deflation on a brief with no tier A list by adding `scope.tier_a_include` to it, and documented-surface counts that differ by the `Type::method` entries the named-export count leaves out need no fix.
-- `provenance-unverified`: the line-check rules could not verify the line, or the recorded line is not a number, so a person checks by hand which line defines the export and, when it is not the recorded one, sets its provenance `source_line` to that line.
+- `provenance-unverified`: the line-check rules could not verify the line, or the recorded line is not a number, so a person checks by hand which line defines the export and, when it is not the recorded one, sets its provenance `source_line` to that line; when the gap names an alias, no line of the cited file defines the export, so a person records the rename in its provenance entry (`export_name` the name the alias renames, `reexported_as` the export) only when no other entry has that `export_name` and the alias does not rename a default export, and otherwise cites the alias line, as the remediation says.
 - `denominator-inflation`: it concerns the brief's scope and the count design, which a person decides in the skill brief, as the gap's remediation says.
 - `brief-scope-stale`: a person edits the brief's scope globs by hand so each matches the files it meant, since update-skill does not rewrite them.
 - `multi-denominator`: no fix is needed, since the barrel and the documented surface measure different sets by design and the report records both counts.

package/src/skf-update-skill/references/invocation-contract.md

@@ -9,4 +9,4 @@ The argument set, gate map, outputs and headless result line of `skf-update-skil
 | **Gates** | step 1: init.md §4's degraded-rebuild gate [D]/[X] when no provenance map is found (headless: halts, or takes [D] under `--allow-degraded`; a gap-driven run halts `blocked` there instead); init.md §4b's [G]/[S] test-report offer, interactive only (headless warns `unconsumed-test-report`); Confirm Gate [C] (init.md §8) | step 2, each only when triggered: detect-changes.md §1b's promote prompt and §1c's scope-expansion prompt [P]/[S]/[U] (headless: defers each candidate to a person), §2.2's deletion-ratio gate [C]/[B]/[A] (headless: [C]) | step 2g (gap-driven): gap-driven.md §1 rule R1's [D]/[R] for each gap whose remediation names removal (headless: [D], or [R] only when the export is internal or `#[doc(hidden)]`) | step 4: Confirm Gate [C] only after the user resolved [MANUAL] conflicts (merge.md §4); a clean merge auto-proceeds, and a headless run with conflicts halts `halted-for-manual-mismatch` before anything is written |
 | **Outputs** | A new version folder `{skill_group}/{new_version}/` and its forge folder, beside the unchanged previous version (a gap-driven repair writes the current version in place), and a finished run's `update-skill-result-{YYYYMMDD-HHmmss}.json` and `update-skill-result-latest.json` in that version's forge folder (a run that found no change: the current one's). `--detect-only` and `--dry-run` write none of these, nor the skill brief. Run state goes to a run folder under `{project-root}/_bmad-output/.skf-run/` that step 7 removes; a halt keeps it |
 | **Concurrency** | A second real update of the same skill halts `halted-for-concurrent-run` while the first holds its run lock (init.md §1b); `--detect-only` and `--dry-run` take no lock. write.md §8 halts with the same status when another flip of the `active` link holds its lock for 5 seconds. A remote skill is read from a private tree, and no mode writes to the shared workspace clone before write.md §9. |
-| **Headless** | No gate prompts: each resolves as the Gates row says, and the run records the decision. One `SKF_UPDATE_RESULT_JSON` line (report.md §5b), at step 6 or at a HALT, printed by the shared emitter and checked against `shared/scripts/schemas/skf-update-result-envelope.v1.json`. It is the run's last line: the shared health check displays it after everything else; a HALT displays its line and stops. Pipelines branch on `skf_update.status`: `success`, `no-changes`, `detect-only` and `dry-run` are successful exits. A caller reads the run's own `SKF_UPDATE_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `update-skill-result-latest.json` may then describe an earlier run, so it is never read in its place. |
+| **Headless** | No gate prompts: each resolves as the Gates row says, and the run records the decision. One `SKF_UPDATE_RESULT_JSON` line (report.md §5b), at step 6 or at a HALT, printed by the shared emitter and checked against `shared/scripts/schemas/skf-update-result-envelope.v1.json`. It is the run's last line: the shared health check displays it after everything else; a HALT displays its line and stops. Pipelines branch on `skf_update.status`: `success`, `no-changes`, `detect-only` and `dry-run` are successful exits. A headless run whose emitter refused its result line for good ends on a `halted-for-write-failure` line instead, with `error.phase` `report:result-contract` and an `error.reason` that starts `result-contract-not-written`, and nothing it wrote is undone. A caller reads the run's own `SKF_UPDATE_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `update-skill-result-latest.json` may then describe an earlier run, so it is never read in its place. |

package/src/skf-update-skill/references/merge.md

@@ -299,7 +299,7 @@ uv run {runLockHelper} acquire \
    ```
 
    It renames the staged folder to `{skill_group}/{new_version}/` in one step, so no reader ever sees a half-copied version.
-6. **Create the forge folder** `{forge_data_folder}/{skill_name}/{new_version}/` and copy `provenance-map.json`, `evidence-report.md` and `extraction-rules.yaml` from `{forge_version}` into it, each when it exists: step 5 updates the provenance map and appends this update to the evidence report there, and audit-skill reads the extraction rules there. Test reports, drift reports and result files belong to the version they were made for and stay where they are.
+6. **Create the forge folder** `{forge_data_folder}/{skill_name}/{new_version}/` and copy into it each of `provenance-map.json`, `evidence-report.md` and `extraction-rules.yaml`: from `{forge_version}` when it is there, else from `{forge_data_folder}/{skill_name}/` when it is there and init.md §4 bound `{provenance_map_path}` to that flat folder's map (an older skill's flat forge data, `knowledge/version-paths.md`). Copy, never move: the previous version's files and the flat ones stay as they are. Step 5 updates the provenance map and appends this update to the evidence report there; the extraction rules record how the skill was extracted. Test reports, drift reports and result files belong to the version they were made for and stay where they are.
 7. **Rebind** `{skill_package}` ← `{skill_group}/{new_version}/{skill_name}` and `{forge_version}` ← `{forge_data_folder}/{skill_name}/{new_version}`. Every later step reads and writes the new version there; `{manual_inventory}` keeps the amended path §4 bound.
 
 If no `{atomicWriteProbeOrder}` candidate resolves, or the stage, copy, write, publish or forge-folder step fails, HALT with status `halted-for-write-failure`, naming the failed step (for a missing helper: "skf-atomic-write.py is missing; re-install SKF"). The halt procedure takes `phase: "merge:new-version-folder"`, `path: "{skill_group}/{new_version}"`, `reason: "<the failed step>: <its error>"`; its rollback removes what this section created, `{version_staging}`, `{skill_group}/{new_version}/` and `{forge_data_folder}/{skill_name}/{new_version}/`, none of which existed before `begin` recorded them. The previous version is unchanged.