[herosjourney]

Problem

Teams that only want to assess an AI workload for a move to Amazon Bedrock currently have no public skill for that. The assessment, design, cost-estimate, and generation-planning logic for OpenAI, Anthropic, Gemini/Vertex AI, OpenRouter, and agentic workloads lives inside gcp-to-aws, so it is only reachable as part of a GCP migration. The existing llm-to-bedrock skill is the wrong fit for that need because it rewrites application code and evaluates output; it does not produce a standalone assessment. This also leaves the neutral AI logic without a single owner, which blocks later stages of issue #389.

Fix

This PR adds a new public skill, bedrock-migration-assessment, that runs the provider-neutral Discover, Clarify, Design, Estimate, and optional Generate-support-artifacts workflow on its own. It identifies AI call sites and provider/gateway/model provenance, captures permitted usage data, recommends Bedrock targets and regions, estimates cost, records decisions, and can generate migration-support artifacts. It does not rewrite application source; llm-to-bedrock remains the execution skill for SDK/code rewrites, output evaluation, and ready-to-merge delivery.

gcp-to-aws now delegates its AI track to the new skill through a route-sensitive bootstrap:

• Pure-infrastructure GCP runs never touch bedrock-migration-assessment; they do not stat, resolve, or load it.
• Runs with AI evidence (provider SDK import or dependency, AI endpoint host, provider env var name, model identifier, explicit provider intent, Vertex-strong IaC, or a durable AI route) require the exact installed sibling skill and preflight its full 66-entry closure before any state or artifact changes. Source files without AI evidence stay GCP-only and never require the sibling; SOURCE_CONTAINING is informational. A missing or tampered sibling fails closed with BEDROCK_MIGRATION_ASSESSMENT_SIBLING_MISSING or BMA_STANDALONE_CLOSURE_INVALID rather than silently degrading.
• gcp-to-aws keeps GCP infrastructure, live, and billing discovery, Vertex-specific adaptation, BigQuery handling, telemetry, outer run state, combined preferences, and combined report assembly.

Input contract. BMA's only AI input is the #415 ai-workload-profile.json contract (scripts/contracts/ai-workload-profile.schema.json, vendored byte-identically into the closure). Legacy GCP-shaped input is rejected by name (BmaLegacyProfileRejected). In delegated GCP runs, a deterministic adapter (gcp-ai-profile-adapter.py) converts GCP's legacy profile at the GCP boundary into a #415 document plus a temporary sidecar, written to a hidden .bma-input/ location; GCP's public ai-workload-profile.json keeps its legacy shape and name. The sidecar carries the fields #415 has no slot for (workloads, agentic profile, tool manifest, observed cost, integration context, per-model usage, Terraform AI resources) and is explicitly temporary pending a #415 schema-version follow-up that folds them in. Artifact names, routes, state transitions, and ownership boundaries are unchanged for every existing GCP route; AI design and estimate content for GCP runs does change where noted under "Changes since first review" below. The PR 449 target-only estimation-ai/generation-ai contracts keep their shared plus fixture_only:true activation. New safety behavior that reviewers should know about:

• The report-contribution contract is closed. Script and style tags, raw HTML wrappers, ATX and Setext headings, HTML anchors, embedded Markdown links, and contributions missing provider, source service, model, or call-site traceability are rejected before any write.
• All writes are atomic and rollback-safe. The full request is validated and staged before publication, symlink components and resolved containment are checked before staging and again before each publication, and a mid-publication failure rolls back both new and replaced outputs.
• The GCP bootstrap manifest hash is pinned in gcp-to-aws and bound to the generated manifest by a test, so the two cannot drift silently.

This advances issue #389 (stage 3a). It does not close that issue.

Changes since the third review (head 972a8640)

Reverted — this PR carries no model-mapping or pricing changes (96b263c5). skills/shared/ai/ (ai-anthropic-to-bedrock.md, ai-gemini-to-bedrock.md, ai-model-lifecycle.md, ai-openai-to-bedrock.md, bedrock-pricing-cache.md, schema-design-aws-ai.md) and all four vendored twins are back to main; so are the GCP/Azure pricing-cache.md, retarget-gotchas.md, discover-preview.md, design-refs/ai-gemini-to-bedrock.md, Azure clarify-ai-only.md/estimate-ai.md, the four aws-design-ai/estimation-ai fixtures, the Sonnet 5.5 rows in clarify-assemble.md / generate-artifacts-report.md, and the BMA hand-adapted clarify/design/estimate/discover-preview/pricing-cache/retarget-gotchas copies. tests/test_bedrock_pricing_sonnet55.py is deleted. The only shared/ai diff left is sdk-capability-map.json (+11 lines of image-output detection patterns the extraction needs; no model facts).

BMA runtime reads the vendored pricing cache (d7840f90, ddcf6bb0). registered_active_models() / pricing_registry() parse Status, Tier and rates from bedrock-pricing-cache.md (with ai-model-lifecycle.md Legacy/EOL + Removed as exclusions) and normalize inference-profile prefixes (us., eu., au., apac., global., us-gov., jp.). design_target resolves embedding/image targets by table + Tier instead of ID literals (same three IDs). MODEL_TARGETS keeps three source→target pairs with no rate literals; gpt-4o → openai.gpt-5.6-terra (matches main's OpenAI guide), Haiku 4.5 priced at the cache rate ($1.00/$5.00). Resolves review Item 4 (CRIS-prefixed IDs / default targets now matched and priced).

Missing-sibling fallback, option 2 of the thread (972a8640). skills/gcp-to-aws/scripts/resolve-ai-track.py + $MIGRATION_DIR/ai-track.json: with Terraform/billing input the infrastructure migration proceeds and the AI track is deferred with a validator-enforced deferred_shared_ai_engine warning (deferred-surfaces report section, exec-assumptions callout, guide subsection); an AI-only repo stops naming bedrock-migration-assessment; a tampered sibling still fails closed. llm-to-bedrock keeps its stop but names the skill.

Tests. Added tests/test_bma_target_registry.py (6) and tests/test_gcp_ai_track_fallback.py (9); updated test_bma_retired_models.py, test_bma_direct_no_sidecar.py, regenerated fixtures/bedrock-migration-assessment/selected-base-semantic-projections.json from the runtime; removed test_bedrock_pricing_sonnet55.py. Plugin CI: 927 passed, 2 skipped; telemetry 280 passed.

Hand-off to #500 (facts intentionally not in this PR):

• Sonnet 5.5 pricing + lifecycle rows (bedrock-pricing-cache.md, ai-model-lifecycle.md) and the Sonnet 5 → 5.5 default/mapping rows across the guides and clarify/design/estimate docs.
• GPT-4o → GPT-6 Luna remap and the 2026-10-14 OpenAI deprecation note (ai-openai-to-bedrock.md, clarify tables); after it lands, MODEL_TARGETS["gpt-4o"] follows.
• ## Verified Active Models / registry table in ai-model-lifecycle.md (now superseded by reading the pricing cache; decide whether docs(aws-startup-advisor): refresh Bedrock model lifecycle for Oct 26 2026 #500 still wants it) and the Last updated bump (lint:model-staleness goes stale 2026-11-05).
• Stable Image Core N. Virginia pricing source paragraph.
• gemini-3.1-flash-image (Nano Banana 2) → Stable Image Core mapping row.
• Replace the three MODEL_TARGETS literals in bma-runtime.py with the docs(aws-startup-advisor): refresh Bedrock model lifecycle for Oct 26 2026 #500 capability table.

Merge order. This PR now depends on PR #500 (model lifecycle/pricing facts, incl. the capability-constraints table) merging first; the default/mapping-guide changes ("Recommend defaults", "Best Bedrock Match", Sonnet 5 → 5.5, GPT-4o → GPT-6 Luna) follow in a separate PR after both.

Changes since first review (head fb1ba769)

For reviewers who saw an earlier head. Every item below was approved explicitly during review and is recorded in the branch's decisions log; commits name the decision they implement.

Second-review follow-ups (head fb1ba769)

• Adapter merges into an existing .bma-input/ document and sidecar instead of overwriting them (@vagmur-aws thread). Writer ownership table: public GCP profile → gcp-to-aws; both .bma-input/* files → bedrock-migration-assessment (@vagmur-aws thread).
• Direct mode runs on a test(aws-startup-advisor): define neutral AI workload profile #415 profile with no sidecar present (needed by the Render follow-up; test added).
• upstream/main merged (brings fix(aws-startup-advisor): isolate telemetry tests and skill attribution #499 telemetry isolation and fix(startup-advisor): align Lambda Event and Web Function guidance #442). bedrock-migration-assessment is intentionally absent from the telemetry SKILL_IDS allowlist until PluginSkillId models it; the telemetry test records this in NOT_YET_MODELLED so the directory check stays exact.

Contract

• BMA reads only the test(aws-startup-advisor): define neutral AI workload profile #415 profile. GCP converts at its boundary (adapter + temporary sidecar); public GCP profile stays legacy. Review threads from @vagmur-aws (selected_base, route gate, Graviton) and @shrugninreddy-hash (CRLF, manifests) are addressed in-thread.

Defaults and pricing (all rates verified against AWS Bedrock model cards / pricing page, cited in skills/shared/ai/bedrock-pricing-cache.md)

• Default Claude recommendation is Sonnet 5.5 (Global $2.00/$10.00, US Geo $2.20/$11.00 per 1M tokens; cache read $0.10 after the 2026-10-07 reduction). Sonnet 5 remains an explicit alternative.
• GPT-4o → openai.gpt-6-luna (OpenAI's own recommended replacement in its 2026-10-14 deprecation notice; GPT-4o shuts down 2027-01-14). US Geo $0.11/$0.55, Global $0.10/$0.50. Replaces the earlier Terra mapping; guides and Clarify tables updated to match.
• Haiku 4.5 target corrected to the documented ID anthropic.claude-haiku-4-5-20251001-v1:0.
• Removed as targets: Claude Sonnet 4.5 and Sonnet 3.5 (both Legacy on Bedrock).
• Stability Image Core $0.04/image (Bedrock, us-east-1). Gemini 3.1 Flash Image added as a source model.

Lifecycle / retirement

• No hand-maintained retired-model list. The lifecycle registry (ai-model-lifecycle.md, Verified Active table) is read at run time. A Bedrock target is priced only when it is listed Active there; an unregistered target gets retirement_status: unverified and no price.
• Source models outside the registry keep their observed cost, labelled lifecycle unverified / observed, not priced from registry, and are excluded from monthly_delta so an unverified baseline is never presented as a verified comparison.
• Unrecognized source-model IDs are rejected with an error that names the ID (fail-closed; fabricated IDs are never admitted as "unverified").

Behavior fixes found by a before/after run on a real app

• Image-output model calls (e.g. gemini-3.1-flash-image) now classify as image_generation and route to Stability, never to a text model. Deterministic via bma-runtime.py design-target.
• Graviton route gate is now a script (gcp-route-gate.py): GATE_NA for AI-only runs, ROUTE_GATE_FAIL stops infrastructure runs.
• Embedding models are accepted and route to amazon.titan-embed-text-v2:0.
• Generate opt-in and confirm_reentry are enforced before any staged write; the "confirmed" evidence-confidence label is removed.
• Report assembly: callers supply a complete document; contributions carry a section; HTML targets require report_mode. Bare contributions fail with document_required. This is a breaking change to the assembly contract.

Known / deferred

• The temporary sidecar is a second, legacy-shaped carrier until the test(aws-startup-advisor): define neutral AI workload profile #415 follow-up. Tracked as follow-up to aws-startup-advisor: extract the AI/LLM engine from gcp-to-aws into its own skill so llm-to-bedrock and agent-advisor stand alone #389.
• Two documentation pins (gcp-to-aws/SKILL.md, discover.md) are hand-set to the generated bootstrap hash because no tool writes them; a test enforces equality. Generator is a follow-up.
• The equivalence harness compares BMA traces, not GCP's LLM-rendered Markdown artifacts; full GCP output equivalence is not claimed. A before/after run on a real Gemini+Imagen app found and fixed the five behavior defects above; its remaining differences are documented in the branch evidence.
• Legacy Sonnet 4.5 ID remains in one example in azure-to-aws's standalone schema-design-aws-ai.md; out of this PR's scope (no Azure changes).

Scope

Skills: bedrock-migration-assessment (new, public), gcp-to-aws (delegation shims, bootstrap, pinned manifest hash), with llm-to-bedrock and agent-advisor only preflighting the new sibling on GCP-selected migration routes. The plugin now exposes 13 public skills.

Files: see git diff --stat upstream/main...HEAD; the first-review count (141 paths) predates the changes listed above. The new skill's 66-file runtime closure, bma-runtime.py, bma-route-classifier.py, the content-contribution schema, bootstrap manifests in skills/shared/migration/ and the GCP runtime copy, plugin and marketplace registration (plugin.json, marketplace.json), the plugin README.md, tests/test_bma_*.py, remote-smoke fixtures, and tooling (build-bma-closure.py, sync-runtime-copies.py, check-skill-refs.py).

Base: main. PR 449 merged on 2026-10-21 and this PR consumes those contracts without duplicating them. PR 369 also merged on 2026-10-21, and this branch has merged main to include it, so the PR 369 Bedrock model and API behavior is still present, now in the new skill. Open PR 459 overlaps this area; its note is in the reviewer block below.

Validation

• Focused pre-ship evidence: 177 tests passed across test_bma_bootstrap.py and the seven-module contribution/runtime selection.
• After merging main (including PR 369): plugin pytest 697 passed and 2 skipped; llm-to-bedrock suite 407 passed; agent-advisor suite 562 passed.
• Plugin mise -C plugins/aws-startup-advisor run ci after the merge, plus root mise run validate, mise run build, and mise run security, all passed.
• Artifact validation on fixtures: 85 artifacts, 0 errors. sync-vendored covered 75 files. check-skill-refs checked 1570 references with 0 missing.
• Exact closure check: 66 entries, manifest SHA-256 96172042cd1a7a4f50d63e6e7594d882757026ef0f027b0acb802c11a3a3f5a8.
• Injection matrix: 13 schema negatives and 3 positives; 26 direct/delegated runtime negatives and 6 positives, all asserting rejection before staging or mutation.
• Restricted remote smoke on Claude Code with tools and MCP disabled: 6/6 scenarios passed, total cost USD 0.28.

Limitations

The equivalence harness carries its own copy of model-mapping, pricing, generated-file, and report-section rules. The Markdown phase files the agent executes do not read those tables. The harness therefore proves the extracted runtime matches the selected base as of this change, but will NOT detect a future edit to the Markdown that changes mappings, prices, or report composition. Reviewers must check such edits by hand until the tables are moved into shared data files consumed by both (tracked as a follow-up to issue #389).

Remote smoke could not independently observe tool or subagent absence (tool_iterations and subagent_calls were null), and packet-level transport was not inspected. All 11 GitHub checks on the current head passed when last verified.

Known issue: scripts/check-bedrock-pricing-parity.py exits non-zero on this branch with Bedrock section changed during extraction. It is not part of CI, and it also failed on this branch's head before main was merged.

For reviewers

File-level move and shim map

The neutral implementations move from GCP ownership into the new skill. These gcp-to-aws files become delegation-only compatibility shims (binding and delegation logic only; no duplicate mapping, pricing, schema, writer, or fallback logic):

• Discover: discover-app-code.md (loaded only when preflight returns AI_CANDIDATE: true), discover-openai-api.md, discover-anthropic-api.md, discover-openrouter-api.md. discover-app-graviton.md is new and GCP-owned: Graviton graviton_profile entries with source: "app_code" are not delegated and are emitted for every source-containing GCP run.
• Clarify: clarify-ai-only.md and the neutral computation in clarify-ai.md
• Design: design-ai.md
• Estimate: estimate-ai.md
• Generate: generate-ai.md, generate-artifacts-ai.md

No file was deleted and Git detects no rename; the move is additions plus modifications because the old paths must survive until later issue #389 stages repoint consumers. GCP phase controllers keep outer orchestration and load the BMA contribution once. Combined-only files (clarify-assemble.md, generate-artifacts-docs.md, generate-artifacts-report.md, report-decision-core.md) stay GCP-owned. Classifier inputs and bootstrap metadata are synchronized across the canonical shared location, the GCP bootstrap copy, and the standalone BMA package.

Ownership and one-writer behavior

• Direct BMA writes direct artifacts. In combined GCP runs, BMA returns validated typed contributions and GCP alone writes combined preferences and wrappers. plan.json has one selected emitter.
• Delegated BMA receives the already selected $MIGRATION_DIR; it cannot create another run, mint another ID, advance GCP outer state, emit GCP telemetry, or write combined wrappers.
• Direct BMA emits no telemetry and reports telemetry_owner: null rather than misattributing activity.
• The schema-version-5 physical write audit records 51 operations and 51 comparisons, all equal, with zero duplicate final writes and zero last-write-wins paths.

Overlap notes for open PRs

• PR 369 (fix(startup-advisor): preserve Astra model and API across Bedrock migration) merged on 2026-10-21 (commit 7cf4fab). This branch merged main as merge commit 5b41eb6 (parents 74b479b and 7cf4fab), keeping the union of both sides. PR 369's neutral model/API behavior was ported into bedrock-migration-assessment (design, estimate, clarify, generate, discover-preview, and openai-on-bedrock), and the gcp-to-aws files stay delegation-only shims. Where this PR's mechanism was the better design it was kept, and no PR 369 capability was dropped.
• PR 459 (feat(aws-startup-advisor): add credits and Azure plans) is open; GitHub currently reports no merge conflicts against main, but it still overlaps this area. Reconciliation must keep GCP Discover initialization and one-time notice ordering at the GCP owner, sync shared/vendored notices through canonical tooling, and refresh the byte-identical BMA copy of canonical plan-emitter changes.

Authorities

Authority	Hash
closure.json	file 96172042cd1a7a4f50d63e6e7594d882757026ef0f027b0acb802c11a3a3f5a8; self-hash 08bada8b83a5b9f150838fb7597a44b86c31524fd2a7c2de5496982c59a00d95
GCP bootstrap manifest	file 127d190a7c80c6bd39189064c6d4226a2f872d7b6dc66adef71b398c62065361; self-hash d30376bc2f88c420f810811cc0d65e243aa1112591e8bb8678625457bce52eaa
content-contribution.schema.json	Draft 2020-12; 97e9dd312ec55695fd4c30a560a45e0672c843484702c85afe38be6513ee980a
bma-runtime.py	87e7a9e98144df80ab45e4db62ee35d4345b7faf0250d136ab696626a348a50c

Complete 66-entry runtime closure

Authoritative manifest: plugins/aws-startup-advisor/skills/bedrock-migration-assessment/references/runtime/closure.json (schema 1, selected base 9ab50636d12510dc351ff02fd7966efa4dba4341, a commit on main: git merge-base --is-ancestor 9ab50636 upstream/main exits 0). Source paths are relative to plugins/aws-startup-advisor/; destinations are relative to the new skill directory.

1. skills/gcp-to-aws/SKILL.md → SKILL.md (adapted)
2. native → references/runtime/bma-input-patterns.json (native)
3. native → scripts/bma-route-classifier.py (native)
4. native → scripts/bma-runtime.py (native)
5. skills/gcp-to-aws/references/design-refs/ai-gemini-to-bedrock.md → references/design-refs/ai-gemini-to-bedrock.md (adapted)
6. skills/gcp-to-aws/references/design-refs/ai.md → references/design-refs/ai.md (adapted)
7. skills/gcp-to-aws/references/phases/clarify/clarify-ai-only.md → references/phases/clarify/clarify-ai-only.md (adapted)
8. skills/gcp-to-aws/references/phases/clarify/clarify-ai.md → references/phases/clarify/clarify-ai.md (adapted)
9. skills/gcp-to-aws/references/phases/design/design-ai.md → references/phases/design/design-ai.md (adapted)
10. skills/gcp-to-aws/references/phases/discover/discover-anthropic-api.md → references/phases/discover/discover-anthropic-api.md (adapted)
11. skills/gcp-to-aws/references/phases/discover/discover-app-code.md → references/phases/discover/discover-app-code.md (adapted)
12. skills/gcp-to-aws/references/phases/discover/discover-openai-api.md → references/phases/discover/discover-openai-api.md (adapted)
13. skills/gcp-to-aws/references/phases/discover/discover-openrouter-api.md → references/phases/discover/discover-openrouter-api.md (adapted)
14. skills/gcp-to-aws/references/phases/discover/discover-preview.md → references/phases/discover/discover-preview.md (adapted)
15. skills/gcp-to-aws/references/phases/estimate/estimate-ai.md → references/phases/estimate/estimate-ai.md (adapted)
16. skills/gcp-to-aws/references/phases/generate/generate-ai.md → references/phases/generate/generate-ai.md (adapted)
17. skills/gcp-to-aws/references/phases/generate/generate-artifacts-ai.md → references/phases/generate/generate-artifacts-ai.md (adapted)
18. skills/gcp-to-aws/references/shared/handoff-gates.md → references/shared/handoff-gates.md (adapted)
19. skills/gcp-to-aws/references/shared/migration-complexity.md → references/shared/migration-complexity.md (adapted)
20. skills/gcp-to-aws/references/shared/openai-on-bedrock.md → references/shared/openai-on-bedrock.md (adapted)
21. skills/gcp-to-aws/references/shared/pricing-cache.md → references/shared/pricing-cache.md (adapted)
22. skills/gcp-to-aws/references/shared/pricing-fallback.md → references/shared/pricing-fallback.md (adapted)
23. skills/gcp-to-aws/references/shared/retarget-gotchas.md → references/shared/retarget-gotchas.md (adapted)
24. skills/gcp-to-aws/references/shared/schema-design-aws-ai.md → references/shared/schema-design-aws-ai.md (adapted)
25. skills/gcp-to-aws/references/shared/schema-discover-ai.md → references/shared/schema-discover-ai.md (adapted)
26. skills/gcp-to-aws/references/shared/schema-phase-status.md → references/shared/schema-phase-status.md (adapted)
27. skills/gcp-to-aws/references/shared/schema-preferences.md → references/shared/schema-preferences.md (adapted)
28. skills/gcp-to-aws/references/shared/validate-artifacts.md → references/shared/validate-artifacts.md (adapted)
29. skills/gcp-to-aws/references/shared/validate-migration-report.md → references/shared/validate-migration-report.md (adapted)
30. skills/shared/ai/ai-anthropic-to-bedrock.md → references/vendored/ai/ai-anthropic-to-bedrock.md (byte-identical)
31. skills/shared/ai/ai-gemini-to-bedrock.md → references/vendored/ai/ai-gemini-to-bedrock.md (byte-identical)
32. skills/shared/ai/ai-migration-guardrails.md → references/vendored/ai/ai-migration-guardrails.md (byte-identical)
33. skills/shared/ai/ai-model-lifecycle.md → references/vendored/ai/ai-model-lifecycle.md (byte-identical)
34. skills/shared/ai/ai-openai-to-bedrock.md → references/vendored/ai/ai-openai-to-bedrock.md (byte-identical)
35. skills/shared/ai/ai-openrouter-to-bedrock.md → references/vendored/ai/ai-openrouter-to-bedrock.md (byte-identical)
36. skills/shared/ai/bedrock-pricing-cache.md → references/vendored/ai/bedrock-pricing-cache.md (byte-identical)
37. skills/shared/ai/bedrock-quotas.md → references/vendored/ai/bedrock-quotas.md (byte-identical)
38. skills/shared/ai/design-ref-agentic-to-agentcore.md → references/vendored/ai/design-ref-agentic-to-agentcore.md (byte-identical)
39. skills/shared/ai/design-ref-harness.md → references/vendored/ai/design-ref-harness.md (byte-identical)
40. skills/shared/ai/sdk-capability-map.json → references/vendored/ai/sdk-capability-map.json (byte-identical)
41. skills/shared/clarify/clarify-availability.md → references/vendored/clarify/clarify-availability.md (byte-identical)
42. skills/shared/clarify/clarify-compliance.md → references/vendored/clarify/clarify-compliance.md (byte-identical)
43. skills/shared/clarify/clarify-cost-appetite.md → references/vendored/clarify/clarify-cost-appetite.md (byte-identical)
44. skills/shared/clarify/clarify-multicloud.md → references/vendored/clarify/clarify-multicloud.md (byte-identical)
45. skills/shared/clarify/clarify-region.md → references/vendored/clarify/clarify-region.md (byte-identical)
46. scripts/emit-plan-json.py → scripts/emit-plan-json.py (byte-identical)
47. scripts/validate-migration-report.py → scripts/validate-migration-report.py (byte-identical)
48. scripts/validate-startup-program-artifacts.py → scripts/validate-startup-program-artifacts.py (byte-identical)
49. native → references/assemblers/decision-report.md (native)
50. native → references/assemblers/migration-docs.md (native)
51. native → references/assemblers/migration-report.md (native)
52. native → references/phases/clarify/clarify.md (native)
53. native → references/phases/design/design.md (native)
54. native → references/phases/discover/discover.md (native)
55. native → references/phases/estimate/estimate.md (native)
56. native → references/phases/generate/generate.md (native)
57. native → references/report-sections/ai-decision-report.md (native)
58. native → references/report-sections/ai-guide.md (native)
59. native → references/report-sections/ai-migration-report.md (native)
60. native → references/report-sections/ai-readme.md (native)
61. native → references/runtime/bedrock-region-map.json (native)
62. native → references/runtime/bma-ai-clarify-result.schema.json (native)
63. native → references/runtime/content-contribution.schema.json (native)
64. native → references/runtime/plugin.json (native)
65. native → references/shared/bma-ai-clarify-result.md (native)
66. scripts/contracts/ai-workload-profile.schema.json → references/contracts/ai-workload-profile.schema.json (byte-identical; the test(aws-startup-advisor): define neutral AI workload profile #415 input contract)

Type of Change

Select at least one.

• New skill
• Bug fix
• Documentation update
• CI/CD change
• Other

Startup Advisor review checklist

By submitting this PR, I confirm that:

• I have reviewed the full diff and understand all changes I am submitting.
• I have tested my changes and confirmed they work as intended.
• I have run mise -C plugins/aws-startup-advisor run ci and all checks pass.
• I have disclosed any known issues, limitations, or untested scenarios.

The first confirmation is left for the author to check after personally reading the 141-path diff; the other three are backed by the Validation and Limitations sections above.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[shrugninreddy-hash]

Requesting changes for the inline comment on line endings. I also agree with vagmur-aws's comment on the Graviton step (discover-app-code.md:124).

One more gap: the new description and the bedrock-migration-assessment keyword are in the Claude and Cursor manifests, but not in .codex-plugin/plugin.json (description, keywords, interface.longDescription), the plugin-root plugin.json, or the .devin-plugin/plugin.json that #482 added to main today. Could you merge main and update all three?

AI-assisted review.

[herosjourney]

@shrugninreddy-hash thanks for the manifest review. All five manifests now list bedrock-migration-assessment in keywords and describe the skill the same way: plugin.json (root), .claude-plugin, .cursor-plugin, .codex-plugin (description and interface.longDescription), and .devin-plugin. Fixed in 563225e.

The Graviton item was already addressed in 39671c0 (restores GCP-owned Graviton app-code profiling).

[herosjourney]

@shrugninreddy-hash Thanks for the manifest check. All five manifests (plugin.json, .claude-plugin, .cursor-plugin, .codex-plugin, .devin-plugin) now carry the bedrock-migration-assessment keyword and the same description. Commit 563225e added the keyword and the BMA capability, and 92a1304 keeps main's existing "move your model calls to Amazon Bedrock" wording with the BMA clause added beside it. The Graviton item was already addressed in 39671c0. Head is f4d509e.

[herosjourney]

@shrugninreddy-hash the manifest finding is valid and fixed. The keyword and description now carry bedrock-migration-assessment in five manifests: plugin.json, .claude-plugin, .cursor-plugin, .codex-plugin, and .devin-plugin. The fix is in commit 563225e, with the description wording kept on main's model-call text in 92a1304. The Graviton item was already addressed in 39671c0.

[leon1418]

[🤖 AI review 🤖]

Reviewed f4d509ed25dad5b9565456e9f5adb504693b9127 against 9ab50636d12510dc351ff02fd7966efa4dba4341. Four functional issues remain: final document rendering, delegated AI-only preferences ownership, authorized phase re-entry, and versioned Google AI detection. The inline comments give the required corrections and acceptance checks.

After the corrections, regenerate the BMA closure and shared/GCP bootstrap manifests from the final source, refresh the pinned hash in GCP SKILL.md and Discover, and run the closure/copy/documented-pin checks.

I verified the source changes addressing the earlier Graviton, non-AI bootstrap, selected-base and five-manifest feedback, plus LF behavior using a core.autocrlf=true checkout simulation.

Validation: targeted reproductions on original source; raw closure, parity, artifact, reference, consent, model/pricing, Markdown, root validation and both Node suites passed; advisor/LLM suites passed 562/407 tests. Current-head Ubuntu CI passed 749 tests with 2 skips. The local macOS plugin run had 643 passes, 106 failures caused by denied nested sandbox-exec, and 2 skips. Independent projected-source tests retained 2 projection-induced closure failures (326 passed, 1 skipped); these were not classified as PR defects.

[shrugninreddy-hash]

Following up on my review: the issues I raised are fixed.

• Line endings: fixed in 8095c41.
• Graviton step: fixed in 39671c0. It's back in gcp-to-aws as discover-app-graviton.md.
• Manifests: fixed in 563225e, 5488dec and 92a1304. All five now have the same description and the bedrock-migration-assessment keyword.

Waiting for the issues raised by leon1418 to be fixed before approval.

AI-assisted comment.

[leon1418]

[🤖 AI review 🤖]

Follow-up at c6ce88b7c2d78a9cf64b30c8a2ce2835f4eaad54 against previously reviewed f4d509ed25dad5b9565456e9f5adb504693b9127. The original plain-text report defect, delegated AI-only preference ownership, and versioned Google import detection are repaired.

Three functional issues remain: final-document assemblies still cannot replace existing outputs using a prior hash; the new report preflight rejects validator-valid attribute ordering; and state decisions do not prevent unrequested Generate writes. I missed the last issue in the first review; it exists at both heads. The report/re-entry details belong in the original threads, with the state-decision issue inline below.

Raw local validation: 672 plugin tests passed, 106 failed because nested macOS sandbox-exec is denied, and 2 were skipped. Advisor/LLM suites passed 562/407 tests. Raw closure, copy/parity, artifact, reference, consent, model/pricing, Markdown, root checks and both Node suites passed. Current-head CI was queued at capture; no prior-head CI result is claimed as current. The independent projected-source test failures remain explicitly separated from source defects.

After corrections, regenerate the raw closure/bootstrap copies and refresh documented pins; keep owner, prior-hash, duplicate-write and rollback checks. Approval remains with the user.

[herosjourney]

@leon1418 @vagmur-aws @shrugninreddy-hash — the branch is at 4b043747 and ready for re-review. Since your last reviews it has grown in two ways, both approved during review and summarized in the new "Changes since first review" section of the description:

1. BMA now reads only the test(aws-startup-advisor): define neutral AI workload profile #415 ai-workload-profile.json contract. GCP converts its legacy profile at the GCP boundary into a test(aws-startup-advisor): define neutral AI workload profile #415 document plus a temporary sidecar in a hidden .bma-input/ location; GCP's public profile keeps its legacy shape. Legacy input to BMA is rejected by name.
2. Defaults and pricing were refreshed against AWS model cards: Sonnet 5.5 is the default Claude target, GPT-4o maps to openai.gpt-6-luna (OpenAI's own replacement in its 2026-10-14 deprecation notice), Haiku 4.5 uses the documented ID, Legacy Sonnet 4.5/3.5 are removed as targets, and retirement status is read from the lifecycle registry at run time rather than a hand-kept list.

A before/after run on a real Gemini + image-generation app surfaced five behavior defects (image calls routed to a text model, a gate that didn't stop the run, the public profile taking the wrong shape, missing sidecar context, false retirement PASS). All five are fixed with regression tests. One note for @leon1418: the report-assembly change you asked for (complete document + section anchors, single final writer) is in and is a breaking change to that contract — bare contributions now fail with document_required.

Previously-open threads have replies in place. I have not resolved any thread. Gates: plugin CI 883 passed, root validate/lint/security clean, gitleaks clean on the full range. The Authorities table and the 66-entry closure list in the description are current for this head.

[herosjourney]

@vagmur-aws @shrugninreddy-hash ready for another look at head fb1ba769.

Since your last review:

• Both open threads are addressed in-thread: the adapter now merges into an existing .bma-input/ document and sidecar instead of overwriting, and the writer-ownership table is explicit (public GCP profile → gcp-to-aws; both .bma-input/* files → bedrock-migration-assessment).
• Direct mode runs on a test(aws-startup-advisor): define neutral AI workload profile #415 profile with no sidecar present (test added).
• upstream/main merged (fix(aws-startup-advisor): isolate telemetry tests and skill attribution #499, fix(startup-advisor): align Lambda Event and Web Function guidance #442); the branch is mergeable again. bedrock-migration-assessment is intentionally left out of the telemetry SKILL_IDS allowlist until PluginSkillId models it, recorded as NOT_YET_MODELLED in the telemetry test.

PR description's Authorities table and "Changes since first review" section are refreshed for this head. I have not resolved any threads; please close them if the fixes look right.

[vagmur-aws]

My two earlier comments are fixed at fb1ba76. These seven are regressions against main or out-of-scope behavior changes; details and repros inline.

[vagmur-aws]

Blocking (regresses GCP runs with no AI): This gate now stops any run that has source code but no top-level graviton_profile in gcp-resource-inventory.json or ai-workload-profile.json. Two common runs can't pass:

billing export + source code               → ROUTE_GATE_FAIL exit=1  (billing writes no inventory)
inventory with metadata.graviton_profile   → ROUTE_GATE_FAIL exit=1  (discover-app-graviton.md says "in the discovery metadata")

On main, a missing profile just meant Clarify asks Q11b. Please don't stop the run on a missing profile. If you keep the gate, make the doc and the script agree on exactly where the list goes, and add a test for billing-only plus source code.

[herosjourney]

Confirmed and fixed in 024a44f. Both runs you named reproduced (ROUTE_GATE_FAIL … reason=missing, exit 1). The gate now treats a missing graviton_profile as "not yet known": it prints GATE_PASS … reason=not_yet_known | note=clarify_q11b_asks_architecture and exits 0, so billing-export + source code continues and Clarify Q11b asks for the architecture exactly as on main. ROUTE_GATE_FAIL is kept only for genuinely malformed input (a file that is not a JSON object, or a graviton_profile that is not an array), and GATE_NA for the AI-only route is unchanged. On the location: the fixtures, scripts/artifact-contracts.json (graviton_profile[]), the validator test and the workshop sheet all read the array at the top level, so top-level stays the one canonical write location; discover-app-graviton.md now says that explicitly (the old "into the GCP discovery metadata" prose was ambiguous), and the gate additionally accepts metadata.graviton_profile so a run that nested it still passes. Tests added for billing-only + source code, inventory with metadata.graviton_profile, missing profile → pass with reason, and the two malformed cases; discover.md Step 2 and schema-graviton.md updated to match.

[vagmur-aws]

Blocking (silent regression for GCP Gemini apps): The current Google GenAI SDK isn't in imports or dependencies. from google import genai, import { GoogleGenAI } from "@google/genai", and a google-genai dependency all return AI_CANDIDATE: false. On main, any source code ran app-code AI discovery, so these apps now lose the AI track with no error. Please add google.genai, the from google import genai form, @google/genai and google-genai, plus a test for each.

[herosjourney]

Confirmed and fixed in 0854843. All forms reproduced as AI_CANDIDATE: false (from google import genai, import google.genai, import { GoogleGenAI } from "@google/genai", google-genai in requirements, @google/genai in package.json). The canonical skills/shared/migration/bma-input-patterns.json now has import tokens google.genai and @google/genai and dependency tokens google-genai and @google/genai; each form now reports AI_SIGNAL_CANDIDATE: true with the file listed in ai_signal_files, and from google import auth stays non-AI. The two runtime copies, closure.json, the bootstrap manifest and the two doc pins were regenerated with tools/sync-runtime-copies.py / tools/build-bma-closure.py rather than hand-edited, and lint:runtime-copy-parity / lint:bma-closure pass. One test per form plus the negative case were added to tests/test_bma_bootstrap.py.

[vagmur-aws]

Blocking: imagen-3.0-generate-001 and o4-mini still fail with LEGACY_MODEL_FAMILY_UNKNOWN, and discover.md then stops the AI route. These worked on main, and Imagen is in this PR's own Gemini+Imagen fixture. Please add imagen and the o-series families (or degrade an unknown family to a per-model warning), with a test each.

[herosjourney]

Confirmed and fixed in 0b9d0e5. imagen-3.0-generate-001, imagen-4.0-fast-generate-001 and o4-mini reproduced with LEGACY_MODEL_FAMILY_UNKNOWN. The adapter's FAMILY_PREFIXES now mirrors SOURCE_MODEL_FAMILY in bma-runtime.py: imagen* → family imagen (image output, which the BMA capability map and design-target already route to Stability), and o4* joins o1*/o3* on the gpt track per ai-openai-to-bedrock.md. We deliberately did not add a generic unknown-family downgrade — unrecognized model IDs are still rejected by name (e.g. mistral-large), which is a standing decision on this PR. Tests cover each new family (six IDs), an end-to-end conversion of the Gemini+Imagen fixture with imagen-3.0-generate-001 that validates against the #415 schema and validate-profile, and the still-rejected unknown case. The mapping row in gcp-ai-profile-415-mapping.md was updated.

[vagmur-aws]

Blocking (GCP AI estimates come out unpriced): The registry this rule checks has 6 rows. 57 of the model IDs in the pricing cache aren't in it, so they get no price. That includes Nova Lite and Micro, Sonnet 5, Opus 5.5, titan-embed-text-v2 and stable-image-core (the new embedding and image defaults), and even the default's own global. and us.anthropic.claude-sonnet-5-5 IDs. Source models outside the 3-entry MODEL_TARGETS table also get no target. GCP AI estimates now run through this file, so they lose prices that they have on main. Please price from bedrock-pricing-cache.md as before, or make the registry cover every priced row before gating on it.

[herosjourney]

Agreed on the defect: registered_active_models() does an exact-string lookup, so our own targets miss via the us./global. cross-region prefixes, and amazon.titan-embed-text-v2:0 / stability.stable-image-core-v1:0 were never in the 6-row table at all. We are not fixing it in this head because the shape of the fix changed with the scope split below: this PR's shared/ai edits (including that 6-row "Verified Active Models" table) are being reverted, and the lifecycle facts are moving to PR #500, whose registry already carries the full Active/Legacy/EOL table plus a new capability-constraints table. Once #500 lands and is merged into this branch, design-target will read lifecycle status (with CRIS-prefix normalization) from that registry rather than a BMA-private list, and a test will assert every emitted target resolves to an Active base model and is priced. The pricing rule itself (price iff target Active) is unchanged. For the record, 55 pricing-cache IDs are absent from the current 6-row table. Leaving this thread open until that lands.

[herosjourney]

Update: this landed in this PR after all, in d7840f90. registered_active_models() / pricing_registry() now read Status, Tier and rates from the vendored bedrock-pricing-cache.md (with ai-model-lifecycle.md Legacy/EOL/Removed as exclusions) and normalize inference-profile prefixes (us., eu., au., apac., global., us-gov., jp.), so the CRIS-prefixed IDs and the embedding/image targets you listed are matched and priced. The 6-row BMA-private table is gone with the shared/ai revert. tests/test_bma_target_registry.py asserts every target design-target can emit resolves to an active, priced row. Pricing rule unchanged (price iff Active).

[vagmur-aws]

Blocking (GCP report reruns fail): GCP's combined migration-report.html and DECISION.md now have to be written through this assembly path, which can't replace an existing file. Delegated combined repro: the first assembly is OK, and the second fails with duplicate_final_write. Adding the prior hash fails with assembly_request_invalid because expected_sha256 isn't accepted here. On main, GCP can regenerate these reports. This is the same item leon1418 raised. Please accept expected_sha256 on assemblies and pass it to prepare.

[herosjourney]

Confirmed and fixed in 90a96f3 — same root cause as leon1418's thread. Reproduced exactly: first assembly OK, rerun without hash duplicate_final_write, rerun with the prior hash assembly_request_invalid because expected_sha256 was not an accepted assembly field. Assembly requests now accept optional expected_sha256 and pass it to the same prepare path writes[] use, so a rerun with the file's current SHA-256 replaces migration-report.html / DECISION.md (and the other replaceable report targets); without the hash it still fails duplicate_final_write, a stale hash fails expected_prior_hash_mismatch, and the owner, owning-phase, downstream-authorization, same-request-duplicate and rollback protections are unchanged. The assembler ABI docs and the GCP report/decision phase docs (report-decision-core.md, generate-artifacts-report.md, generate-artifacts-docs.md, estimate.md decision-pack re-entry) now show passing the hash. Tests cover rerun with the correct hash (file replaced), without hash, wrong hash, hash on a missing target, and the delegated-mode DECISION.md rerun including the owning-phase guard.

[vagmur-aws]

Blocking unless intended: With only gcp-to-aws installed, any GCP repo with AI evidence now stops with BEDROCK_MIGRATION_ASSESSMENT_SIBLING_MISSING, and llm-to-bedrock now needs three siblings. That works on main today. It is the per-skill install decision that #389 asks a maintainer to make, and that decision hasn't been made yet. Please get it recorded on #389 before merge, or keep a fallback for that install.

[herosjourney]

Implemented option 2 in 972a8640. When bedrock-migration-assessment is not installed beside gcp-to-aws, a new stdlib resolver skills/gcp-to-aws/scripts/resolve-ai-track.py runs on the first classifier pass and decides:

• No AI evidence → not_applicable; the sibling is never even stat'ed (pure infrastructure keeps doing zero BMA operations).
• Sibling present → active; the existing second classifier pass with --bma-base runs exactly as before. A present-but-tampered sibling still fails closed with BMA_STANDALONE_CLOSURE_INVALID — that is not a deferral case and bma-route-classifier.py is unchanged.
• Sibling missing + infrastructure input (Terraform/billing in the repo, or a resumed run with gcp-resource-inventory.json / billing-profile.json / live-capture/manifest.json) → deferred. The infrastructure migration proceeds; the AI track is deferred with an explicit deferred_shared_ai_engine warning, never silently dropped and never represented as generated. The decision is recorded once in $MIGRATION_DIR/ai-track.json (contract in references/shared/schema-ai-track.md, registered in artifact-contracts.json) and surfaces in the Discover preview, the Clarify assumption sheet, the decision report (exec-assumptions callout), MIGRATION_GUIDE/README ("Deferred: AI workloads") and the migration report as a required <section id="deferred-surfaces"> naming the missing skill and the install command.
• Sibling missing + AI-only repo → AI_TRACK_FAIL | code=bedrock_migration_assessment_missing_ai_only | missing_skill=bedrock-migration-assessment | detail=…, exit 1, since there is nothing else to migrate. llm-to-bedrock keeps its stop for the same reason but now names the skill and the install command.

The report validator enforces it (--migration-dir): AI_DEFERRED_STATE_MISSING when the deferred section/callout is absent, AI_DEFERRED_BUT_AI_SECTIONS_PRESENT if appendix-ai/exec-tco appear anyway, AI_DEFERRED_IN_AI_ONLY_MODE, and AI_DEFERRED_WARNING_UNEXPECTED when the warning text appears without a deferred track. Behavioral coverage in tests/test_gcp_ai_track_fallback.py runs the resolver as a subprocess against a temp copy of skills/gcp-to-aws with the sibling genuinely absent (defer / AI-only fail / present-unchanged / tampered-still-fails / never-stats). This mirrors the resolve-ai-track.py + deferred-surfaces pattern already used by render-to-aws.

[vagmur-aws]

Production behavior change, out of scope: Editing the shared defaults (Sonnet 5.5 as the default here, and GPT-4o → GPT-6 Luna in ai-openai-to-bedrock.md) changes the recommendations from azure-to-aws, agent-advisor and gcp-to-aws through the vendored copies, 13 files outside BMA. That contradicts #389 ("no model mapping or pricing changes" in the extraction) and this PR's own "no Azure changes" note. Sonnet 5.5 also rejects forced tool_choice, so apps that rely on it would break after following the recommendation. Please move the defaults and pricing changes to a separate PR.

[herosjourney]

Agreed, and splitting. The verified model facts from these edits (rates, IDs, lifecycle rows, and a new capability-constraints table that records, among other things, that Sonnet 5.5 accepts tool_choice auto/none only, which confirms your point) have moved to PR #500 at 0820cda5. The next push on this PR reverts every change under skills/shared/ai/ and the vendored twins back to main, and reverts the Q16/Q21/Q22 answer-table edits in the Clarify docs, so this PR carries no model-mapping or pricing changes per #389. Default/mapping-target changes ("Recommend defaults", "Best Bedrock Match", GPT-4o → GPT-6 Luna as a target) go to a separate mapping-guide PR after #500 merges. This PR will depend on #500 landing first.

[herosjourney]

@vagmur-aws @leon1418 @shrugninreddy-hash ready for re-review at head 972a8640.

All seven items from the 2026-10-27 review are addressed in-thread. In short: the route gate no longer fails on a missing Graviton profile; the google-genai SDK is detected; imagen and o-series families are recognized; report assemblies accept expected_sha256 so reruns work; the runtime prices from the vendored pricing cache with prefix normalization; every shared/ai and Clarify-table edit is reverted to main (only sdk-capability-map.json detection patterns remain), with the verified model facts moved to PR #500; and a missing bedrock-migration-assessment sibling now defers the AI track with a validator-enforced warning instead of stopping the run.

Merge order: #500 first, then this PR. The description's "Changes since the third review" section and Authorities hash table are refreshed. Threads left open for you to close.

[mickylindsay]

This is a monstrously large PR. First pass agent adversarial review is reporting a few dozen contradictions. Ill comment on the High findings, but with a list that large I strongly urge you to run your own review against HEAD. After almost 60 additional commits, it appears that the expected behavior and functionality have drifted

[mickylindsay]

This isnt behaving how the PR description claims it should. Desc states "missing or tampered sibling fails closed with BEDROCK_MIGRATION_ASSESSMENT_SIBLING_MISSING or BMA_STANDALONE_CLOSURE_INVALID rather than silently degrading"

Your code fails silently.

[mickylindsay]

Schema still lists it, schema-discover-ai.md still allows it.
Description says user confirmation is removed. Seems like there is still a expected path that will set users in this now failing state.

Decide if confirmed is to remain or be removed, and reconcile the rest of your change to be consistent on that decision.

[mickylindsay]

estimate phase is setting these tiers 10x what the clarify phase claims.
Low here is 6M in and 4M out. Low in clarify is < 1M

Have we tested these changes? I would expect that discrepancy to damage the quality of the outputs

[herosjourney]

Thank you for the detailed reviews. They exposed cross-contract inconsistencies after extensive scope drift: runtime behavior no longer consistently matches the schemas, phase documents, estimates, or this PR's description. At this size and history, adding more repair commits would make the change harder—not easier—to review with confidence.

We are superseding #483 with a sequence of smaller, independently testable PRs tracked in #389: standalone BMA contract/core; design and estimate engine; GCP adapter/delegation; report assembly; then the consumer integrations. The useful tests and decisions from this branch will become requirements for those PRs, but implementations will be rebuilt from current main rather than mechanically carried forward.

Reviewers do not need to continue reviewing the current head. I am leaving the PR open momentarily for traceability; it will not be merged in its current form.

[herosjourney]

Closing as superseded by the smaller replacement sequence documented in #389 (3a.1–3a.4). The branch and review history remain available as implementation evidence, but this PR will not be merged or used as a source of mechanically cherry-picked commits.

Thank you to everyone who reviewed it and surfaced the cross-contract inconsistencies.