refactor(migrate): rename DSL _kind 'checkpoint' → 'sidebar' - #162
Merged
icarthick merged 1 commit intoJul 20, 2026
Merged
Conversation
Pure concept rename, no behavior change. 'sidebar' better captures the construct: an OPTIONAL phase that hangs OFF the backbone (entered by its _trigger, returns control, never becomes current_phase) — 'checkpoint' misleadingly implies a mandatory inline gate you pass through. - Validator (parse.ts/types.ts/check.ts): _kind role value + all error messages checkpoint -> sidebar; frontmatter-validator.test.ts updated (57 tests pass). - All 18 _kind: checkpoint frontmatter declarations -> sidebar across every skill. - Construct prose 'checkpoint' -> 'sidebar' in canonical INTERPRETER.md, workshop-invariants.md, phase-status.schema.json + per-skill files; vendored copies re-synced byte-identical (shared:check OK, 4 trees). - PROTECTED (NOT renamed — external/unrelated terms): LangGraph checkpointer (retarget-gotchas.md, clarify-ai.md), Temporal 'checkpoint business state' (temporal.md), 'Go/No-Go checkpoint' PM milestones (migration-complexity.md, generate-infra.md). Deferred to follow-ups: workshop->what-if phase rename; estimation_summary.workshop metadata field; and the Tier-2 structural _gates grammar (making the sidebar's 'hold the successor until resolved' declarative + validator-enforced). Full 'mise run build' green (validator, node --test, dprint, markdownlint, shared:check, security scanners).
This was referenced Jul 20, 2026
10 tasks
icarthick
added a commit
to herosjourney/startups
that referenced
this pull request
Jul 22, 2026
Resolves conflicts after the whole workshop stack + awslabs#162 sidebar rename landed: - heroku-to-aws SKILL.md + heroku-live-capture/README.md: took main's version (this branch's stale awslabs#148-lineage copies; a GCP PR shouldn't alter merged heroku content — main has the newer workshop/what-if + Scenario C content). - migrate/README.md + plugin README: UNION — kept main's vercel/agent-advisor requirements AND this branch's GCP live-discovery additions (gcloud requirement lines, 'Live GCP discovery — how it works' subsection, gcloud/heroku input source). Full build to follow.
icarthick
added a commit
to herosjourney/startups
that referenced
this pull request
Jul 22, 2026
Resolves conflicts after the workshop stack + awslabs#149/awslabs#151/awslabs#155/awslabs#162 landed: - heroku-to-aws SKILL.md + heroku-live-capture/README.md: took main (stale awslabs#148/awslabs#150 lineage; main has the merged workshop/what-if + Scenario C content). - gcp-live-capture/README.md: kept THIS branch's added 'Scenario C — derived GCP baseline' block (its genuine new content; main's side empty there). - migrate/README.md: took main (adds vercel + agent-advisor reqs; awslabs#149's gcloud GCP requirement lines already present above the conflict). New gcp-infra-pricing-cache.md auto-enrolls in pricing:staleness (6/6 fresh) and the seed-baseline fixtures pass fixtures:check (141 json / 10 asserters). Full build green.
5 tasks
icarthick
added a commit
that referenced
this pull request
Jul 23, 2026
Per product decision, remove the vercel-to-aws migration skill entirely. This is a forward-removal (not a git-revert): vercel landed via shared/cross-skill commits (#153/#157/#162/#155/#152/#176) that also carried heroku/gcp/sidebar work, so reverting those merge commits was not viable. Removed: - skills/vercel-to-aws/ (full skill, 57 files incl. its references/vendored/ copies) - fixtures/vercel-capture/ + fixtures/vercel-workshop/ (replay fixture sets) - Orphaned vercel report validator + its test + golden fixtures (lived at plugin level, not under the skill dir): scripts/validate-assessment-report.py, tests/test_validate_assessment_report.py, fixtures/assessment-report-{reference,stub}.html, fixtures/tier1-signals-reference.json (vercel prescan fixture, no consumers) - Deregistered from all 3 plugin manifests (.claude/.codex/.cursor-plugin): dropped vercel/next-js/nextjs/opennext keywords, the 'Vercel' mentions in descriptions, and the codex 'Assess my Vercel migration' example prompt - Stripped vercel from both READMEs (intro bullets, triggers, Vercel→AWS mapping table, trigger-table row, requirement bullet, DSL-architecture section: 'five skills'→'four', removed the resumability-ledger note) + fixtures/README registry line - Dropped vercel asserter entries from tools/run-asserters.py (10→6 asserters) - Stripped stale vercel cross-refs: heroku SKILL.md workshop-arch note, gcp schema-workshop-scenarios arch-defaults line, canonical workshop-invariants {SKILL_LABEL}/{INVENTORY} placeholders (shared:sync propagated to vendored copies) PRESERVED (heroku + gcp depend on these — #157's shared architecture): canonical skills/shared/workshop/workshop-invariants.md + skills/shared/estimate/pricing-mode.md and their heroku/gcp vendored copies. shared:check drops 4→3 trees cleanly (the sync tool auto-discovers consumers). Left legit non-skill refs: gcp's vercel.json detection signal, 'Vercel AI SDK' framework name, historical PR-context notes. Verified: shared:check OK (3 trees byte-identical), fixtures:assert 6/6, all validators green (heroku/gcp/agent-advisor), dprint + markdownlint clean, full mise run build green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Pure concept rename, no behavior change: the DSL phase kind
_kind: checkpointbecomes_kind: sidebar.Why. "checkpoint" misleadingly implies a mandatory inline gate you pass through (its meaning in git/CI/DBs). The construct is the opposite: an optional phase that hangs OFF the backbone — entered only by its
_trigger, returns control instead of advancing, never becomescurrent_phase. "sidebar" captures that step-off-and-return nature, and reads cleanly against_kind: backbone. It also matches the "side-visit" language the interpreter contract already uses to explain the construct.Changes (46 files, +239/−239 — symmetric, pure rename)
tools/frontmatter-validator/{parse,types,check}.ts): the_kindrole value and all error-message stringscheckpoint → sidebar._kind: checkpointwithout a parser change would silently parse asbackboneand fail — so this is a lockstep grammar-vocabulary change. Test suite (frontmatter-validator.test.ts) updated — 57 tests pass._kind: checkpointfrontmatter declarations →sidebaracross every skill (heroku, vercel, gcp, agent-advisor, shared).checkpoint → sidebarin canonicalINTERPRETER.md,workshop-invariants.md,phase-status.schema.json(doc string), and per-skill files. Vendored copies re-synced byte-identical (shared:checkOK across 4 trees).Protected — NOT renamed (external/unrelated terms)
Deliberately skipped 5 files whose "checkpoint" is not the DSL construct:
checkpointer—retarget-gotchas.md,clarify-ai.mddecision-refs/temporal.mdmigration-complexity.md,generate-infra.mdDeferred to follow-ups (intentionally out of scope)workshop
→what-ifphase rename (phase id, dirs,phases.workshop` state key, fixtures)estimation_summary.workshopmetadata field rename_gates: make the sidebar's "hold the backbone successor until it resolves" declarative + validator-enforced (today it lives in interpreter prose). That's where the real capability win is; this PR is vocabulary only.Test plan
mise run buildgreen — frontmatter validator (all skills),node --test(57 pass), dprint fmt:check, markdownlint,shared:check(4 vendored trees byte-identical), security scanners.Note for reviewers
This is a plugin-wide vocabulary change, so it touches
**/SKILL.md(→@startups-admins) and the agent-advisor / llm-to-bedrock skills. The diff is mechanical and symmetric (+239/−239); no logic changes.