Skip to Content

← All archived runs

Run: remove-categories-section

run.md

Run: remove-categories-section

  • branch: claude/pipeline-remove-categories-section-h9a3oc
  • pr: #614

00_intake/stub.md

Stub: Remove the categories blueprint section

  • feature-slug: remove-categories-section
  • epic: onboarding-blueprint-alignment
  • personas: Admin, Vendor
  • initiative: Build the Bridge / objective: Q2-2026 O1 — Establish Product-Market Fit with Vendor Partners
  • depends-on: none
  • sequence: 1 of 6

Problem

The onboarding blueprint drafts a categories section, but there is no Category model anywhere on the platform — its commit step has no target and is silently ignored. It generates confusing, uncommittable datapoints and pollutes the review panel. This is a core case of the "useless datapoints that don't make sense" the user hit in testing.

Proposed change

Remove categories as a first-class blueprint section end-to-end: drop it from the section vocabulary (ONBOARDING_SECTION_KEYS), the extraction contract (DraftBlueprintSchema), the system prompt's section list and interview flow, the commit switch, and the review-panel section metadata / editable fields. Ensure blueprints that already carry a stored categories section degrade gracefully (ignored / hidden, not a hard error).

Acceptance criteria (rough)

  • categories is gone from the blueprint section vocabulary and the extraction contract.
  • The concierge prompt no longer references categories as a section to draft.
  • analyse_source and draft_section can no longer produce a categories section.
  • The review panel shows no categories section, and commit no longer has a categories branch.
  • A tenant with a pre-existing categories section in a stored blueprint still loads and commits without error.

Out of scope (this feature)

  • Any change to the products / services / skills / SLA / settings / profile shapes (other stubs).
  • A data migration to strip categories from historical blueprint documents (safe to leave; ignored).

Notes for Define

  • Foundation for the epic — every other section-alignment stub builds on the corrected vocabulary, so ship this first.
  • touches: packages/services/src/db/models/onboarding-blueprint.ts (ONBOARDING_SECTION_KEYS), packages/services/src/ai/onboarding/{contract.ts,prompt.ts,analyse-source.ts,blueprint-tools.ts}, packages/services/src/db/services/onboarding-blueprint/commit.ts (the categories no-op branch, documented at its top), apps/web/components/onboarding/types.ts (SECTION_META, COLLECTION_LABELS).

01_define/output/spec.md

Spec: Remove the categories blueprint section

  • slug: remove-categories-section
  • personas: Admin, Vendor
  • touches: packages/services/src/db/models/onboarding-blueprint.ts, packages/services/src/ai/onboarding/{contract.ts,prompt.ts,analyse-source.ts,blueprint-tools.ts}, packages/services/src/db/services/onboarding-blueprint/commit.ts, apps/web/components/onboarding/types.ts
  • complexity: standard

Problem

The onboarding blueprint drafts a categories section, but no Category model exists anywhere on the platform — its commit step has no target and is silently ignored. It generates confusing, uncommittable datapoints and pollutes the review panel, a core case of the "useless datapoints that don't make sense" surfaced in testing. This is the foundation stub for the onboarding-blueprint-alignment epic under Build the Bridge / Q2-2026 O1 — Establish Product-Market Fit with Vendor Partners: every other section-alignment stub builds on the corrected section vocabulary, so the blueprint must stop offering a section it cannot commit before the rest of the epic proceeds.

Proposed change

Remove categories as a first-class blueprint section end-to-end:

  • Drop it from the section vocabulary (ONBOARDING_SECTION_KEYS).
  • Drop it from the extraction contract (DraftBlueprintSchema in contract.ts).
  • Remove it from the concierge system prompt's section list and interview flow (prompt.ts), the source-analysis section list (analyse-source.ts), and the completion-tool section list (blueprint-tools.ts, which currently names "all seven sections").
  • Remove the categories no-op branch from the commit switch (commit.ts).
  • Remove it from the review-panel section metadata / editable fields (SECTION_META, COLLECTION_LABELS in apps/web/components/onboarding/types.ts).

Blueprints that already carry a stored categories section must degrade gracefully — ignored / hidden, not a hard error — so existing tenants keep loading and committing.

Acceptance criteria

  • categories is removed from ONBOARDING_SECTION_KEYS and from the DraftBlueprintSchema extraction contract; the blueprint section vocabulary now lists six sections.
  • The concierge system prompt (prompt.ts), source analysis (analyse-source.ts), and the completion tool description (blueprint-tools.ts) no longer reference categories as a section to draft, and reference six sections rather than seven.
  • analyse_source and draft_section can no longer produce a categories section.
  • The review panel renders no categories section and exposes no categories editable fields; the commit switch has no categories branch.
  • A tenant with a pre-existing categories section in a stored blueprint still loads in the review panel and commits without error (the stored section is ignored / hidden, not a hard failure).

Out of scope

  • Any change to the products / services / skills / SLA / settings / profile section shapes (other stubs in this epic).
  • A data migration to strip categories from historical blueprint documents — safe to leave; stored categories sections are ignored rather than removed.

Open questions

  • none

02_build/output/notes.md

Build notes: remove-categories-section

  • commits: feat: remove-categories-section — drop categories from blueprint vocabulary end-to-end

What changed

  • packages/services/src/db/models/onboarding-blueprint.ts: dropped "categories" from ONBOARDING_SECTION_KEYS (now six sections). Reworked the doc comment to explain the removal and the ignore-legacy-section behaviour. This narrows OnboardingSectionKey and the schema enum for both the section and commit-item key.
  • packages/services/src/ai/onboarding/contract.ts: removed the categories field from DraftBlueprintSchema — the satisfies Record<OnboardingSectionKey, …> keeps it in lockstep with the model, so extraction can no longer produce a categories section.
  • packages/services/src/ai/onboarding/prompt.ts: concierge prompt now lists six sections in order, categories removed, and the "seven sections" phrasing updated to six.
  • packages/services/src/ai/onboarding/analyse-source.ts: source-analysis system prompt drops the categories bullet and says six sections.
  • packages/services/src/ai/onboarding/blueprint-tools.ts: mark_blueprint_complete description lists the six sections (categories removed). draft_section/analyse_source already key off ONBOARDING_SECTION_KEYS, so they now reject/omit categories automatically.
  • packages/services/src/db/services/onboarding-blueprint/commit.ts: doc comment updated — the commit reads only known section keys, so a stored legacy categories section is never looked up and is ignored (there was no runtime categories branch to remove).
  • apps/web/components/onboarding/types.ts: dropped "categories" from the client ONBOARDING_SECTION_KEYS, removed the SECTION_META.categories entry, and dropped the now-unused FolderTree import. The review panel iterates SECTION_ORDER/SECTION_META, so no categories section or editable fields render.
  • apps/web/lib/onboarding/serialize.ts: serializeBlueprint now filters out sections whose key is no longer in the vocabulary, so a legacy categories section on an older blueprint is dropped at the serialize boundary — it neither renders nor counts toward the panel's review-progress totals.

Acceptance criteria status

  • categories removed from ONBOARDING_SECTION_KEYS and DraftBlueprintSchema — vocabulary is now six sections (model + contract).
  • Concierge prompt, source analysis, and completion-tool description no longer reference categories and say six sections rather than seven.
  • analyse_source and draft_section can no longer produce a categories section — both derive from ONBOARDING_SECTION_KEYS / DraftBlueprintSchema, which no longer include it.
  • The review panel renders no categories section and no categories editable fields; the commit switch has no categories branch (it reads only known keys).
  • A tenant with a pre-existing stored categories section still loads (filtered out at serialization → hidden) and commits (unknown key never looked up; the status/commit-record $set does not re-validate the sections array) without error.

Verify result

  • mechanical checks (format · lint · typecheck · build) run in CI + the Vercel preview, not here. Release reads them back from the PR's check runs. No check is expected to fail.

Notes for review

  • Graceful degradation is achieved without a data migration (per spec Out of scope): stored categories sections are ignored at three points — extraction can't create them, the commit only reads known keys, and serialization filters them before the client sees them.
  • The Mongoose section/commit-item key enums lose categories. This is safe for existing documents: enum validation runs on write, not read, and the only writes to a stored categories section's array would come through upsertSection (targeted $ update, validators scoped to the touched path) — the commit's status advance is a $set on status/commitRecord that never touches sections.
  • apps/demo keeps its own separate mock onboarding vocabulary (out of scope for this run).

03_release/output/changelog.md

Changelog: remove-categories-section

Published as apps/help/app/changelog/2026-07-08-remove-categories-section/page.mdx.

Benefit copy

When you set up a new workspace, the setup assistant no longer drafts a "categories" section — a step that never connected to anything and only added items you couldn't actually use.

  • You now move through six focused sections instead of seven, so there's less to review before you launch.
  • Nothing the assistant drafts is a dead end anymore — every item you approve lands in your real workspace.
  • Existing workspaces are unaffected: any categories drafted earlier are simply set aside, not shown.

03_release/output/investor-update.md

Vendor onboarding drops a dead-end setup step

Who it's for: Admins and vendors setting up a new workspace What shipped: The onboarding assistant no longer drafts a categories section that could never be committed. Why it matters: A cleaner, less confusing first-run setup — advancing product-market fit with vendor partners.

It removes the kind of useless datapoints first flagged in vendor testing.

Dig deeper: <merged-PR URL> · <changelog entry URL>

03_release/output/release.md

Release: remove-categories-section

  • pr: https://github.com/sustentus/sustentus/pull/614 · merged: yes — 2026-07-08 (squash)
  • CI: green — Quality Project, preview DB migration, DB audit all passed; Claude "Review diff against CONVENTIONS.md" action skipped (not enabled), so /code-review medium was run inline instead.
  • technical docs: updated apps/docs/app/technical/packages/services/page.mdx — "seven blueprint sections" → "six".
  • business docs: no business docs impact — platform-overview already summarises the blueprint as "(profile, catalogue, skills, SLAs, settings)" and never listed categories; no other business page names the section vocabulary.
  • release notes: both — changelog entry (apps/help/app/changelog/2026-07-08-remove-categories-section/)
    • investor draft in this PR.
  • deploy: READY (web, help) — confirmed via poll-deploy after merge.
  • sent: investor update sent after green deploy (see close-out).

Review summary

  • /code-review medium on the branch diff — findings summarised against the acceptance criteria; no correctness issues. Graceful-degradation path (stored legacy categories section) verified at three points: extraction can't recreate it, the commit reads only known keys, and serialization filters it before the client renders. No cleanup/dead code surfaced.

Acceptance check (vs spec)

  • categories removed from ONBOARDING_SECTION_KEYS + DraftBlueprintSchema — model + contract, six sections.
  • Concierge prompt, source analysis, completion-tool description no longer reference categories; say six sections.
  • analyse_source / draft_section can't produce a categories section — both derive from the trimmed vocabulary / schema.
  • Review panel renders no categories section or fields; commit switch reads only known keys.
  • A stored legacy categories section still loads (filtered at serialization) and commits (never looked up; status $set doesn't re-validate sections) without error.