Spec: Shared Scaffold Model Boundary

User Input

/goal Achieve the full M1 Monorepo Foundation Module milestone for the Devpunks Harness Intelligence project in /Users/stefan/Desktop/repos/wearedevpunks-cli.

Relevant IP-98 Linear scope:

• IP-98 extracts shared scaffold primitives only when both CLI and API need the same stable contract.
• IP-115 requires shared baseline/scaffold model candidates to be identified before extraction.
• IP-116 allows packages/scaffold only after both apps/cli and apps/api consume the same model boundary.

Context

The CLI owns scaffold execution today, but the backend/control plane will also need to understand stable baseline manifests, pack/catalog metadata, compatibility/channel metadata, provenance, and required-tool contracts. The shared model must prevent duplicate schema drift while keeping behavior in the owning apps.

Non-Goals

• Moving CLI filesystem writing, terminal UI, repo scanning, prompts, or local update logic into a package.
• Moving API auth, blob storage, persistence, or release publication behavior into a scaffold package.
• Creating a generic scaffold utility bucket.
• Rewriting existing catalog data.

Acceptance Criteria

• Shared baseline/scaffold model candidates are listed in spec/implementation artifacts.
• CLI-only filesystem, terminal, and repo-scanning behavior is explicitly excluded.
• API-only auth and blob behavior is explicitly excluded.
• packages/scaffold exists only as a stable schema/type package.
• Both apps/cli and apps/api consume @punks/scaffold.
• Package-to-package runtime imports are avoided for this boundary; app surfaces compose @punks/contract and @punks/scaffold.
• packages/scaffold imports no sibling app or package runtime code.
• The shared package exports baseline manifest, artifact metadata, channel, provenance, pack/catalog, and required-tool schemas/types.
• packages/contract owns its wire-level HTTP API schemas independently of packages/scaffold.
• Root validation passes after extraction.

Constraints

• Prefer the smallest package boundary that removes real cross-app duplication.
• Keep prompt/spec resolution logic in this repo.
• Do not leak consumer-repo business logic into the CLI or shared package.
• Keep app behavior owned by apps; shared package owns only stable data contracts.

Technical Notes

• IP-97 introduced packages/contract with baseline and artifact metadata shapes. Those shapes overlap conceptually with IP-98's shared scaffold model, but the package boundary keeps the HTTP wire contract independent; app surfaces reconcile the matching literals where needed.
• Existing CLI catalog and baseline runtime types live under apps/cli/src/core and apps/cli/src/data/catalog.
• API consumption can remain shape-level in M1; backend storage behavior is still deferred.

Decision Log