bmad-module-skill-forge 6.0.0 → 7.0.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "6.0.0",
+      "version": "7.0.0",
       "author": {
         "name": "Armel"
       },

package/docs/_data/pinned.yaml

@@ -32,7 +32,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "6.0.0"
+skf_version: "7.0.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/workflows.md

@@ -73,7 +73,7 @@ Each workflow is also a skill you can run directly, without Ferris: `/skf-setup`
 
 **Which brief:** Name the brief by its path or by the skill's name. With no brief path, skill name or `--batch`, CS loads the only brief in `forge_data_folder` and names it in its opening banner. When the folder holds several, an interactive run asks which one to compile, and a headless run stops with exit `2` (`brief-missing`), naming them.
 
-**Batch mode:** The paths after `--batch` name `skill-brief.yaml` files or folders of briefs; with no path, CS takes the briefs in `forge_data_folder`. Every brief is validated before the first one compiles, and the plan lists the briefs to compile and each refused brief: one that fails the brief schema, with the validator's first message, or one whose `name` an earlier brief of the batch already has. A HARD HALT ends only its own brief. The batch writes `create-skill-batch-<timestamp>.json` and `create-skill-batch-latest.json` under `<skills_output_folder>/_batch/` and exits with the highest exit code among its briefs, `0` when every brief finished. Run again with the same briefs, a batch that an ended session left goes on where it stopped.
+**Batch mode:** The paths after `--batch` name `skill-brief.yaml` files or folders of briefs; with no path, CS takes the briefs in `forge_data_folder`. Every brief is validated before the first one compiles, and the plan lists the briefs to compile and each refused brief: one that fails the brief schema, with the validator's first message, or one whose `name` an earlier brief of the batch already has. A HARD HALT ends only its own brief. The batch writes `create-skill-batch-<timestamp>.json` and `create-skill-batch-latest.json` under `<skills_output_folder>/_batch/` and exits with the highest exit code among its briefs, `0` when every brief finished. Its result is the file its `batch_summary` event's `summary_path` names: the `-latest.json` copy holds the last batch summary written, which may be another batch's. Run again with the same briefs, a batch that an ended session left goes on where it stopped.
 
 **Safety:** Writes a version only into a skill folder SKF generated, or a new one. When `skills_output_folder` already holds a folder with the skill's name that SKF did not generate, or a version folder SKF did not generate, it stops before writing anything (`not-skf-output`); an SKF skill still in the old flat layout stops with `flat-layout` until `@Ferris TS` moves it. Set a different `name` in the brief to create the skill beside a folder SKF did not generate.
 
@@ -549,7 +549,7 @@ Setup is not the only workflow whose result line is the run's final message: a h
 
 4. **Success result contract.** A finished run prints one `SKF_QUICK_SKILL_RESULT_JSON: {…}` line on `stdout`. Its `summary` carries `quality_score` (the skill-check score of the written package, not a Test Skill score), `validation_issues`, `repo_shape`, `language_resolution` and `active_pointer`, beside the top-level `headless_decisions` and `warnings`, such as `also_found_in` when a headless run kept the first registry's pick of a package name another registry also holds. The run also writes `quick-skill-result-latest.json` in the skill package.
 
-**Batch mode (`--batch <file>`).** Drives N targets in sequence: each target runs steps 1 to 6, and the health check runs once, after the batch summary. Input format: one target per line, `#` comments and blank lines ignored, optional per-line modifiers `language=<lang>` and `scope=<path>`. Each target's output lands in its own `{skill_package}/`; an aggregated summary writes to `{skills_output_folder}/_batch/quick-skill-batch-{ts}.json` (with `quick-skill-batch-latest.json` copy). Per-target boundary events (`{"batch":N,"target":"…","status":"start|done|fail",…}`) and a final `{"batch_summary":true,…}` event extend the per-step event stream above. The batch exits with the highest exit code among its failed targets (`0` when none failed); `--fail-fast` stops it at the first failed target and exits with that target's code. A batch refused before its first target writes no summary and exits `2`, or `4` when its run folder cannot be written. Full input grammar, summary schema, and exit-code rules in [`src/skf-quick-skill/references/batch-mode.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/references/batch-mode.md).
+**Batch mode (`--batch <file>`).** Drives N targets in sequence: each target runs steps 1 to 6, and the health check runs once, after the batch summary. Input format: one target per line, `#` comments and blank lines ignored, optional per-line modifiers `language=<lang>` and `scope=<path>`. Each target's output lands in its own `{skill_package}/`; an aggregated summary writes to `{skills_output_folder}/_batch/quick-skill-batch-{ts}.json` (with `quick-skill-batch-latest.json` copy). Per-target boundary events (`{"batch":N,"target":"…","status":"start|done|fail",…}`) and a final `{"batch_summary":true,…}` event extend the per-step event stream above. The batch's result is the file that event's `summary_path` names: the `-latest` copy holds the last batch summary written, which may be another batch's. The batch exits with the highest exit code among its failed targets (`0` when none failed); `--fail-fast` stops it at the first failed target and exits with that target's code. A batch refused before its first target writes no summary and exits `2`, or `4` when its run folder cannot be written. Full input grammar, summary schema, and exit-code rules in [`src/skf-quick-skill/references/batch-mode.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/references/batch-mode.md).
 
 **Exception: `/skf-brief-skill` headless emits a final result envelope and supports presets.** Headless `/skf-brief-skill` is a first-class building block for scripted brief generation (for example, seeding briefs for N SaaS SDKs that share scope and authority defaults). Three operational contracts go beyond per-gate auto-proceed:
 
@@ -576,7 +576,7 @@ Setup is not the only workflow whose result line is the run's final message: a h
 - **`/skf-rename-skill` (RS)**: exit `2` `input-missing`/`input-invalid`, `3` resolution-failure (`manifest-corrupt`, `nothing-to-rename`), `4` write-failure (`copy-failed`, `write-failed`, `manifest-write-failed`; the context-file rebuild is best-effort and never halts), `5` state-conflict (`name-collision`, `source-authority-blocked`, `halted-for-concurrent-run` while another rename of the same skill holds its run lock or when this run's own lock went stale while it waited at a prompt, `not-skf-output` for a folder SKF did not generate, or a forge folder that also holds other files or that is a link, is not a folder, or cannot be listed; `flat-layout` for a skill not yet migrated; `verify-failed` when the old name is still in the renamed files, which rolls the rename back with the old skill intact, see [Troubleshooting](/docs/troubleshooting.md)). The run lock is `.skf-rename-<name>.lock` in `forge_data_folder`, and it goes stale 60 minutes after it was taken or renewed: when no other rename of that skill is running, delete the lock file the message names, or wait until the time it gives, then run the rename again. When this run's own lock went stale at a prompt, nothing was changed: run the rename again. Exit codes in [`src/skf-rename-skill/references/exit-codes.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-rename-skill/references/exit-codes.md); the envelope in [`src/skf-rename-skill/references/invocation-contract.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-rename-skill/references/invocation-contract.md) § "Result Contract (Headless)".
 - **`/skf-refine-architecture` (RA)**: exit `2` `input-missing`/`input-invalid` (`input-invalid` also covers a Verify Stack report with a `schemaVersion` other than `1.0`, a missing or doubled verdict table, or an unknown verdict token), `3` resolution-failure (`output-folder-unconfigured`, `forge-folder-unconfigured`, and `resolution-failure` when the result emitter or `scripts/skf-check-preservation.py` cannot start, when the refinement rules cannot be read, lack one of their six tables or break a tier rule (phase `init:rules`), or when the skill inventory helper (phase `init:inventory`) or the co-mention helper (phase `gap-analysis:comention`) is missing or its call fails, or the Verify Stack report validator (phase `init:feasibility-validator`) is missing), `4` write-failure (`write-failed`, and `preservation-failed` when the draft would lose or change a line of the original: at once in a headless run, or when the promotion still finds it after one rebuild), `5` state-conflict (`insufficient-skills`: no skill SKF generated was found), `7` `inventory-unreliable`, `8` `recovery-failed` (at step 3, the Verify Stack report cannot be read again, Verify Stack rewrote it during the run, or the refinement rules no longer pass step 1's check; the saved state is not enough to rebuild the findings; or a record of the draft's build or promotion is missing at step 6). Exit codes and the envelope in [`src/skf-refine-architecture/references/exit-codes.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-refine-architecture/references/exit-codes.md).
 
-**Reading the result lines.** Read the run's own line: a run that printed none has no result to read, whatever the process exit code (`claude -p` exits `0` when the agent ends its turn early): it was cut off, or could not write its result. Treat it as a failure, and never read a `-latest.json` result file in its place, since that file may then describe an earlier run. A cut-off run can also leave its run lock until the lock goes stale, 60 minutes after it was taken or renewed: Test Skill's `.test-skill.lock`, Update Skill's `.skf-update.lock` or Rename Skill's `.skf-rename-<name>.lock` ([Troubleshooting](/docs/troubleshooting.md#test-skill-stops-with-another-run-active)). Check each line's `status` field first (for US, `skf_update.status`). For most workflows it only says whether the run finished or stopped on an error, so read the outcome from the fields below: a TS run whose skill scores below its threshold still reports `status: "success"`, with `verdict: "FAIL"`. AN, CS, SS, AS, TS, EX and VS also give each outcome a stable exit code, which the line carries as `exit_code` (a CS halt has `2` to `6`).
+**Reading the result lines.** Read the run's own line: a run that printed none has no result to read, whatever the process exit code (`claude -p` exits `0` when the agent ends its turn early): it was cut off, or could not write its result. Treat it as a failure, and never read a `-latest.json` result file in its place, since that file may then describe an earlier run. A Quick Skill or Create Skill `--batch` run is read from its `batch_summary` event and the summary file that event's `summary_path` names (the event plus the batch run folder's `batch.jsonl` when `summary_path` is null), never from `quick-skill-batch-latest.json` or `create-skill-batch-latest.json`: each holds the last batch summary written, which may be another batch's. The event comes before the health check, so a caller reads it from the session's output stream (`claude -p --output-format stream-json`) or transcript, not from the final message. A printed `batch_summary` event stays the batch's result even if a halt line follows it. A batch that printed no `batch_summary` event has no batch result, whatever the process exit code: a halt line of its own (phase `batch-mode`, or `on-activation` for Quick Skill) says why it stopped, and with no halt line it was cut off or could not print its halt line. Each target it printed a `done` or `fail` event for ended as that event says, and a target with only a `start` event has no result. After a cut-off batch, run it again: a Quick Skill batch starts over from the first target, and a Create Skill batch run with the same briefs goes on with the brief it was working on. A cut-off run can also leave its run lock until the lock goes stale, 60 minutes after it was taken or renewed: Test Skill's `.test-skill.lock`, Update Skill's `.skf-update.lock` or Rename Skill's `.skf-rename-<name>.lock` ([Troubleshooting](/docs/troubleshooting.md#test-skill-stops-with-another-run-active)). Check each line's `status` field first (for US, `skf_update.status`). For most workflows it only says whether the run finished or stopped on an error, so read the outcome from the fields below: a TS run whose skill scores below its threshold still reports `status: "success"`, with `verdict: "FAIL"`. AN, CS, SS, AS, TS, EX and VS also give each outcome a stable exit code, which the line carries as `exit_code` (a CS halt has `2` to `6`).
 
 | Workflow | Result line | Fields worth reading |
 | --- | --- | --- |
@@ -605,7 +605,7 @@ Settings every workflow has:
 
 - `persistent_facts`: rules the workflow keeps in mind for the whole run. Every workflow except Setup Forge loads any `project-context.md` in your project by default. In a team or personal override, an entry that starts with `!` drops each earlier entry it names and loads nothing itself. To turn that default off for one workflow, add `persistent_facts = ["!file:{project-root}/**/project-context.md"]` under `[workflow]` in `_bmad/custom/<skill-name>.toml`. Every workflow that loads the default honours such an entry, and Campaign's kickoff loader drops the default from each skill's kickoff the same way.
 - `activation_steps_prepend` and `activation_steps_append`: extra steps to run before or after start-up.
-- `on_complete`: a command to run after the workflow writes its result file, such as a notifier. Every workflow except Campaign, Stack Skill, Verify Stack and Setup Forge (Quick Skill included) calls it with `--result-path=<result file>` (for Brief Skill, the `skill-brief.yaml` it wrote), and the hook is skipped when the emitter wrote no result file. Quick Skill's hook gets `--result-path=<skill package>/quick-skill-result-latest.json`, where the skill package is that file's folder, and is skipped when the emitter wrote no result file, or did not write that `-latest` copy. Campaign passes `--report-path=<report>` when it wrote its report, Stack Skill runs the command with no argument, and Setup Forge and Verify Stack carry it out as an instruction once they finish. A failing command never fails the workflow.
+- `on_complete`: a command to run after the workflow writes its result file, such as a notifier. Every workflow except Campaign, Stack Skill, Verify Stack and Setup Forge (Quick Skill included) calls it with `--result-path=<result file>` (for Brief Skill, the `skill-brief.yaml` it wrote), and the hook is skipped when the emitter wrote no result file. Quick Skill's hook gets `--result-path=<skill package>/quick-skill-result-latest.json`, where the skill package is that file's folder, and is skipped when the emitter wrote no result file, or did not write that `-latest` copy. Analyze Source, Create Skill and Update Skill pass their `-latest` copy too (`<forge_data_folder>/analyze-source-result-latest.json`, `<version folder>/create-skill-result-latest.json` and `<version folder>/update-skill-result-latest.json`), and skip the hook, with a line that says so, when the run did not write it. Campaign passes `--report-path=<report>` when it wrote its report, Stack Skill runs the command with no argument, and Setup Forge and Verify Stack carry it out as an instruction once they finish. A failing command never fails the workflow.
 
 Useful settings in specific workflows:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "6.0.0",
+  "version": "7.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",

package/src/shared/references/output-contract-schema.md

@@ -38,7 +38,7 @@ Each run writes **two files** to `{output_dir}`:
 
 Write the per-run record first, then copy it to the `-latest.json` path. If the copy fails, the per-run record still exists — the run is not lost.
 
-**Consumers (forger, CI, chained workflows):** a caller that started a run reads that run's own `SKF_<NAME>_RESULT_JSON` envelope 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 `{skill-name}-result-latest.json` may then describe an earlier run, so it is never read in its place. A tool that looks up the last run of a skill rather than one it started (skf-find-test-report.py, forge-status.py) may read the copy. Do not enumerate timestamped files unless inspecting prior-run history.
+**Consumers (forger, CI, chained workflows):** a caller that started a run reads that run's own `SKF_<NAME>_RESULT_JSON` envelope 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 `{skill-name}-result-latest.json` may then describe an earlier run, so it is never read in its place. A tool that looks up the last run of a skill rather than one it started (skf-find-test-report.py, forge-status.py) may read the copy. Do not enumerate timestamped files unless inspecting prior-run history. Under `--batch` (skf-quick-skill, skf-create-skill), a batch's result is its `batch_summary` event and the summary file its `summary_path` names, never the `quick-skill-batch-latest.json` or `create-skill-batch-latest.json` copy: that copy holds the last batch summary written, which may be another batch's, and a batch that printed no `batch_summary` event has no batch result (each workflow's `references/batch-mode.md`).
 
 ## Writing the Files
 

package/src/shared/scripts/skf-quick-batch.py

@@ -124,6 +124,15 @@ summarize
   "succeeded", "failed", "status", "fail_fast_triggered", "exit_code",
   "summary_path"}, with "warnings" when a summary file could not be
   written. A batch already summarized prints its event again.
+  The batch's result is that event and the file its summary_path names
+  (with summary_path null, when the per-batch file could not be written,
+  the event and batch.jsonl; a summary_write_failed warning beside a set
+  summary_path means only the copy failed): <stem>-latest.json holds the
+  last batch summary written, which may be another batch's, so it never
+  stands for this batch, and a batch cut off before summarize leaves it in
+  place. A summarize on a run folder that is gone (a batch whose targets
+  all succeeded, summarized and removed) exits 1, naming the per-batch
+  file whose input_file (or input_briefs) is this batch's.
 
 The batch file is one JSON object per line, so a write cut short spoils at
 most its own line, which is skipped when read: the next write ends that
@@ -628,10 +637,14 @@ def summary_event(summary: dict) -> dict:
 
 def cmd_summarize(run_dir: Path, output_dir: Path) -> dict:
     if not (run_dir / BATCH_FILE).exists() and not run_dir.exists():
-        stem = SUMMARY_STEMS[CREATE_WORKFLOW if run_dir.name.startswith(f"{CREATE_WORKFLOW}-") else WORKFLOW]
+        create = run_dir.name.startswith(f"{CREATE_WORKFLOW}-")
+        stem = SUMMARY_STEMS[CREATE_WORKFLOW if create else WORKFLOW]
+        names = "input_briefs name its briefs" if create else "input_file names its batch file"
         raise BatchError(f"no batch in {run_dir.as_posix()}: a batch whose targets all succeeded removes its "
-                         f"run folder once summarized; its summary is "
-                         f"{(output_dir / f'{stem}-latest.json').as_posix()}")
+                         f"run folder once summarized; its summary is the {stem}-<YYYYMMDD-HHmmss>.json in "
+                         f"{output_dir.as_posix()} whose {names}, and "
+                         f"{(output_dir / f'{stem}-latest.json').as_posix()} holds the last batch summary "
+                         f"written, which may be another batch's")
     state = load(run_dir)
     name = workflow(state)
     if state["summary"] is not None:

package/src/shared/scripts/skf-verify-provenance-completeness.py

@@ -455,7 +455,8 @@ Subcommands:
          "source": "<source_file>:<source_line>" | "<source_file>" | null,
          "defined_at": "<path>:<line>" | null,
          "declared_in": ["<path>:<line>", ...] | null,
-         "reason": "not-defined" | "defined" | "unchecked" | "no-entry",
+         "reason": "not-defined" | "aliased" | "defined" | "unchecked"
+                   | "no-entry",
          "entries": [{"source_file": "<as recorded>",
                       "source_line": <as recorded>,
                       "line_check": "checked" | "file-missing"
@@ -469,9 +470,30 @@ Subcommands:
     `fabricated` is true, with reason `not-defined`, when the name has an
     entry and every entry's `line_check` is `file-missing`, or `checked`
     with an empty `definition_lines`: the export is in neither the surface
-    nor the cited file. Otherwise the reason is `defined` (a cited file
-    defines the name), `unchecked` (no rule could check a cited file, and
-    none defines it) or `no-entry` (the map has no entry for the name).
+    nor the cited file, and no item of an export list or of a Python
+    `from X import` clause elsewhere renames to it a name that file
+    declares. Such an alias (`export { API_Entry as Entry }` or
+    `export type { ... }`, on one line or an item of a multi-line list;
+    `from X import L as NAME`, on one line or an item in parentheses or
+    after a backslash) gives the reason `aliased` and `fabricated` false:
+    the first of the name's declarations the lookup below finds (its
+    `declared_in`, else the cited file's) that is such an item
+    `L as NAME`, where a file of a `checked` entry of the name declares
+    `L` by the same rule (no module or package so named counting), is its
+    `defined_at`. A TS/JS line is read with its comments removed and its
+    one-line strings blanked, a Python line with its `#` comment cut.
+    Neither the rename's `from` module nor `L`'s own binding is resolved,
+    so an `L` that another file declares under the same name counts too.
+    Any other rename stays fabricated: `export { default as NAME }`,
+    `const NAME = L`, `type NAME = L`, an import then an export of NAME,
+    Python `NAME = L`, a TS type assertion (`x as NAME`) and `as NAME` in
+    a comment or a string; and so does a name whose cited file is the
+    module so named and itself the export (a column-0 `export default` or
+    `module.exports =`), which settles it at its line 1, so no walk looks
+    for an alias elsewhere.
+    Otherwise the reason is `defined` (a cited file defines the name),
+    `unchecked` (no rule could check a cited file, and none defines it) or
+    `no-entry` (the map has no entry for the name).
     An entry with no `source_file` (update-skill writes one for an
     `unknown` NEW_EXPORT) cites no file to check: its `line_check` is
     `no-file`, which, like a skipped or unreadable check, neither proves
@@ -483,7 +505,8 @@ Subcommands:
     `defined_at` is where the source declares a name that is not
     fabricated, so test-skill can tell a documented extra (a name outside
     the surface that the source still declares) from stale documentation;
-    a fabricated name is not looked up (null). A declaration is a line at
+    a fabricated name has none and no `declared_in` (both null), the
+    lookup reading it only for an alias. A declaration is a line at
     column 0 that the definition-line rules match with imports left out:
     a `def`, `class`, assignment, annotation, type alias, TS/JS
     declaration, `exports.NAME =`, or an alias that renames
@@ -498,9 +521,12 @@ Subcommands:
     `const NAME = require(...)`, `const { NAME } = require(...)`,
     `exports.NAME = require(...)`, `{ NAME: require(...) }`), an
     indented line and any line of a Python
-    file that does not tokenize never count. A module or package named
-    NAME (`NAME.py`, `NAME/__init__.py`, a TS/JS `NAME.<ext>` or
-    `NAME/index.<ext>`) declares NAME too: at its line 1 when no line of it
+    file that does not tokenize never count (an item of a multi-line list
+    counts at its own line, the list's opening line at column 0, so an
+    `aliased` name's `defined_at` is its rename's line). A module or
+    package named NAME (`NAME.py`, `NAME/__init__.py`, a TS/JS
+    `NAME.<ext>` or `NAME/index.<ext>`) declares NAME too: at its line 1
+    when no line of it
     declares NAME, unless `--inventory` gives NAME a `function`, `hook`,
     `class`, `interface`, `enum` or `type` kind (any of its kinds, when it
     gives several; a `method` kind is not read), no entry of NAME is a
@@ -524,10 +550,12 @@ Subcommands:
     and `defined_at` is the one item when the list has exactly one and no
     walked Python file that does not tokenize holds the name (a homonym,
     two files or more, gives null: test-skill decides it by the files the
-    skill cites). The walk reads, sorted by path, every file below the
-    walk root: the deepest folder that the files of the map's entries
-    share, widened to its package root (Python: the nearest folder at or
-    above it that holds `__init__.py`, then up while the parent holds
+    skill cites), save for an `aliased` name, whose `defined_at` is its
+    alias whatever the list holds. The walk reads, sorted by path, every
+    file below the walk root: the deepest folder that the files of the
+    map's entries share, widened to its package root (Python: the nearest
+    folder at or above it that holds `__init__.py`, then up while the
+    parent holds
     one, never the source root itself; TS/JS: the nearest folder at or
     above it that holds `package.json`), leaving out the entries whose
     file lies outside every package; the source root when none lies in
@@ -551,9 +579,12 @@ Subcommands:
     skips, those walk-only ones aside. The path is relative to the source
     root. A dotted name, or a map whose entries cite files
     but no Python or TS/JS one, is not looked up (`defined_at` and
-    `declared_in` null, as for a fabricated name), and a filesystem error
-    during the lookup gives every name null in both (the exit code stays
-    0).
+    `declared_in` null, as for a fabricated name). A filesystem error
+    during the lookup of the names that are not fabricated gives each of
+    them null in both (the exit code stays 0). The `not-defined` names are
+    looked up apart, after the others and whether or not that lookup
+    failed: an error in their walk or their alias check keeps only them
+    fabricated, and clears no other name's answer.
 
   kind-at --file <path> --line <n> --recipes <recipes>
           [--language <lang>] [--name <export_name>]
@@ -2360,6 +2391,8 @@ STALE_NOT_DEFINED = "not-defined"
 STALE_DEFINED = "defined"
 STALE_UNCHECKED = "unchecked"
 STALE_NO_ENTRY = "no-entry"
+# a not-defined name a declaration renames to it from a name a cited file declares
+STALE_ALIASED = "aliased"
 
 
 def stale_names(data: object) -> list[str]:
@@ -2745,6 +2778,68 @@ def baseline_gaps(
     return gaps, unchecked
 
 
+# A one-line TS/JS string literal, blanked before an export list is read.
+_JS_STRING_RE = re.compile(r"'(?:[^'\\]|\\.)*'|\"(?:[^\"\\]|\\.)*\"|`(?:[^`\\]|\\.)*`")
+_JS_IDENT_RE = re.compile(r"[A-Za-z_$][\w$]*")
+
+
+def _renamed_locals(lines: list[str], index: int, name: str, family: str) -> list[str]:
+    """The names line `index` (from 0) of a file renames to `name` as an item
+    of an export list (`export { L as NAME }` or `export type { ... }`, on
+    one line or an item of a multi-line list) or of a Python
+    `from X import` clause (on one line, or an item of one in parentheses
+    or continued with a backslash): each `L` an identifier other than
+    `name`, and in TS/JS other than `default` (`export { default as NAME }`
+    renames the default export, no declared name). A TS/JS line is read
+    with its `//` and `/* */` comments removed and each one-line string
+    blanked, a Python line with its `#` comment cut (a `from X import`
+    clause holds no string). The list opens at the nearest column-0
+    `export {` (`from X import`) at or above the line, and must not close
+    above it. Empty for any other line: `as NAME` in a comment or a string,
+    a TS type assertion (`const NAME = x as NAME`), `import { L as NAME }`
+    and Python's `import M as NAME` rename nothing here. Neither the `from`
+    module nor the binding of `L` is resolved: the caller takes `L` as
+    the name a cited file declares."""
+    if not 0 <= index < len(lines) or not re.search(
+        rf"(?<![\w$])as\s+{re.escape(name)}(?![\w$])", lines[index]
+    ):
+        return []
+    python = family == "python"
+    if python:
+        code = [line.split("#", 1)[0] for line in lines[: index + 1]]
+        opener, close, item_re = _PY_FROM_IMPORT_RE, ")", _PY_IMPORT_ITEM_RE
+    else:
+        code = [_JS_STRING_RE.sub('""', line) for line in _js_code_lines(lines[: index + 1])]
+        opener, close, item_re = _JS_EXPORT_LIST_RE, "}", _JS_EXPORT_ITEM_RE
+    for start in range(index, -1, -1):
+        opened = opener.match(code[start]) if _is_column_0(code[start]) else None
+        if opened is not None:
+            break
+        if start < index and close in code[start]:
+            return []  # a list that closes above the line holds it not
+    else:
+        return []
+    head = opened.group(1)
+    if start < index:
+        # an item of a list the opening line leaves open: in parentheses, or
+        # a Python clause each of whose lines above ends with a backslash
+        continued = all(line.rstrip().endswith("\\") for line in code[start:index])
+        if close in head or (python and not head.lstrip().startswith("(") and not continued):
+            return []
+        head = code[index]
+    locals_: list[str] = []
+    for item in head.split(close, 1)[0].replace("(", " ").replace("\\", " ").split(","):
+        found = item_re.match(item.strip())
+        if found is None or found.group(2) != name:
+            continue
+        local = found.group(1)
+        if local == name or (not python and local == "default"):
+            continue
+        if (_PY_IDENT_RE if python else _JS_IDENT_RE).fullmatch(local):
+            locals_.append(local)
+    return locals_
+
+
 class _DeclarationLookup:
     """Where the source declares the stale names (classify-stale's
     `defined_at`): a column-0 declaration, an alias that renames included, a
@@ -2766,7 +2861,10 @@ class _DeclarationLookup:
     on its path and the same skips but the walk-only ones, judged below the
     walk root when it lies there. The walk runs once for all the names no
     cited file settles: each file is read once, and only a file whose text
-    holds a name goes through the rules. Any error of the filesystem raises
+    holds a name goes through the rules. `renamed` then tells which of a
+    name's declarations is an alias of a name a cited file declares (an
+    item of an export list or of a Python `from X import` clause), from
+    the lines the lookup read. Any error of the filesystem raises
     (`_LOOKUP_ERRORS`)."""
 
     def __init__(self, entries: list[dict], source_root: Path) -> None:
@@ -2786,6 +2884,9 @@ class _DeclarationLookup:
         # the cited files read, kept for the walk: a few files at most
         self._cited: dict[tuple[str, ...], list[str] | None] = {}
         self._cited_cache = _SourceCache()
+        # during the suspects' pass only (`keep_declaring`): the lines of each
+        # file a declaration was found in, by path, which `renamed` reads
+        self._declaring: dict[str, list[str]] | None = None
 
     # -- the walk root ------------------------------------------------------
 
@@ -2921,8 +3022,8 @@ class _DeclarationLookup:
                     found.append((*below, filename))
         return sorted(found)
 
-    @staticmethod
     def _first(
+        self,
         parts: tuple[str, ...],
         lines: list[str],
         name: str,
@@ -2931,11 +3032,16 @@ class _DeclarationLookup:
     ) -> str | None:
         """`file:line` of the first line of a file that declares `name`, else,
         with `module_fallback`, its line 1 when it is the module or package
-        so named (`declared_line`)."""
+        so named (`declared_line`). After `keep_declaring`, the file's lines
+        are kept for `renamed`."""
         line = declared_line(
             parts, name, lines=lines, cache=cache, module_fallback=module_fallback
         )
-        return f"{'/'.join(parts)}:{line}" if line is not None else None
+        if line is None:
+            return None
+        if self._declaring is not None:
+            self._declaring['/'.join(parts)] = lines
+        return f"{'/'.join(parts)}:{line}"
 
     # -- the answer ---------------------------------------------------------
 
@@ -3018,6 +3124,36 @@ class _DeclarationLookup:
                     hits[name].append(hit)
         return {name: sorted(_without_stubs(h)) for name, h in hits.items()}, unsure
 
+    def keep_declaring(self) -> None:
+        """From now on, keep the lines of each file a declaration is found in,
+        for `renamed`: the suspects' pass, which comes last."""
+        self._declaring = {}
+
+    def renamed(self, name: str, hits: list[str], files: list[str]) -> str | None:
+        """The first of `hits` (`file:line` declarations of `name` the lookup
+        found, sorted) whose line renames to `name`, as an item of an export
+        list or of a Python `from X import` clause (`_renamed_locals`), a
+        name `L` one of `files` (source_file values, as recorded) declares:
+        `declared_line` gives `L` a line of that file, no module or package
+        so named counting. The lines are the ones the lookup read after
+        `keep_declaring` (`_first`), never read again. None when no hit is
+        such an alias."""
+        cited = list(dict.fromkeys(filter(None, map(_cited_parts, files))))
+        for hit in sorted(hits):
+            file, _, number = hit.rpartition(":")
+            lines, family = (self._declaring or {}).get(file), _rule_family(file)
+            if lines is None or family is None or not number.isdigit():
+                continue
+            for local in _renamed_locals(lines, int(number) - 1, name, family):
+                for parts in cited:
+                    source = self._cited_lines(parts)
+                    if source is not None and declared_line(
+                        parts, local, lines=source, cache=self._cited_cache,
+                        module_fallback=False,
+                    ) is not None:
+                        return hit
+        return None
+
 
 def inventory_kinds(data: object, path: str) -> dict[str, frozenset[str]]:
     """name -> the kinds a documented inventory gives it (`--inventory`):
@@ -3054,18 +3190,26 @@ def classify_stale(
     """The fabricated-signature test for each stale name: the definition-lines
     rules at every provenance entry whose raw `export_name` is the name, and
     for a name that is not fabricated, where the source declares it
-    (`defined_at`, and `declared_in` when the walk looked for it). The
-    classify-stale section of the module docstring gives each reason, what
-    a `no-file` entry means, which entry gives `source` and how
-    `defined_at` and `declared_in` are found. `kinds` (`inventory_kinds`,
-    None without `--inventory`) keeps a name of a `NO_MODULE_KINDS` kind
-    from a module or package so named, unless an entry of the name is a
-    `module` or `package` one.
+    (`defined_at`, and `declared_in` when the walk looked for it). A name
+    the cited files do not define is looked up too, after the others and
+    in a lookup of its own (an error there keeps it fabricated and clears
+    no other name), with no module or package so named counting unless it
+    is the export, and is `aliased`, not fabricated, when one of its
+    declarations is an export-list or `from X import` item renaming to it
+    a name a `checked` entry's file declares (`_DeclarationLookup.renamed`);
+    any other such name keeps both null. The classify-stale section of the
+    module docstring gives each reason, what a `no-file` entry means, which
+    entry gives `source` and how `defined_at` and `declared_in` are found.
+    `kinds` (`inventory_kinds`, None without `--inventory`) keeps a name of
+    a `NO_MODULE_KINDS` kind from a module or package so named, unless an
+    entry of the name is a `module` or `package` one.
     """
     entries = [e for e in prov.get("entries") or [] if isinstance(e, dict)]
     results: list[dict] = []
-    # the names to look up (never a fabricated one): name -> its cited files
+    # the names to look up that are not fabricated: name -> its cited files
     cited: dict[str, list[str]] = {}
+    # the not-defined names an alias may clear: name -> its checked entries' files
+    suspects: dict[str, list[str]] = {}
     # the names a module so named does not declare
     strict: set[str] = set()
     for name in names:
@@ -3097,7 +3241,12 @@ def classify_stale(
             reason = STALE_UNCHECKED
         source = next(filter(None, map(_entry_citation, mine)), None)
         fabricated = reason == STALE_NOT_DEFINED
-        if not fabricated:
+        if fabricated:
+            # a missing file declares nothing an alias could rename
+            checked = [c["source_file"] for c in checks if c["line_check"] == "checked"]
+            if checked:
+                suspects[name] = checked
+        else:
             cited[name] = [f for f in map(_entry_file, mine) if f is not None]
             documented = (kinds or {}).get(name, frozenset())
             if documented & NO_MODULE_KINDS and not any(map(_module_entry, mine)):
@@ -3113,16 +3262,43 @@ def classify_stale(
                 "entries": checks,
             }
         )
+    lookup: _DeclarationLookup | None = None
     try:
-        found, declared = _DeclarationLookup(entries, source_root).find(
-            cited, frozenset(strict)
-        )
+        lookup = _DeclarationLookup(entries, source_root)
+        found, declared = lookup.find(cited, frozenset(strict))
     except _LOOKUP_ERRORS:
         # a lookup that fails proves nothing: every name stays null
         found, declared = {}, {}
+    # the suspects' own lookup, after: an error there clears no name settled
+    # above, and keeps every suspect fabricated
+    aliased: dict[str, str] = {}
+    suspect_declared: dict[str, list[str]] = {}
+    if suspects and lookup is not None:
+        try:
+            # a suspect is strict: a cited module so named settles it before
+            # the walk only when it is the export
+            lookup.keep_declaring()
+            suspect_found, suspect_declared = lookup.find(suspects, frozenset(suspects))
+            for name, files in suspects.items():
+                hits = suspect_declared[name] if name in suspect_declared else (
+                    [suspect_found[name]] if name in suspect_found else []
+                )
+                hit = lookup.renamed(name, hits, files)
+                if hit is not None:
+                    aliased[name] = hit
+        except _LOOKUP_ERRORS:
+            aliased, suspect_declared = {}, {}
     for item in results:
-        item["defined_at"] = found.get(item["name"])
-        item["declared_in"] = declared.get(item["name"])
+        name = item["name"]
+        if name in suspects:
+            if name in aliased:
+                item.update(
+                    fabricated=False, reason=STALE_ALIASED,
+                    defined_at=aliased[name], declared_in=suspect_declared.get(name),
+                )
+            continue  # any other suspect stays fabricated, both null
+        item["defined_at"] = found.get(name)
+        item["declared_in"] = declared.get(name)
     return results
 
 

package/src/skf-analyze-source/customize.toml

@@ -59,8 +59,9 @@ analysis_report_template_path = "templates/analysis-report-template.md"
 # written the result files, at the end of every run that writes them
 # (generate-briefs.md, step-auto-scope.md and auto-docs-only.md), as:
 #   <on_complete> --result-path=<forge_data_folder>/analyze-source-result-latest.json
-# A run whose result file could not be written (result_path null in the
-# envelope) and a HALT call no hook. Useful for Slack notifications,
+# A HALT calls no hook, nor does a run whose result file or its -latest
+# copy could not be written (result_path null, or a result_file_write_failed
+# warning naming the copy, in the envelope). Useful for Slack notifications,
 # dashboard ingest, CI hooks, or chaining into a brief linter. A hook
 # failure is displayed and never fails the run.
 #

package/src/skf-analyze-source/references/auto-docs-only.md

@@ -145,9 +145,9 @@ Add `"coexistence": "alongside"` when `{coexistence_suffix}` is non-empty ([A]lo
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `auto-docs-only:5`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
+The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim. 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, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `auto-docs-only:5`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
 
-If `{onCompleteCommand}` is non-empty and the line's `result_path` is not null, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run.
+If `{onCompleteCommand}` is non-empty, the line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `analyze-source-result-latest.json`, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run. When `{onCompleteCommand}` is non-empty but `result_path` is null or a `result_file_write_failed` warning names `analyze-source-result-latest.json` (the copy alone failed), skip the hook and say so: "on_complete skipped: `analyze-source-result-latest.json` was not written."
 
 ### 6. Chain to health check
 

package/src/skf-analyze-source/references/generate-briefs.md

@@ -287,11 +287,11 @@ The shared emitter writes the result files and prints the envelope; this section
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path; a caller reads its own run's `SKF_ANALYZE_RESULT_JSON` line), and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim: it is the success signal of a headless run. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:9`, path `{forge_data_folder}`, with `brief_paths` and `unit_counts` from the payload): "The result contract could not be written: {its message}."
+The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path; a caller reads its own run's `SKF_ANALYZE_RESULT_JSON` line), and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim: it is the success signal of a headless run. 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, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:9`, path `{forge_data_folder}`, with `brief_paths` and `unit_counts` from the payload): "The result contract could not be written: {its message}."
 
 ### 9b. On-Complete Hook (pipeline integration)
 
-If `{onCompleteCommand}` is non-empty and the §9 line's `result_path` is not null, invoke it now, after the emitter wrote the timestamped result JSON and its `analyze-source-result-latest.json` copy:
+If `{onCompleteCommand}` is non-empty, the §9 line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `analyze-source-result-latest.json` (the emitter wrote the timestamped result JSON and its `analyze-source-result-latest.json` copy), invoke it now:
 
 ```
 {onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json
@@ -303,8 +303,10 @@ The stable `-latest` path is preferred over the timestamped copy so downstream c
 - On non-zero exit / process error: display the hook failure (`on_complete hook failed (exit {code}): {stderr_snippet}`); it never fails the run.
 - **Never fail the workflow on hook errors** — the hook is for pipeline integration (Slack, dashboards, CI), not for gating skill-brief production.
 
+When `{onCompleteCommand}` is non-empty but `result_path` is null or a `result_file_write_failed` warning names `analyze-source-result-latest.json` (the copy alone failed), skip the hook and say so: "on_complete skipped: `analyze-source-result-latest.json` was not written." The hook never gets a `-latest` copy this run failed to write.
+
 If `{onCompleteCommand}` is empty, skip this section entirely (default behavior — no hook configured).
 
 ### 10. Chain to Health Check
 
-After the briefs are written (or skipped, or none was confirmed), the report updated, the summary presented, the run ended in §9 and the on-complete hook invoked (or skipped per empty `{onCompleteCommand}`), delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step: continue past the summary even though it reads as final.
+After the briefs are written (or skipped, or none was confirmed), the report updated, the summary presented, the run ended in §9 and the on-complete hook invoked (or skipped as §9b says), delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step: continue past the summary even though it reads as final.

package/src/skf-analyze-source/references/headless-contract.md

@@ -17,7 +17,7 @@ SKF_ANALYZE_RESULT_JSON: {"status":"success|error|redirect|skipped","report_path
 - `brief_paths`: absolute path of every `skill-brief.yaml` the run wrote (empty array if none). A brief is written only after it passed the brief writer and, outside the docs-only branch, the schema gate.
 - `unit_counts` — `confirmed` (units approved for briefs) and `skipped` (rejected in step 5, or the skipped target in coexistence §0c) counts; auto mode reports `confirmed:N, skipped:0`. `maybe` is a reserved slot, currently always `0`.
 - `mode`: `"auto"` when the invocation carries `[auto]`, from activation through step 1a and the docs-only branch; `"interactive"` otherwise, also in the step-by-step chain an `[auto]` run falls back to (step 1a §3, exit 1).
-- `result_path`: the per-run result file the emitter wrote, stamped by it; `null` for a HALT, which writes no result file, and when the write failed (a `result_file_write_failed` warning then says why).
+- `result_path`: the per-run result file the emitter wrote, stamped by it; `null` for a HALT, which writes no result file, when `--result-dir` names no folder (with no warning), and when the per-run record could not be written (a `result_file_write_failed` warning then says why); a `-latest` copy that could not be written leaves it set, and a `result_file_write_failed` warning names the copy.
 - `error`: on a HALT only, `{"phase", "reason"}` plus `path` when the halt names one.
 - `headless_decisions`: present when the run recorded an auto-decision: step 1a's §3b merge-or-split decision (gate `auto-scope.cohesion`), its §4 choices of shape for a repository on a framework or a parser library (gate `auto-scope.shape`) and its §5 choice of the documented language (gate `auto-scope.language`), and each gate default a headless run of the step-by-step chain took: `scan-project.scan`, `identify-units.classifications`, `map-and-detect.findings` (with the composite merges it accepted), `recommend.recommendations` and `generate-briefs.write`.
 - `warnings`: present when the run recorded at least one.
@@ -32,7 +32,7 @@ The step that ends the run stages `{run_dir}/result-context.json` with the envel
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time, the run id, the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the line. 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, the step corrects the payload from the message on its stderr and runs it once more; if it fails again, it HARD HALTs with exit code 4 (`write-failed`). Then `{onCompleteCommand}` runs, when it is set and `result_path` is not null, with `--result-path={forge_data_folder}/analyze-source-result-latest.json`; a hook failure is displayed and never fails the run. Last, the step deletes `{run_dir}` and chains to step 7.
+The emitter stamps the UTC time, the run id, the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the line. 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, the step corrects the payload from the message on its stderr and runs it once more; if it fails again, it HARD HALTs with exit code 4 (`write-failed`). Then `{onCompleteCommand}` runs, when it is set, `result_path` is not null and no `result_file_write_failed` warning names `analyze-source-result-latest.json`, with `--result-path={forge_data_folder}/analyze-source-result-latest.json`, and a hook failure is displayed and never fails the run; otherwise a set hook is skipped with "on_complete skipped: `analyze-source-result-latest.json` was not written." Last, the step deletes `{run_dir}` and chains to step 7.
 
 ## Halt Envelope
 

package/src/skf-analyze-source/references/step-auto-scope.md

@@ -447,8 +447,8 @@ Add `"coexistence": "alongside"` when `{coexistence_suffix}` is non-empty ([A]lo
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time, the run id and the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:9`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
+The emitter stamps the UTC time, the run id and the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim. 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, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:9`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
 
-If `{onCompleteCommand}` is non-empty and the line's `result_path` is not null, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run.
+If `{onCompleteCommand}` is non-empty, the line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `analyze-source-result-latest.json`, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run. When `{onCompleteCommand}` is non-empty but `result_path` is null or a `result_file_write_failed` warning names `analyze-source-result-latest.json` (the copy alone failed), skip the hook and say so: "on_complete skipped: `analyze-source-result-latest.json` was not written."
 
 Then delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Load, read fully, then execute {nextStepFile} to run the shared workflow health check.