#2947 stagecraft: prepare for publication: manifest, swamp's extension checks (fmt, quality, push --dry-run), repo verification, packaged install

Get stagecraft (stagecraft/ in swamp-extensions, @swamp/stagecraft) ready to publish. Add its manifest, then run every check swamp and this repo apply to a published extension, and fix what fails until the extension is clean. A --dry-run push must succeed. Publishing itself stays in #2820, which this issue blocks.

Why

Nothing about publishing has ever run for this extension. It has deliberately had no manifest.yaml, and extensions/models/no_manifest_test.ts fails if one appears, so these have never been exercised:

• swamp's packaging and quality scoring;
• this repo's publish workflow;
• manifest-listed files;
• installing from a package.

Several pieces were built around having no manifest and need switching. The starters are embedded through deno task gen:starters because context.extensionFile() needs a manifest. The studio's built page is resolved relative to the code. The skill has only ever been linked into .claude/skills/ by hand. Doing this now, with time to iterate, is safer than discovering it on release day (target 2026-10-14).

Scope

1. Manifest. Add stagecraft/manifest.yaml, following the repo's other extensions; software-factory/manifest.yaml is the closest. Set:

   • name: "@swamp/stagecraft";
   • the version from swamp extension version (CalVer);
   • a description consistent with the README (#2819);
   • every file the extension ships: models, reports, _lib, the studio's built assets, the skill (.claude/skills/stagecraft/ with its references and examples), and anything else read at run time.

   Read swamp's manifest schema rather than guessing fields. Delete no_manifest_test.ts and the README's "not published until go-live" section.

2. Don't publish by accident. CI publishes any directory whose manifest.yaml changes on main (.forgejo/workflows/publish.yml). Decide with Seth before merging how this lands without publishing. Options:

   • keep the manifest on the branch and merge it as part of #2820;
   • merge with visibility: private, or another gate that push respects;
   • merge to a beta channel (swamp extension push --channel beta) as a deliberate pre-release.

   Say which, and don't merge a manifest to main until Seth agrees.

3. Bundled files. Switch run-time file reads to manifest-listed files where swamp offers that (context.extensionFile() and similar), and confirm the result works in source mode, packaged mode and on a remote worker. Revisit the embedded starters (_lib/engine/starters.ts, scripts/gen_starters.ts) and the studio page lookup: keep, simplify, or switch, and say why. Make sure the pieces that need a manifest now have one.

4. swamp's checks. Run each, fix what fails, and record the final output in the PR:

   • swamp extension fmt stagecraft/manifest.yaml: format and lint.
   • swamp extension quality stagecraft/manifest.yaml: score against the Swamp Club quality rubric. Raise the client-earnable factors as far as sensible, and list any factor left low and why.
   • swamp extension push stagecraft/manifest.yaml --dry-run: build the archive locally.
   • The upgrade-path check (#2696 made it skip extensions without a manifest, so it applies for the first time now) and --skip-upgrade-check semantics for a first version. A first version should need no upgrade entries; confirm that.

5. This repo's checks.

   • verification/checks.yaml's stagecraft target: check, lint, fmt, test and lockfile.
   • verify-build and verify-reviews (verification/workflow-verify.yaml), and the attestation CI validates.
   • ci.yml, and scripts/audit_deps.ts, which should scan stagecraft's lockfile (#2850; fold it in here if it's still open).
   • The adversarial-review path guard (#2583): make sure stagecraft is covered.

6. Install the package. Install the dry-run archive into a fresh swamp repo, not from source, and go from zero to a first work item:

   • init --from a starter;
   • validate;
   • start the studio and see the page;
   • start and drive a work item to its first human stop on the built-in tracker;
   • confirm the skill arrives with the extension and an agent can load it.

   Anything that only works from source is a bug to fix here.

7. Licensing and metadata. LICENSE, README, repository and homepage links, keywords and the like, whatever the registry page shows. Check how @swamp/software-factory and other @swamp extensions present on the registry.

Done when

• The --dry-run push builds cleanly.
• quality reports a score Seth has seen, with any low factors explained.
• All repo verification passes on the branch.
• The packaged extension, installed into a fresh repo, runs zero to first work item, including the studio and the skill.
• Seth has decided how the manifest lands without an accidental publish, and that's what happens.

Out of scope:

• the actual publish and announcement (#2820);
• the README content (#2819), apart from making the manifest description agree with it;
• deprecating software-factory (#2821).

Other work running in stagecraft/: #2912 (evals), #2931 (getting started), #2819 (README), #2943 (Board) and #2944 (work-item view). Rebase before the PR. A manifest change on main publishes, so coordinate the merge with Seth.