feat(skills)!: move machine envelope to orchestration layer (#28)

## What

Moves the machine-readable turn envelope out of the per-skill contract
and into the orchestration layer that is its only consumer.

- Removes the `## Machine envelope` section and its turn-contract
emission clause from the 14 user-facing skills that carried it:
`audit-docs, audit-pr, bump-skill, design-feature, execute-phase,
generate-docs, init-workspace, log-session, plan-feature, plan-fix,
product-audit, review-change, ship-roadmap, triage-issue`. Every turn
now ends cleanly at the closing `→ Next:` block.
- `workflow-status` is unchanged — emitting the envelope inline *is* its
function.
- `orchestration-envelope` (internal) gains the canonical
**driver-injected system-prompt snippet** and documents the **repair
loop** (parse-fail → re-invoke with `Emit only the machine envelope for
the turn above.`; one retry, then a driver-level `FAILED`).
- `docs/workflow/ORCHESTRATION.md` and
`docs/workflow/PORTABLE_PROMPT.md` mirror the snippet + repair-loop
protocol for driver authors.
- MAJOR version bump for each of the 14 skills; MINOR for
`orchestration-envelope`. `CHANGELOG.md`/`CHANGELOG.es.md` rows, README
skill/model tables refreshed, `docs/workflow/MIGRATION.md` entry added.
- `packages/agentic-workflow-schema/` (the envelope JSON schema + npm
package) is untouched — parsers keep working.

## Why

- The envelope's only consumer is an external driver/orchestrator; in
interactive chat the trailing JSON was noise.
- Weak models drop end-of-document duties — the workflow's own stated
reasoning for front-loading turn contracts — yet the envelope sat at the
very end, so weak models were penalized for a duty a static `SKILL.md`
instruction could never actually enforce or recover from.
- Enforcement now sits at the layer that reads the envelope: a driver
can detect a missing envelope and re-ask, something a skill body cannot
do for itself.

## Driver gate note

The SPEC records this as a driver-gated feature: execution should not
start until an external driver's repair loop is confirmed ready. No such
external driver exists yet for this repo (user-confirmed during
execution), so this was proceeded under `--force`, recorded in
`decisions.md` (D9). Any future driver picking up this repo must inject
the canonical snippet (from `orchestration-envelope`) and implement the
repair loop before relying on these 14 skills' output for routing.

## Evidence

- AC1–AC10 all green (see
`docs/features/10-envelope-orchestrator-only/TASKS.md` for the full
per-phase verification log).
- `npx skills add . --list` — 56 skills discovered, no malformed
frontmatter.
- `git diff --name-only origin/main...HEAD | grep
'^packages/agentic-workflow-schema/'` — no output (schema untouched).

Closes #17

Author: gtrabanco

CHANGELOG.es.md

@@ -347,16 +347,22 @@ mantiene, el techo se mueve.
 
 ## Orquestación programática
 
-Toda skill de cara al usuario termina con un **envelope máquina** — un bloque
-JSON fijo y cercado (state, unit, phase, PR, findings, blockers, orden de
-construcción de dependencias, siguiente comando recomendado + pista de tier de
-modelo). Un driver externo — un bucle de shell, CI, tu propio programa — lo
+Las skills se leen limpias en el chat interactivo — sin JSON al final. Un
+driver que quiera orquestarlas (un bucle de shell, CI, tu propio programa)
+inyecta el **snippet canónico de system-prompt** para que cada invocación
+termine con un **envelope máquina** — un bloque JSON fijo y cercado (state,
+unit, phase, PR, findings, blockers, orden de construcción de dependencias,
+siguiente comando recomendado + pista de tier de modelo) — y ejecuta un
+**bucle de reparación** cuando un turno lo omite (reintenta con un prompt de
+una línea; un reintento, luego un fallo a nivel de driver). El driver lo
 parsea e invoca la siguiente skill con el modelo que tú elijas en cada paso.
 Es la sustitución neutral de proveedor del `/loop` y los subagentes de Claude
 Code: el mismo bucle que `ship-roadmap` ejecuta dentro del agente, alojado
-fuera de cualquier agente. `workflow-status` es el sensor de solo lectura que
-reporta el árbol de dependencias completo y qué es arrancable. Protocolo,
-máquina de estados y esqueleto de driver:
+fuera de cualquier agente. `workflow-status` es la única skill que sigue
+emitiendo el envelope en línea — es un sensor de solo lectura que reporta el
+árbol de dependencias completo y qué es arrancable, así que emitirlo es toda
+su función. Protocolo, snippet, bucle de reparación, máquina de estados y
+esqueleto de driver:
 **[`docs/workflow/ORCHESTRATION.md`](docs/workflow/ORCHESTRATION.md)**. Para
 drivers JS/TS, **[`@gtrabanco/agentic-workflow-schema`](packages/agentic-workflow-schema/)**
 (npm) trae los tipos, el JSON Schema y `parseEnvelope()` implementando el

CHANGELOG.md

@@ -335,15 +335,20 @@ produce shallower judgment; the discipline holds, the ceiling moves.
 
 ## Programmatic orchestration
 
-Every user-facing skill ends with a **machine envelope** — one fixed, fenced
-JSON block (state, unit, phase, PR, findings, blockers, dependency build
-order, recommended next command + model-tier hint). An external driver — a
-shell loop, CI, your own program — parses it and invokes the next skill on
-the model you choose per step. This is the vendor-neutral replacement for
-Claude Code's `/loop` and subagents: the same loop `ship-roadmap` runs
-in-agent, hosted outside any agent. `workflow-status` is the read-only sensor
-that reports the full dependency tree and what's startable. Protocol, state
-machine, and a driver skeleton:
+The skills read cleanly in interactive chat — no trailing JSON. A driver that
+wants to orchestrate them (a shell loop, CI, your own program) injects the
+canonical **system-prompt snippet** so each invocation ends with a **machine
+envelope** — one fixed, fenced JSON block (state, unit, phase, PR, findings,
+blockers, dependency build order, recommended next command + model-tier
+hint) — and runs a **repair loop** when a turn omits it (re-ask with a
+one-line prompt; one retry, then a driver-level failure). The driver then
+parses the envelope and invokes the next skill on the model you choose per
+step. This is the vendor-neutral replacement for Claude Code's `/loop` and
+subagents: the same loop `ship-roadmap` runs in-agent, hosted outside any
+agent. `workflow-status` is the one skill that still emits the envelope
+inline — it's a read-only sensor reporting the full dependency tree and
+what's startable, so emitting it is its whole job. Protocol, snippet, repair
+loop, state machine, and a driver skeleton:
 **[`docs/workflow/ORCHESTRATION.md`](docs/workflow/ORCHESTRATION.md)**. For
 JS/TS drivers, **[`@gtrabanco/agentic-workflow-schema`](packages/agentic-workflow-schema/)**
 (npm) ships the types, the JSON Schema, and `parseEnvelope()` implementing the

README.es.md

@@ -78,7 +78,8 @@ agentic-workflow pack itself.
      frontmatter key (`generated-by: agentic-workflow/generate-docs`,
      `source-unit: <NN-slug|fix-n>`), so audit-docs can find orphans.
    - Turn contract, fixed output contract (report block + `PASS | FAIL`-style
-     decision), closing `→ Next:` block, machine envelope (last output),
+     decision), closing `→ Next:` block, machine envelope (last output;
+     superseded 2026-07-10 by feature 10 — see `docs/workflow/MIGRATION.md`),
      `## Portability` section, Allowed/Forbidden lists.
 2. `execute-phase`: at unit close-out, when a docs adapter is declared, the
    closing `→ Next:` block recommends `/generate-docs` (docs regeneration is a

README.md

@@ -222,6 +222,9 @@ Docs/skills-only change — the skills are the product here. Invariants to hold:
   `plan-feature` — `state` = `OK` (designed), `NEEDS_INPUT` (interview question
   pending), or `BLOCKED` (unresolvable capability gap). `next.recommended` =
   `/plan-feature <slug>`.
+  *(Superseded 2026-07-10 by feature 10: `design-feature` dropped its inline
+  `## Machine envelope` section; the contract moved to the orchestration
+  layer. See `docs/workflow/MIGRATION.md`.)*
 - **One-PR-per-unit, against `main`**; conventional commits.
 
 ## Design
@@ -445,8 +448,9 @@ this feature. This is the substrate later phases reference.
 contract`, `Step 0`, `Process` (raw-idea interview folded in + proportional
 research + capability-closure checklist + per-feature tooling notes + upsert +
 interaction rule + scale-down), `Guardrails`, `## Portability`, `Relationship to
-other skills`, `Done when`, `→ Next:` block, and the machine envelope. Writes the
-SPEC product half + stamps the `designed` marker.
+other skills`, `Done when`, `→ Next:` block, and the machine envelope
+*(superseded 2026-07-10 by feature 10 — see `docs/workflow/MIGRATION.md`)*.
+Writes the SPEC product half + stamps the `designed` marker.
 
 **P3 — `plan-feature` slim (MAJOR) + interview retirement + from-issue/scaffold
 alignment.** Slim the router (remove interview path; add the redirect gate on the

docs/features/01-generate-docs/SPEC.md

@@ -0,0 +1,65 @@
+# 10 — envelope-orchestrator-only · PLAN
+
+Phased implementation plan. Phases are labelled `P1, P2, …` (the executor's
+argument, e.g. `execute-phase 10 P2`). Planning is done; `P1` is the first
+implementation phase. The last phase is hardening. Opening the PR is the final
+*step* of P4, not a phase of its own.
+
+> **Execution is driver-gated.** Do not start P1 until the user confirms the
+> external opencode/Node driver ships the envelope repair loop (see SPEC
+> Dependencies + `known-issues.md`). Planning is complete regardless.
+
+## P1 — Orchestration home (the contract moves in)
+
+One concern: the orchestration layer. Add, before anything is removed from the
+skills, the canonical contract at its new home so nothing is momentarily
+homeless.
+
+- Add the canonical **driver system-prompt snippet** (fenced, verbatim) to
+  `skills/orchestration-envelope/SKILL.md`.
+- Document the **repair loop** protocol (parse-fail → re-invoke with the one-line
+  prompt) in `docs/workflow/ORCHESTRATION.md`.
+- Mirror the snippet into `docs/workflow/PORTABLE_PROMPT.md` (the prompt a driver
+  injects).
+- Note `workflow-status` stays the inline emitter (no repair loop needed for it).
+- Gate: AC4, AC5.
+
+## P2 — Strip the 14 skills
+
+One concern/layer: skills text. Uniform, mechanical, grep-checkable. Apply the
+three-deletion removal shape (SPEC → Design) to each:
+`audit-docs, audit-pr, bump-skill, design-feature, execute-phase, generate-docs,
+init-workspace, log-session, plan-feature, plan-fix, product-audit, review-change,
+ship-roadmap, triage-issue`.
+
+- Delete the `## Machine envelope` section.
+- Delete the turn-contract envelope box line(s).
+- Remove any "then the machine envelope" clause so `→ Next:` is the true last
+  output.
+- Do **not** touch `workflow-status` or `orchestration-envelope`.
+- Do **not** hand-edit `version:` here (P3 does it via bump-skill).
+- Gate: AC1, AC2, AC3.
+
+## P3 — Release metadata
+
+One concern: version/release docs.
+
+- Run `bump-skill` for the 14 stripped skills: MAJOR bump each, add rows to
+  `CHANGELOG.md` + `CHANGELOG.es.md`, refresh both README skill/model tables.
+- Add the `docs/workflow/MIGRATION.md` entry (what/where-now, per SPEC → Design).
+- Gate: AC6, AC7.
+
+## P4 — Hardening + PR
+
+Edge cases + dev-scenario failure modes, then close out.
+
+- Sweep for **dangling envelope references** across `skills/` and `docs/workflow/`
+  (AC10) — any skill still pointing at a removed section is fixed.
+- Confirm `packages/agentic-workflow-schema/` is untouched (AC8).
+- Confirm `npx skills add . --list` lists all skills (AC9).
+- Re-confirm `workflow-status` still emits (AC3) and P1's repair-loop doc reads
+  coherently end-to-end.
+- Re-run every AC command; all pass.
+- Open the PR (`gh pr create --body-file …`, body includes `Closes #17`), PRINT
+  THE PR URL, update the roadmap row to `done · [#<pr>]`, commit `docs: link PR`.
+- Gate: full AC re-run green.