Plan: IP-98 Shared Scaffold Model Boundary

Initial Situation

IP-97 created typed baseline/artifact metadata inside packages/contract. IP-98 now asks for the actual shared scaffold model to exist only where CLI and API both need the same stable data shape. The CLI has existing catalog/runtime types, and the API app has a contract surface that can compose shared scaffold vocabulary without making packages import sibling packages.

Issue

Without a small shared model package, apps/cli and future API storage code can drift on baseline manifests, artifact metadata, pack/catalog shapes, provenance, and required-tool metadata. But extracting CLI behavior would create a bucket package and violate IP-98.

Solution Shape

Create packages/scaffold as a pure schema/type package. Move or mirror only stable scaffold-domain primitives there, then make apps/cli and apps/api consume those types/schemas. Keep packages/contract independent as the HTTP wire schema package. Leave execution, filesystem writes, terminal UI, repo detection, auth, and blob behavior in their owning apps.

Inner Skill Phases

• $grill-me: no open decision remains; Linear defines the shared/non-shared boundary.
• $parallel-research: local readonly inspection covered CLI catalog/baseline types and IP-97 contract overlap.
• $swarm-planner: single dependency chain because shared types must land before consumers.
• $tdd: package schema tests plus root validation prove the extraction.

Tasks

T1: Create pure scaffold model package

• depends_on: []
• location: packages/scaffold
• description: Add package metadata, scoped guidance, schemas/types, and focused tests for baseline manifest, artifacts, provenance, pack/catalog, and required-tool contracts.
• validation: bun run check-types --filter=@punks/scaffold, bun run test --filter=@punks/scaffold
• status: Complete
• log: Added packages/scaffold as a pure schema/type package with tests and scoped AGENTS guidance.
• files edited/created: packages/scaffold/**
• backlog_item_id: IP-115, IP-116
• assigned_skills: quality-types, tdd, simplify
• tdd_target: Shared schemas decode representative baseline/catalog/tool payloads.
• review_mode: cli

T2: Compose scaffold model from API/CLI

• depends_on: [T1]
• location: packages/contract, apps/api, apps/cli
• description: Keep packages/contract as the independent wire contract; consume @punks/scaffold from app surfaces without moving behavior.
• validation: targeted package typechecks/tests.
• status: Complete
• log: packages/contract owns baseline/artifact wire schemas directly; apps/cli consumes scaffold model types; apps/api consumes scaffold schemas at the app composition layer.
• files edited/created: packages/contract/src/schemas.ts, apps/cli/src/core/models.ts, apps/api/src/index.test.ts, package manifests
• backlog_item_id: IP-116
• assigned_skills: effect-authoring, quality-types, tdd, simplify
• tdd_target: Both apps consume @punks/scaffold; packages/contract typechecks without importing sibling package runtime models.
• review_mode: cli

T3: Review, docs-ingest-phase, validation, and Linear closeout

• depends_on: [T2]
• location: packages/scaffold, packages/contract, apps/api, apps/cli, apps/wiki, docs
• description: Run findings-first review, resolve issues, ingest wiki/domain docs, validate root, commit, and close IP-98/IP-115/IP-116.
• validation: bun run check, bun run check-types, bun run test, bun run build, git diff --check
• status: Complete
• log: Review gate completed locally with two timed-out read-only review workers and no unresolved findings. docs-ingest-phase added the shared scaffold model concept and updated the existing scaffold baseline concept.
• files edited/created: apps/wiki/specs/cli/IP-98-shared-scaffold-model/**, apps/wiki/content/docs/cli/concepts/shared-scaffold-model.md, apps/wiki/content/docs/cli/concepts/scaffold-baseline.md, apps/wiki/content/docs/cli/**, docs/README.md
• backlog_item_id: IP-98
• assigned_skills: parallel-research, simplify, improve-codebase-architecture, docs-ingest-phase, tdd
• tdd_target: Closeout evidence maps child acceptance signals to concrete files and passing validation.
• review_mode: cli

Shared Candidates

• Baseline channel and manifest metadata.
• Artifact metadata and artifact kind.
• Compatibility/provenance metadata.
• Pack/catalog entry primitives.
• Required-tool contract.

Explicitly Excluded

• CLI filesystem writing, terminal UI, repo detection, prompt rendering, local update flow, and archive extraction behavior.
• API auth, blob storage, database persistence, release publication, and artifact hosting behavior.

Unresolved Questions

None for M1. Future storage/publishing behavior belongs to later backend stories.