Skip to content

refactor(migrate): rename DSL _kind 'checkpoint' → 'sidebar' - #162

Merged
icarthick merged 1 commit into
awslabs:mainfrom
icarthick:refactor/kind-checkpoint-to-sidebar
Jul 20, 2026
Merged

refactor(migrate): rename DSL _kind 'checkpoint' → 'sidebar'#162
icarthick merged 1 commit into
awslabs:mainfrom
icarthick:refactor/kind-checkpoint-to-sidebar

Conversation

@icarthick

Copy link
Copy Markdown
Collaborator

Summary

Pure concept rename, no behavior change: the DSL phase kind _kind: checkpoint becomes _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 becomes current_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)

  • Validator (tools/frontmatter-validator/{parse,types,check}.ts): the _kind role value and all error-message strings checkpoint → sidebar. _kind: checkpoint without a parser change would silently parse as backbone and fail — so this is a lockstep grammar-vocabulary change. Test suite (frontmatter-validator.test.ts) updated — 57 tests pass.
  • All 18 _kind: checkpoint frontmatter declarations → sidebar across every skill (heroku, vercel, gcp, agent-advisor, shared).
  • Construct prose checkpoint → sidebar in canonical INTERPRETER.md, workshop-invariants.md, phase-status.schema.json (doc string), and per-skill files. Vendored copies re-synced byte-identical (shared:check OK across 4 trees).

Protected — NOT renamed (external/unrelated terms)

Deliberately skipped 5 files whose "checkpoint" is not the DSL construct:

  • LangGraph checkpointerretarget-gotchas.md, clarify-ai.md
  • Temporal "checkpoint business state"decision-refs/temporal.md
  • "Go/No-Go checkpoint" PM milestones — migration-complexity.md, generate-infra.md

Deferred to follow-ups (intentionally out of scope)workshopwhat-ifphase rename (phase id, dirs,phases.workshop` state key, fixtures)

  • estimation_summary.workshop metadata field rename
  • Tier 2 — structural _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 build green — 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.

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).
@icarthick
icarthick requested a review from a team as a code owner July 20, 2026 20:06
@icarthick
icarthick merged commit 79219eb into awslabs:main Jul 20, 2026
8 checks passed
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.
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant