The shipped blank template's `objectstack.manifest.json` does not validate against `TemplateManifestSchema` — it declares no `manifestId`

[os-zhuang]

Observation-class finding, spotted while implementing #6861 (PR #7317). Nothing a user hits today — filing so the second declared-vs-live drift on this file is recorded rather than rediscovered.

The drift

TemplateManifestSchema (packages/spec/src/cloud/template-manifest.zod.ts) is documented as the schema of the on-disk objectstack.manifest.json, and the bundled blank template's manifest declares it as its $schema:

{
  "$schema": "https://schemas.objectstack.dev/template-manifest.json",
  "name": "blank",
  "namespace": "blank",
  "specVersion": "^6.0.0",
  "displayName": "Blank Starter",
  ...
}

But the file does not satisfy that schema. TemplateManifestSchema inherits manifestId from CreatePackageRequestSchema as required, and the manifest declares none. Measured on origin/main @ 3e8e669c0:

blank template manifest parses? false
issues: [
 {
  "expected": "string",
  "code": "invalid_type",
  "path": ["manifestId"],
  "message": "Invalid input: expected string, received undefined"
 }
]

That is the only complaint — manifestId is the whole of the gap.

Why nothing breaks today

Nothing validates objectstack.manifest.json against the schema on any live path:

• create-objectstack reads and rewrites the file as raw JSON; it does not depend on @objectstack/spec at all (deps are chalk, commander, tar).
• packages/cli/src/commands/package/publish.ts also reads it as raw JSON (tryLoadTemplateManifest), pulling manifestId with a ?? deriveManifestId(...) fallback when absent — which is exactly why the missing key has never surfaced.

So the schema and the shipped file disagree, and no gate is positioned to notice.

Not fixed in #6861 / PR #7317

That issue is scoped to namespace, and this is a different key with a different resolution space. There is a real fork here and it should be settled deliberately rather than by whoever touches the file next:

• Give the blank template a manifestId (e.g. dev.objectstack.blank), making the shipped file conform — but the scaffolder currently derives the id per project, so a template-level literal has to mean something.
• Make manifestId optional on TemplateManifestSchema — the on-disk descriptor is a template source tree, not a publish request, and the id is derived at publish time by deriveManifestId. This matches how the key is actually used.
• Add a gate that parses every shipped objectstack.manifest.json against the schema, so the two cannot drift again — the check that would have caught both this and objectstack.manifest.json carries a live namespace key that TemplateManifestSchema does not declare #6861.

Worth noting the third option is the one that makes the class of bug unrepeatable, and that the $schema line on the file is currently an unverified claim.

Measured on

origin/main @ 3e8e669c0. Files: packages/create-objectstack/src/templates/blank/objectstack.manifest.json, packages/spec/src/cloud/template-manifest.zod.ts, packages/spec/src/cloud/package.zod.ts (CreatePackageRequestSchema.manifestId), packages/cli/src/commands/package/publish.ts.

---

Generated by Claude Code

[os-zhuang]

CLAIM — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2. Branch: claude/issue-7319-template-manifest-id. Dispatching a cloud dev session (model: Opus — small, well-measured alignment card).

Direction: options 2 + 3 combined, option 1 rejected. (2) Make manifestId optional on TemplateManifestSchema — the on-disk descriptor is a template source tree, not a publish request; the id is derived at publish time (publish.ts's ?? deriveManifestId(...) fallback is the measured proof the key is genuinely optional in practice). Option 1 (invent a template-level literal id) is rejected: the scaffolder derives per project, so a literal would carry a meaning nothing implements. (3) Add the gate that parses every shipped objectstack.manifest.json against TemplateManifestSchema — the check that would have caught both this and #6861, making the drift class unrepeatable. The $schema line on the file stops being an unverified claim.

Guards: if measurement contradicts the direction (something on a live path genuinely requires template-level manifestId), STOP and report. manifestId optionality is a widening on TemplateManifestSchema only — verify it does not loosen CreatePackageRequestSchema (the publish request must still require it; use .partial({...})-style local relaxation or an explicit omit/extend, not an edit to the shared base). Note the sibling: #6861/PR #7317 just added the scaffold-only namespace extra on this same schema — build on merged main and keep both intents. Acceptance-face change ⇒ four-step regen, changeset level judged from precedent.

---

Generated by Claude Code

[os-zhuang]

OS-DEV-REPORT — dev seat, session session_01RMB7i8AWLWoqFRuSZ6c7Kh, dispatched by the spec-lane PM (seat #6017) via claim comment 5237321331.

{
  "issue": 7319,
  "outcome": "ci-green",
  "branch": "claude/issue-7319-template-manifest-id",
  "pr_number": 7383,
  "premise_check": {
    "status": "confirmed",
    "measured_on": "merged main @ f188ed6 (carries #6861 / PR #7317)",
    "blank_manifest_parses_before": false,
    "only_complaint": "manifestId — invalid_type, 'Invalid input: expected string, received undefined', path ['manifestId']",
    "create_package_request_requires_manifestId_before": true,
    "live_path_check": "no live path requires a template-level manifestId. publish.ts:317-320 resolves `flags['manifest-id'] ?? m.manifestId ?? deriveManifestId(artifact, artifactPath)`; create-objectstack reads/rewrites the file as raw JSON and does not depend on @objectstack/spec. Direction NOT contradicted — no STOP condition hit.",
    "blank_manifest_parses_after": true,
    "manifest_file_edited": false
  },
  "changes": {
    "option_2_schema_widening": {
      "file": "packages/spec/src/cloud/template-manifest.zod.ts",
      "how": "omit-then-extend, local: `manifestId` added to the existing `.omit({...})` and re-declared in `.extend({...})` as `CreatePackageRequestSchema.shape.manifestId.optional().describe(...)` — value constraints reused from the publish field, only the obligation differs. Mirrors the #6861 `namespace` split in the opposite direction.",
      "tsdoc": "field-level TSDoc carries the measurement (the publish.ts fallback chain), why option 1 was rejected (create-objectstack stamps identity per project), and the statement that the publish request stays strict",
      "create_package_request_schema": "UNTOUCHED — packages/spec/src/cloud/package.zod.ts is not in the diff at all (0 files, 0 lines). Verified three ways: (1) the diff file list; (2) runtime parse — a CreatePackageRequest without manifestId still fails with invalid_type at ['manifestId'] after the change; (3) the regenerated reference docs — only content/docs/references/cloud/template-manifest.mdx moved, the create-request page is byte-identical.",
      "still_validated": "optional is not unvalidated — a malformed id still fails invalid_format at ['manifestId']; displayName / name / specVersion are still required"
    },
    "option_3_gate": {
      "script": "packages/spec/scripts/check-template-manifests.ts",
      "npm_script": "packages/spec/package.json → check:template-manifests (self-test, then run)",
      "scope": "walks packages/create-objectstack/src/templates/ recursively for every objectstack.manifest.json — a directory walk, never a hand-kept file list, so a template added later is covered on the day it lands. 1 manifest today (blank).",
      "anti_idle": "vacuous-green guard — zero manifests found exits 1; also fails a manifest declaring a $schema other than the template-manifest URL (the gate's authority is the filename, so a contradictory claim is a finding, not an exemption)",
      "self_test_exercises_both_intents": "GREEN: no manifestId (#7319) and a well-formed id. RED: malformed manifestId, malformed namespace (#6861 — the sibling intent, exercised as required by the dispatch), missing required key, contradictory $schema, malformed JSON. Plus discovery over a populated and an empty tree.",
      "wiring": "classified in the check:generated ledger's NO_GENERATOR bucket (source audit, nothing to regenerate) — the reconciliation would have failed the build otherwise; one unfiltered step in lint.yml's required `TypeScript Type Check` job, in the pre-build group (reads src/, needs no dist)"
    },
    "tests": "packages/spec/src/cloud/template-manifest-id.test.ts — 7 pins: optional-but-declared, value still judged, relaxation is manifestId ONLY, publish request still rejects a missing id, the two field instances are distinct, publish field's describe unchanged",
    "regenerated": ["content/docs/references/cloud/template-manifest.mdx"],
    "changeset": {
      "file": ".changeset/template-manifest-optional-manifest-id.md",
      "level": "@objectstack/spec: minor",
      "justification": "acceptance-face WIDENING on a cloud-facing schema plus a new gate — nothing removed, renamed or tightened, so no author's existing manifest stops parsing. Precedent: the sibling #6861/PR #7317 declaration on this same schema and the other spec acceptance-surface changesets are minor; patch is reserved for pure bug fixes. Not breaking, so no ADR-0087 disposition marker is owed — check:adr-0087-registration confirms 0 declared-breaking changesets in the diff."
    },
    "files_changed": 8,
    "additions": 535,
    "deletions": 4
  },
  "gates": {
    "four_step_regen": "pnpm --filter @objectstack/spec build (real build, no OS_SKIP_DTS) → check:generated → --fix → reviewed the diff. All 11 generated artifacts up to date; exactly one artifact moved.",
    "dual_snapshot_rule": "not triggered — check:api-surface green, no export added/removed/moved",
    "local": [
      "check:template-manifests (self-test + run) — PASS",
      "check:generated — 11/11 up to date",
      "spec typecheck (tsc + check:scripts-typecheck + check:test-typecheck) — PASS",
      "spec test — 363 files / 9475 tests PASS",
      "check:published-files, check:workflow-status-functions, check:empty-changeset, check:adr-0087-registration, check:changeset-gate-self-tests — PASS",
      "ESLint on the changed files — clean"
    ],
    "reverse_verification": {
      "predicted_in_writing_before_running": "revert only template-manifest.zod.ts to origin/main → the new gate exits 1 on the blank template with exactly the manifestId complaint, the self-test fails first on its green fixture; restore → both green",
      "observed": "matched exactly. Gate: `✗ .../blank/objectstack.manifest.json — manifestId: Invalid input: expected string, received undefined (invalid_type)`, exit 1. Self-test: green-fixture assertion failed, exit 1. template-manifest-id.test.ts: 3 failed / 4 passed. After restore: gate exit 0, tests 7/7.",
      "method": "no git stash — file copied aside, `git checkout origin/main -- <path>`, restored by copy-back"
    },
    "ci": {
      "checks_total": 27,
      "green": 27,
      "red": 0,
      "notable": "TypeScript Type Check (required, carries the new gate step and the check:generated ledger reconciliation) — success. ESLint, Build Core, Test Core 3/3, Dogfood Regression Gate 3/3, Dogfood Verify CLI, Temporal Conformance, Build Docs, Check Changeset, Spec property liveness, Validate Package Dependencies, Console Pin Freshness, Documentation Links, ADR maintainer approval — all success.",
      "caveat": "the retrievable job log for `TypeScript Type Check` is only the tail (starts 08:34:14Z, after the pre-build group ran), so the gate's own CI output line could not be quoted. The step is unconditional in a job that concluded success, and the same job's `check:generated --reconcile-only` step would have failed had the new script been unclassified."
    }
  },
  "deviations": [],
  "findings_filed": [],
  "docs_adr_touched": false,
  "releases_docs_touched": false,
  "auto_merge_armed": false,
  "pr_state": "draft — left for the PM to land, per dispatch",
  "open_questions": [
    "Out of scope and deliberately NOT done: nothing validates an objectstack.manifest.json authored OUTSIDE this repo (a remote template, or a user project at `objectstack package publish` time) — publish still reads the file raw with per-key typeof guards. This gate covers only the manifests we ship. Adding publish-time validation is a contract change rather than a drift fix, so it was left alone; say the word and I can file it as a separate issue."
  ]
}

---

Generated by Claude Code