bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/shared/references/pipeline-contracts.md

@@ -9,10 +9,10 @@ Pipelines chain multiple SKF workflows in sequence. The forger orchestrates the
 The forger recognizes pipeline invocations when the user provides multiple workflow codes:
 
 ```
-AN CS TS EX              — space-separated codes
-AN -> CS -> TS -> EX     — arrow-separated (equivalent)
-BS CS[cocoindex] TS EX   — with target argument in brackets
-CS TS[min:80] EX         — with circuit breaker threshold
+QS[cocoindex] TS EX                          # space-separated codes, the first code's input in brackets
+QS[cocoindex] -> TS -> EX                    # arrow-separated (equivalent)
+AN[https://github.com/honojs/hono] CS TS EX  # a project path in AN's bracket
+QS[cocoindex] TS[min:80] EX                  # with circuit breaker threshold
 ```
 
 The forger also accepts common pipeline aliases:
@@ -39,6 +39,8 @@ The forger also accepts common pipeline aliases:
 
 ## Pipeline Arguments
 
+An alias takes its arguments after it, and they go, in order, to the inputs of the alias's first workflow: `forge-auto <repo-or-doc-url>` gives AN its `project_path`, `forge <repo-url-or-path> <skill-name>` gives BS its `target_repo` and `skill_name`, `forge-quick <package-or-url>` gives QS its `target`, and `maintain <skill>` gives AS its `skill_name`. The forger's `parse-pipeline.py` script binds them and returns them as `args`. A missing or left-over argument, a flag the pipeline does not take, or a `--pin` with no value stops the pipeline before any workflow runs.
+
 Pipeline-level arguments (e.g., `--pin <version>`) are passed to the first workflow's data context. The workflow decides how to consume them. For the `forge-auto` pipeline, `--pin` flows to AN, where `step-auto-scope.md §0b` uses it for pin resolution.
 
 ## Data Flow
@@ -52,55 +54,117 @@ How outputs from one workflow become inputs to the next:
 | BS | CS | `skill-brief.yaml` path | Forger passes the brief path written by BS as `brief_path` to CS |
 | CS | TS | skill name (derived from brief) | Forger passes the `skill_name` from the completed CS to TS |
 | CS | EX | skill name | Same — forger resolves the created skill's name |
-| TS | EX | skill name + test result | Forger checks `result` field in test report; if FAIL and circuit breaker active, halts |
+| TS | EX | skill name + settled verdict | EX runs only when TS settled PASS (`next_workflow` is `export-skill`); FAIL, INCONCLUSIVE and pass-with-drift halt the pipeline before EX, with the verdict as the halt reason |
 | QS | TS | skill name (from `repo_name`) | Forger passes the quick-skill's output name to TS |
 | QS | EX | skill name | Same |
-| AS | US | skill name + drift severity | Forger checks `summary.severity` in `audit-skill-result-latest.json`; if CLEAN, skips US |
+| AS | US | skill name + drift severity + route + upstream ref | The forger's gate reads the drift severity (`drift_score`) and the route (`next_workflow`) from the envelope AS printed. CLEAN skips US unless `next_workflow` is `update-skill`, which AS sets when upstream moved past the ref the skill was built from (`upstream_moved`). AS then hands on its `upstream_ref`: the gate prints it as `handoff.target_ref`, `pipeline-journal.py step --gate` records it, and US takes it as `--target-ref`, so the update reads the ref the audit found |
+| US | TS | skill name | Forger passes the `skill_name` US updated to TS: the skill `maintain` names, or the one a repair updates |
 | VS | RA | architecture doc path | Already known from VS invocation |
 
 ## Circuit Breakers
 
-Circuit breakers halt the pipeline when a workflow's output doesn't meet a quality threshold:
+Circuit breakers halt the pipeline when a workflow's output doesn't meet a quality threshold. The forger's `pipeline-gate.py` script applies the AN, TS, AS and VS rows to the result envelope a workflow printed (a field name after a slash is its spelling in the workflow's result record) and answers continue, skip or halt with a reason; CS's row is a hard halt, which stops the pipeline by itself.
 
 | Workflow | Check | Default Threshold | Halt Condition |
 |----------|-------|-------------------|----------------|
-| AN | recommended units count | min: 1 | Zero skillable units found |
+| AN | recommended units count (`unit_counts.confirmed`) | min: 1 | Fewer units than the minimum (by default, zero skillable units found) |
 | CS | compilation success | must complete | Hard error during compilation |
-| TS | completeness score | min: 60 (per-pipeline defaults apply — see init.md §1b) | Score below 80% floor (scores between 80% and per-pipeline threshold produce a fallback PASS with evidence report — pipeline continues) |
-| AS | drift score | not CRITICAL | Critical drift found |
-| VS | feasibility verdict | not BLOCKED | All integrations blocked |
+| TS | settled verdict (`verdict` / `summary.result`, with `next_workflow`) | TS's own: `TS[min:N]` reaches TS as `--threshold=N`, else the per-pipeline defaults apply (see init.md §1b) | Any verdict but PASS, reported as the halt reason: FAIL (including a FAIL that a post-score cap forced although the score clears the threshold), INCONCLUSIVE or pass-with-drift. TS owns its score, caps and 80% floor: a score between 80% and a higher threshold that TS settles as a fallback PASS with an evidence report continues |
+| AS | drift severity (`drift_score` / `summary.severity`) with the route (`next_workflow` / `summary.next_workflow`) | not CRITICAL | CRITICAL drift found (CLEAN skips a US that comes next, unless `next_workflow` is `update-skill`: upstream moved, so the update still runs) |
+| VS | coverage (`coverage_percentage` / `summary.coveragePercentage`) with the overall verdict (`overall_verdict` / `summary.overallVerdict`) | coverage above 0% | Zero coverage (`zero-coverage`): VS verified none of the architecture's technologies. Every verdict with coverage continues, NOT_FEASIBLE included, since RA takes each Blocked integration as a critical issue |
 
-Override syntax: `TS[min:80]` sets the test-skill threshold to 80 for this pipeline run.
+Override syntax: `TS[min:80]` sets the test-skill threshold to 80 for this pipeline run (the forger passes it to TS as `--threshold=80`), and `AN[min:2]` asks AN for at least two units.
 
 ### Bracket Syntax
 
 Brackets after a workflow code (`CODE[value]`) are parsed as follows:
 
-- **Circuit breaker override**: `min:N` where N is a number — e.g., `TS[min:80]` sets the threshold for that workflow
+- **Circuit breaker override**: `min:N` where N is a number, on AN or TS (the override syntax above), e.g. `TS[min:80]`
 - **Mode flag**: `auto` — e.g., `AN[auto]` activates auto mode for that workflow. The workflow's first step reads the flag from pipeline data context and routes to the appropriate auto-mode step file.
 - **Target argument**: any other value — e.g., `CS[cocoindex]` passes "cocoindex" as the target to CS
 
-Only workflows with a circuit breaker entry (AN, CS, TS, AS, VS) accept `min:N` overrides. All other workflows ignore `min:N` brackets. Target arguments are valid for any workflow that accepts a named input (CS, QS, BS, US, etc.).
+The keywords `min` and `auto` match in any case (`TS[MIN:80]`). A bracket that starts like `min` but is not `min:<number>` (`TS[min:80%]`, `TS[min=80]`) is malformed: the pipeline stops before any workflow runs rather than pass it on as a target.
+
+Only AN (a unit count) and TS (a test threshold) take `min:N`. CS, AS and VS have circuit breakers with no number to set, so a `min:N` on them, as on any other code, is ignored, and the forger warns about it. Target arguments are valid for any workflow that accepts a named input (CS, QS, US, etc.). A bracket holds one value, so a chain led by BS gets its target and skill name only as `forge <repo-url-or-path> <skill-name>`, and RS and DS, which need more than one input, run on their own, outside a chain: `parse-pipeline.py` reports each as the chain's `first_input`.
 
 ## Pipeline State
 
-The forger tracks pipeline state in memory during execution:
-
-```yaml
-pipeline:
-  alias: "forge"          # pipeline alias name, or null for ad-hoc sequences
-  workflows: [AN, CS, TS, EX]
-  current_index: 1
-  completed:
-    - {code: AN, status: ok, output: {units: 3, briefs: [...]}}
-  pending: [CS, TS, EX]
-  data:
-    pipeline_alias: "forge" # forwarded to each workflow's data context (consumed by TS init.md §1b for per-pipeline threshold lookup)
-    skill_name: "cocoindex"
-    brief_path: "/path/to/skill-brief.yaml"
-    target: "cocoindex"
+The forger keeps a chain's state on disk, never only in the conversation, so a closed session, a killed terminal or a compacted context loses nothing. Its `scripts/pipeline-journal.py` writes the state, and nothing else does: a journal, `pipeline-journal.json`, in the run's own folder `{project-root}/_bmad-output/.skf-run/skf-forger-<run_id>/`, written when the chain starts, after every workflow, and when a resume picks the chain up again.
+
+| Field | What it holds |
+| --- | --- |
+| `journal_version` | `1` |
+| `run_id` | the UTC time the chain started and a random suffix (`20261001T120000Z-3f9a1c2e`), also the run folder's suffix |
+| `status` | `running` from the start, `halted` once a step halted; a chain cut off mid-step stays `running` |
+| `started_at`, `updated_at` | the UTC times of the journal's first and last write |
+| `invocation` | the whole invocation the chain started from |
+| `alias` | the pipeline alias name (`forge-auto`, `forge`, `forge-quick`, `maintain`), or null for an ad-hoc sequence |
+| `args` | the first workflow's inputs, the parse's `args` (`project_path`, `pin` ...) |
+| `steps` | one entry per workflow, in plan order |
+| `data` | each value a workflow handed the next, by its Data Flow name (`skill_name`, `brief_path` ...); a name one call gave twice holds a list |
+| `outputs` | each result or report path a workflow's envelope named, with its code |
+| `history` | each halt a resume or repair picked up again: its code, reason, repair and time |
+
+Each entry of `steps` has one shape, in the journal and in the pipeline result alike:
+
+```json
+{"code": "TS", "min": 90, "mode": null, "target": null, "flags": [], "status": "halted", "reason": "FAIL"}
+```
+
+`min`, `mode` and `target` are the plan's bracket values (Bracket Syntax), a resumed chain's first step also taking the journal's skill as its `target`, and `flags` the flags a repair adds (`--from-test-report`). `status` is `pending` (not run yet), `completed`, `skipped` (a gate passed over it) or `halted`, and `reason` is the gate's or the workflow's halt reason, a gate's reason for a skip, or null.
+
+Every chained workflow's data context carries `pipeline_mode: true`, which marks pipeline context even for an ad-hoc sequence, and `pipeline_alias`, the journal's `alias`, which TS reads in init.md §1b for the per-pipeline threshold lookup.
+
+## Pipeline Result
+
+`pipeline-journal.py finish` writes each chain's result from its journal, per `output-contract-schema.md`: the per-run record `{sidecar_path}/pipeline-result-<YYYYMMDD-HHmmss>.json` (UTC; `-2`, `-3` ... when a run already took that second's name) and its copy `{sidecar_path}/pipeline-result-latest.json`, the file consumers read.
+
+```json
+{
+  "skill": "skf-forger",
+  "status": "partial",
+  "timestamp": "2026-10-01T12:31:07Z",
+  "run_id": "20261001T120000Z-3f9a1c2e",
+  "outputs": [{"type": "report", "path": "forge-data/hono/1.2.0/create-skill-result-latest.json"}],
+  "summary": {
+    "status": "partial",
+    "halt_reason": "FAIL",
+    "alias": "forge-auto",
+    "steps": [
+      {"code": "CS", "min": null, "mode": null, "target": null, "flags": [], "status": "completed", "reason": null},
+      {"code": "TS", "min": 90, "mode": null, "target": null, "flags": [], "status": "halted", "reason": "FAIL"}
+    ]
+  },
+  "headless_decisions": [],
+  "warnings": []
+}
 ```
 
+`status` and `summary.status` are `success` when no step halted, `partial` when a step halted after another completed, and `failed` when one halted before any completed, or when the chain stopped before its journal started (at its parse, or a `start` that failed) or lost it: such a record lists no step. `summary.halt_reason` is the halted step's `reason`, null on success, and `summary.steps` lists every step of the plan in the Pipeline State shape, one that never ran as `pending` (the example shows two of five). `headless_decisions` stays empty, and `warnings` names what `finish` could not do: save or read the journal, or delete the run folder.
+
+## Resume and Repair
+
+At activation the forger runs `pipeline-journal.py resume`, which reads the newest journal a stopped chain left. It offers nothing when no journal is left, when a later chain recorded a result with a step in it (any pipeline result in the sidecar, the per-run records included: a record with no step, such as a parse halt's, supersedes nothing), or when the journal's skill was tested or exported after the journal's last write: a test result record or an export manifest entry, which WS reads too, dated after it. The manifest dates an export by its day only, so an export that same day counts when the manifest was written after the journal, whichever skill that write was for. Otherwise it offers one of two things:
+
+- **Resume** after an interruption (the journal is still `running`) or a halt that is no quality verdict, such as a workflow that hard-halted or a result the gate could not read: the chain re-runs the step it stopped on, then the rest of the plan, with the recorded alias, bracket values and arguments.
+- **Repair** after a quality halt: the repair the table below gives, then the chain picks up where the table says, still with the recorded alias and threshold.
+
+`finish` prints the same next action when the chain stops, and both print it with its `route`, the next action in one line (`US hono --from-test-report, then TS EX at the recorded threshold of 90`), and its `user_action`, what the user does before the chain picks up again (null when the chain does it all). `pipeline-journal.py reopen` applies the offer the user accepts (the Resume procedure in the forger's pipeline-mode.md), and `discard` deletes a stopped chain's run folder, so its offer is made no more.
+
+### Repair Routes
+
+| Halted on | Reason | `repair` | `user_action` | The chain picks up at |
+| --- | --- | --- | --- | --- |
+| TS | `FAIL` | `update-from-test-report` | none: `US <skill> --from-test-report` joins the plan as the next step and fixes the gaps the test report lists | TS, at the recorded threshold |
+| TS | `INCONCLUSIVE` | `add-evidence` | add evidence: install skill-check, or move up a tier (the tier's tools, then `SF`) | TS |
+| TS | `pass-with-drift`, `workspace-drift` | `retest-at-pinned-commit` | put the source back at the commit the skill pins | TS, without `--allow-workspace-drift` |
+| AS | `CRITICAL` | `review-drift-report` | review the drift report | the step after AS |
+| VS | `zero-coverage` | `create-missing-skills` | create skills for the architecture's technologies (for example `forge-quick <package>`) | VS |
+| AN | `no-skillable-units`, `units-below-min`, `skipped` | `new-target` | start a new chain with another target, or with a scope hint | no resume |
+| AN | `redirect` | `update-existing-skill` | run `US` on the skill the target already has | no resume |
+
+A halt with no resume leaves no journal behind: `finish` deletes its run folder, as it does after a chain that succeeded, and its `route` is `no resume:` and the `user_action`.
+
 ## Anti-Patterns
 
 The forger validates the pipeline sequence and warns about:
@@ -112,3 +176,4 @@ The forger validates the pipeline sequence and warns about:
 | CS without BS or AN | Compiling without brief | Need a brief — use QS for quick path, or AN for brownfield |
 | TS after EX | Testing after export | Move TS before EX |
 | Duplicate codes | Same workflow twice | Remove duplicate |
+| `min:N` on a code other than AN or TS | Threshold ignored | Remove it, or put it on TS |

package/src/shared/references/tessl-review.md

@@ -0,0 +1,77 @@
+# Tessl Review
+
+Tessl Review scores a skill on Tessl's servers. It runs deterministic validation checks and two AI judges, one for the frontmatter `description` (specificity, completeness, trigger-term quality, distinctiveness) and one for the body and the files beside it (conciseness, actionability, workflow clarity, progressive disclosure), and weighs them into one review score from 0 to 100, with suggestions. It reads the whole skill folder, so a skill whose Tier 2 sections moved to `references/` is judged with them.
+
+create-skill (step 6 §6b) and test-skill (step 4b §3) run it through `skf-tessl-review.py`. No step file runs tessl itself, and neither workflow halts, asks the user anything or changes a file because of a review.
+
+## When It Runs
+
+The helper checks these conditions in order and stops at the first one that fails:
+
+1. **Opt-in.** `tessl_review_workspace` in `{sidecar_path}/preferences.yaml` names one of the user's Tessl workspaces. A missing key, `~`, `false` or an empty value means off, the default in interactive and headless runs alike. Setting the key is the user's consent to upload the files listed below to that workspace.
+2. **Installed.** `tessl` is on `PATH`, or its npm launcher is already in the npx cache. SKF never installs tessl.
+3. **Signed in.** `tessl whoami` succeeds: the user ran `tessl login`, or `TESSL_TOKEN` is set for an unattended run.
+
+The helper's `submit` then sends the copy as `tessl review run <copy> --workspace <tessl_review_workspace> --no-wait --json` and removes the copy once tessl answers with the review's run id, and its `collect` reads the review with `tessl review view <run id> --json`, the only tessl command it runs. A check that fails without an answer SKF can read, or does not answer in time, is tried again, since Tessl may still finish the review. Every tessl call runs with a temporary folder as its working directory, so tessl never reads or writes the user's project.
+
+## What Is Uploaded
+
+Only the files an agent loads from the skill: `SKILL.md` and the `references/`, `scripts/` and `assets/` folders, copied without links into a temporary folder named after the skill. `metadata.json`, `context-snippet.md` and the workspace artifacts create-skill stages beside them (`provenance-map.json`, `evidence-report.md`) stay on the machine. Tessl keeps each review in the workspace's review history.
+
+create-skill reviews the staged skill, which holds no `scripts/` or `assets/` until step 7 copies them, so for a skill with scripts or assets its validation findings may name those paths as missing. test-skill reviews the finished package.
+
+## Cost and Time
+
+Each fresh review spends credits from the Tessl account's plan, and each workflow run with the review on can spend one. Re-reviewing a skill folder Tessl has already reviewed can return Tessl's cached result without spending credits. A review takes Tessl about two minutes, and no helper call waits for all of it, so every call ends within two minutes, inside a shell tool's default time limit: `submit` returns as soon as Tessl has accepted the review, and each `collect` checks it for up to 90 seconds, then returns `pending` again or the result. The calling step collects at most six times, about ten minutes in all, and its sixth call passes `--final`, which turns a review still running into `timeout`.
+
+## Results
+
+The helper prints one JSON object whose keys are always present. Both workflows record its `summary` as the line `Tessl Review: {summary}`:
+
+| `status` | Summary starts with | Meaning |
+|---|---|---|
+| `reviewed` | `reviewed — score` | Tessl finished. The scores, validation findings and suggestions are filled in. |
+| `pending` | `no result yet — Tessl Review run` | Tessl accepted the review and SKF has not seen it finish. The calling step collects it again until its sixth `collect`, which reports `timeout` instead. |
+| `off` | `off —` | `tessl_review_workspace` is not set. |
+| `invalid-config` | `not run — tessl_review_workspace must be` | The key holds something that is not a workspace name of letters, digits, `.`, `_` and `-`. |
+| `not-installed` | `not run — tessl is not installed` | Neither `tessl` nor a cached npm launcher was found. |
+| `signed-out` | `not run — not signed in to Tessl` | `tessl whoami` or the review reported that the user is not signed in. |
+| `command-unavailable` | `not run — the installed tessl has no working review run command` | The installed tessl lacks or replaced `tessl review run`. |
+| `unknown-run` | `no result — Tessl has no review run` | `tessl review view` found no review with the run id `collect` was given, or that id is not a Tessl run id. |
+| `timeout` | `no result — Tessl Review run` | SKF had not seen the review finish when the sixth `collect` ended: Tessl was still working, or its last checks failed or did not answer. The review may still complete in the workspace (`tessl review view <run id>`). |
+| `failed` | `failed —` | tessl's own message, for example about the workspace, or a skill file the helper could not read, or a tessl call that did not answer in time. The steps record `failed — stopped before skf-tessl-review.py reported a result` when the shell tool stopped a helper call, and keep the run id when Tessl had accepted the review. |
+| `parse-failure` | `failed — Tessl Review output could not be read` | tessl printed no review SKF can read. |
+
+Only `reviewed` produces a score. For every other status the scores are null, and test-skill then scores External Validation from skill-check alone.
+
+## Floors
+
+The helper adds a warning for each of the review, description and content scores that is below 60%, and one when validation reports errors. For every status other than `reviewed` and `off` it adds the summary itself as a warning, so a review that was switched on but produced no score shows in the run's warnings. Warnings never fail a run.
+
+## Suggestions
+
+SKF never applies a Tessl suggestion. Content suggestions would add text SKF cannot cite to source, and the description is compiled from the brief, so a description suggestion is acted on by editing the brief and re-running create-skill. Both workflows list the suggestions as advice and mark each content suggestion that a rule below matches with `(not applicable: <rule-id>)`, because following it would break SKF's design. The judges do not know that design, so lower conciseness and progressive-disclosure scores are expected on SKF skills.
+
+### Rule: `keep-manual-markers`
+
+- **Matches:** removing, cleaning up or replacing `<!-- [MANUAL] -->` markers, including empty MANUAL placeholder blocks.
+- **Why:** update-skill keeps the content an author writes between these markers when it regenerates the skill.
+
+### Rule: `keep-tier2-inline`
+
+- **Matches:** moving a `## Full …` section (API reference, type definitions, integration patterns) into a separate file while the body is within the size limit.
+- **Why:** create-skill step 6 §4 moves Tier 2 sections to `references/` only when the body is over the limit, because inline context serves agents better than on-demand retrieval.
+
+### Rule: `keep-both-tiers`
+
+- **Matches:** merging the Key API Summary or Quick Start into the Full API Reference, or removing parameters that both list.
+- **Why:** Tier 1 lists the key parameters so an agent finds them at once, and Tier 2 holds the complete tables. That is progressive disclosure, not duplication.
+
+### Rule: `keep-provenance`
+
+- **Matches:** removing, shortening or moving `[SRC:…]`, `[AST:…]`, `[QMD:…]` or `[EXT:…]` citations.
+- **Why:** every claim carries its source, so update-skill can detect drift and audit-skill can verify the claim.
+
+## Evolving These Rules
+
+Add a rule when a Tessl suggestion keeps coming back that would break an SKF design principle, and name that principle in its **Why** line; a rule that protects no principle is a smell. Change the floor in the helper and here together.

package/src/shared/scripts/schemas/skf-analyze-result-envelope.v1.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-analyze-result-envelope.v1.json",
+  "title": "SKF_ANALYZE_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-analyze-source prints, prefixed with the literal 'SKF_ANALYZE_RESULT_JSON: ': on stdout when a run ends (briefs written, zero units confirmed, a coexistence redirect or skip), and on stderr at every HARD HALT of a headless run. The shared emitter builds each line from the payload a step stages, so pipelines branch on status, halt_reason and unit_counts without parsing the human-readable report. src/skf-analyze-source/references/headless-contract.md describes each field.",
+  "$defs": {
+    "skf-envelope": {
+      "description": "The shared emitter's settings for this workflow, read by skf-emit-result-envelope.py: the workflow, the line's prefix, the status a halt carries, the exit code of each halt_reason and the result file stem. Nothing in the schema references this entry, so it constrains no envelope.",
+      "const": {
+        "workflow": "skf-analyze-source",
+        "prefix": "SKF_ANALYZE_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 2,
+          "resolution-failure": 3,
+          "pin-invalid": 3,
+          "write-failed": 4,
+          "user-cancelled": 6
+        },
+        "success_exit_code": 0,
+        "result_file": "analyze-source-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "report_path", "brief_paths", "unit_counts", "exit_code", "halt_reason", "mode", "result_path"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error", "redirect", "skipped"],
+      "description": "'success' when a run ends with its briefs written, or with none because no unit was confirmed. 'redirect' when the auto coexistence gate routes the target to an update of an existing skill ([M]erge). 'skipped' when it skips the target ([S]kip). 'error' at every HARD HALT."
+    },
+    "report_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "Absolute path of the analysis report. Null on a redirect, a skip and a HALT before the report was written."
+    },
+    "brief_paths": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "Absolute path of every skill-brief.yaml the run wrote. A brief is written only after it passed the brief writer and, outside the docs-only branch, the schema gate. Empty when no unit was confirmed, when the user chose not to write the briefs, and on a redirect, a skip and a HALT."
+    },
+    "unit_counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["confirmed", "skipped", "maybe"],
+      "properties": {
+        "confirmed": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Units approved for a brief (step 5, or the units step 1a confirmed)."
+        },
+        "skipped": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Units rejected in step 5, or 1 for the target a coexistence [S]kip passed over."
+        },
+        "maybe": { "type": "integer", "minimum": 0, "description": "Reserved, always 0." }
+      },
+      "default": { "confirmed": 0, "skipped": 0, "maybe": 0 },
+      "description": "The unit counts. A run that confirms no unit reports confirmed 0, which the forger's AN circuit breaker reads as no skillable unit."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 6],
+      "description": "Process exit code, derived from halt_reason: null gives 0 (success, redirect and skipped), input-missing 2, resolution-failure and pin-invalid 3, write-failed 4, user-cancelled 6."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [null, "input-missing", "resolution-failure", "pin-invalid", "write-failed", "user-cancelled"],
+      "description": "Null unless the run halted. One of the documented HALT classes on error; write-failed also covers a brief the writer or the schema gate rejects."
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["interactive", "auto"],
+      "default": "interactive",
+      "description": "'auto' when the invocation carries [auto], from activation through step 1a and its docs-only branch; 'interactive' otherwise, also in the step-by-step chain an [auto] run falls back to when shape detection cannot classify the repository."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "description": "The per-run result file the emitter wrote, {forge_data_folder}/analyze-source-result-<YYYYMMDD-HHmmss>.json (UTC), beside its analyze-source-result-latest.json copy. Stamped by the emitter, never typed. Null for a HALT, which writes no result file, and when the write failed (warnings say why)."
+    },
+    "error": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["phase", "reason"],
+          "properties": {
+            "phase": { "type": "string", "minLength": 1, "description": "The step and section that halted, such as 'step-auto-scope:8'." },
+            "reason": { "type": "string", "minLength": 1, "description": "The halt's one-line message." },
+            "path": { "type": "string", "description": "The file or folder the failed operation targeted, when the halt names one." }
+          }
+        }
+      ],
+      "description": "Optional. On a HALT, the step that halted and its message; absent when the run ended."
+    },
+    "coexistence": {
+      "type": "string",
+      "enum": ["alongside", "merge", "skip"],
+      "description": "Optional, auto mode only: the coexistence decision of step 1a section 0c when a skill already matched the target ('alongside' writes a -wiki skill beside it)."
+    },
+    "pinned_ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional, auto mode only: the git ref the run pinned (the --pin value, or the latest release tag). Absent when no pin resolved."
+    },
+    "pinned_version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional, auto mode only: the version of pinned_ref. Absent when no pin resolved, and for a pin with no version (a branch, or a latest release whose tag is not a version)."
+    },
+    "source_type": {
+      "type": "string",
+      "enum": ["docs-only"],
+      "description": "Optional: 'docs-only' when the target was a documentation URL, so brief-skill skips repo-based enrichment."
+    },
+    "redirect_to": {
+      "type": "string",
+      "enum": ["US"],
+      "description": "Optional, on a redirect only: the workflow the forger routes to (update-skill)."
+    },
+    "skill_name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional, on a redirect only: the existing skill to update."
+    },
+    "skill_path": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional, on a redirect only: the existing skill's active version folder."
+    },
+    "skipped_reason": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional, on a skip only: why the target was skipped."
+    },
+    "headless_decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gate", "default_action", "taken_action", "reason"],
+        "properties": {
+          "gate": {
+            "type": "string",
+            "enum": [
+              "auto-scope.cohesion",
+              "auto-scope.language",
+              "auto-scope.shape",
+              "scan-project.scan",
+              "identify-units.classifications",
+              "map-and-detect.findings",
+              "recommend.recommendations",
+              "generate-briefs.write"
+            ],
+            "description": "The decision the run took with no one to ask. Step 1a: section 3b's merge-or-split decision for a monorepo, section 4's choice between an app and a library when the only app signal is a framework dependency or between a language and its user when the repository depends on a parser library, and section 5's choice of the documented language when the language helper found more than one. A headless run of the step-by-step chain: the default of each step's gate (continue past the scan, accept the unit classifications, accept every composite merge, confirm every recommendation and flag every stack skill candidate, write the briefs)."
+          },
+          "default_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The documented default: 'merge' for the cohesion check, 'reference-app' for the app-or-library choice, the shape the run judged from for the language-or-user choice (after the app-or-library choice when both hold), the helper's first language for the language choice, the menu option a step-by-step gate takes ('C', or 'Y' to write the briefs)."
+          },
+          "taken_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What the run decided: 'merge' or 'split', 'reference-app' or 'library-API', the shape judged from or 'language-reference', the language the brief records, or the option a headless gate took."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "One line on why, such as the cohesion trigger that held."
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Optional decision data: the package count and the members, the languages the helper listed, or what a step-by-step gate accepted (the composites, the confirmed units, the briefs)."
+          }
+        }
+      },
+      "description": "Optional. Each auto-decision the run recorded in its sink the moment it decided, so a halt still reports the decisions taken before it. Present only when there is at least one."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. Non-fatal anomalies the run recorded in its sink or the emitter raised, one string each (for example result_file_write_failed). Present only when there is at least one."
+    }
+  }
+}