diff --git a/aws-transform/steering/workload-mainframe-reimagine-modern-traceability.md b/aws-transform/steering/workload-mainframe-reimagine-modern-traceability.md new file mode 100644 index 0000000..b7cc9d9 --- /dev/null +++ b/aws-transform/steering/workload-mainframe-reimagine-modern-traceability.md @@ -0,0 +1,392 @@ +--- +inclusion: always +--- + +# Phase 5: Modern Code Traceability + +> **Last Updated:** 2026-06-30 + +This steering file guides the generation of annotated modern code and traceability artifacts that link functional requirements (from the reimagine pipeline) to their implementing code locations in a modernized codebase. It is the fifth and final phase of the mainframe reimagine pipeline, following Phase 4 (Traceability Verification). + +It is language-agnostic and architecture-agnostic — it auto-detects the customer's target stack and adapts accordingly. + +## When to Use + +- After Phase 4 (`workload-mainframe-reimagine-verify.md`) has completed with a `traceability-dashboard.html` +- User asks to "implement from specs", "forward engineer", "build from requirements", or "generate code" +- User asks to start implementing a specific microservice specification from `outputs/microservices/` + +**Key principle:** Traceability annotations are inserted AT WRITE TIME — as code is being generated. This ensures 100% coverage by default. + +**Relationship to Phase 4:** Phase 4 (`traceability-dashboard.html`) verifies that all requirements appear in microservice specifications. Phase 5 (`traceability-modern.yaml`) verifies that all requirements appear in the actual generated source code. They are separate artifacts at different levels of the chain: + +``` +Legacy COBOL rules (traceability.yaml) + → Requirements (requirements.md) + → Microservice Specs (*-specification.md) ← Phase 4 verifies this link + → Modern Source Code (*.java, *.cs, etc.) ← Phase 5 verifies this link +``` + +The REQ-* ID is the join key across all levels. A compliance reviewer can trace any `@TracesRequirement("REQ-F-044")` annotation in modern code back through the spec → `requirements.md` → `traceability.yaml` → original COBOL rule. + +## Prerequisites + +- Phase 1–4 of the reimagine pipeline completed +- `outputs/microservices/*-specification.md` files exist (Phase 3 output) +- `traceability-dashboard.html` exists (Phase 4 output) +- `spec//requirements.md` and `spec//traceability.yaml` present for all business functions +- The target modern source code project is set up (or will be created during generation) + +--- + +## Step 1: Target Stack Discovery + +Before generating any code, determine the customer's target environment. The detection order is: + +1. **Customer steering files** — read `.kiro/steering/` for target language, framework, project structure, and naming conventions. These are the authoritative source. +1. **Build/project files** — if no steering files specify the stack, inspect the workspace: + +| Indicator File | Language | Framework Hints | +|---------------|----------|-----------------| +| `pom.xml`, `build.gradle`, `*.java` | Java | Spring Boot, Quarkus, Micronaut | +| `*.csproj`, `*.sln`, `*.cs` | C# | .NET, ASP.NET Core | +| `package.json`, `tsconfig.json`, `*.ts` | TypeScript | Node.js, NestJS, Express | +| `package.json`, `*.js` | JavaScript | Node.js, Express | +| `pyproject.toml`, `setup.py`, `*.py` | Python | FastAPI, Django, Flask | +| `go.mod`, `*.go` | Go | Standard library, Gin, Echo | +| `Cargo.toml`, `*.rs` | Rust | Actix, Axum, Tokio | + +1. **Ask the user** — if neither steering files nor build files provide clarity, ask: "I couldn't determine your target language from steering files or project structure. What language/framework are you targeting?" + +--- + +## Step 2: Inline Tracing During Code Generation (Write-Time) + +**This is the primary traceability mechanism.** When generating modern code from a microservice specification, traceability annotations MUST be inserted as the code is being written. + +### Pre-Generation: Load the Requirement Checklist + +Before writing any code for a service, extract every `REQ-*` identifier from the service's specification file in `outputs/microservices/-specification.md`. These IDs were distributed to each service during Phase 3 (specgen) and appear throughout sections 1–8 of the spec. + +The agent MUST: +1. **Build a tracking list** of all REQ-* IDs from the specification — this is the punch list for this service +2. **Keep this list in working memory** throughout code generation, marking each REQ-* as "traced" when a corresponding annotation is written + +Each specification's header shows which business functions it covers, for example: +``` +> **Source Functions**: BatchDataProcessing-AccountProcessing, OnlineTransactionProcessing-AccountManagement +``` +This determines which `spec//traceability.yaml` files contain the legacy rule hashes that back-fill the `legacy_rule_ids` field in `traceability-modern.yaml`. + +**This list is the source of truth.** Code generation is not complete for a service until every REQ-* on the list has been annotated in at least one code location. + +### Write-Time Rules + +When writing any method, function, or handler that implements a requirement: + +1. **Before writing the code element**, determine which REQ-* ID(s) it satisfies +2. **Insert the appropriate annotation** immediately above the method/function signature +3. **Mark the requirement as traced** on the tracking list +4. **Track the mapping** for later inclusion in `traceability-modern.yaml` + +This is NOT optional. Every method that implements a traced requirement gets an annotation at write time. + +### Post-Generation Gate: Completeness Check + +After all code for a service has been written, the agent MUST: + +1. **Review the tracking list** — identify any REQ-* IDs still unmarked +2. **If gaps exist**, the agent SHALL NOT consider code generation complete. Instead: + - List the untraced requirements to the user + - Ask: "These requirements don't have implementing code yet. Should I implement them now, or are they handled elsewhere?" + - If the user confirms they are out of scope, mark them as `excluded` with a reason + - Otherwise, implement the missing requirements before proceeding +3. **Only after all requirements are traced or explicitly excluded** may the agent proceed to generate `traceability-modern.yaml` + +### Exclusion Guardrails + +1. **Every exclusion requires a reason.** Acceptable reasons: + - "Handled by service X" (cross-service boundary) + - "Infrastructure concern, not application code" (e.g., deployment, monitoring) + - "Deferred to phase 2" (with user acknowledgment) + - Free-text from the user + +2. **Exclusions are always visible** in `traceability-modern.yaml` and the validation report with their reason. They are NEVER silently omitted. + +3. **Threshold warning.** If more than 20% of requirements are excluded, the agent MUST warn: + > "X out of Y requirements (Z%) are marked as excluded. This is a high exclusion rate — are you sure these are all handled elsewhere? Would you like to review the list?" + +### Context Persistence Across Sessions + +For large services spanning multiple sessions, write tracking state to `outputs/microservices/-traceability-progress.yaml` after each session: + +```yaml +service: account-service +source_functions: + - BatchDataProcessing-AccountProcessing + - OnlineTransactionProcessing-AccountManagement +total_requirements: 49 +traced: [REQ-F-001, REQ-F-002, ...] +excluded: [] +remaining: [REQ-F-044, REQ-F-048] +last_updated: '2026-06-30T15:30:00Z' +``` + +On resume, check for `outputs/microservices/*-traceability-progress.yaml`. If a file exists: +- Load the tracked/excluded/remaining lists +- Tell the user: "Resuming traceability — X/Y requirements already traced. Continuing with the remaining Z." + +On completion (gate passes), delete `-traceability-progress.yaml` — the final `traceability-modern.yaml` supersedes it. + +### Annotation Granularity + +Annotate at the **lowest-level method that meaningfully implements business logic**, not the orchestrator that calls it. + +| Scenario | Where to Annotate | +|----------|-------------------| +| One requirement → one method | That method | +| One requirement → multiple methods | Each method that contributes distinct logic | +| Orchestrator calls sub-methods | The sub-methods, NOT the orchestrator | +| Helper/utility shared across requirements | Do NOT annotate the helper | +| One method satisfies multiple requirements | Stack annotations on that method | + +**Rule of thumb:** If you removed the annotated method, would the requirement no longer be satisfied? If yes, the annotation is correctly placed. + +### Annotation Format (by detected language) + +| Language | Format | Placement | +|----------|--------|-----------| +| Java | `@TracesRequirement("REQ-F-XXX")` | Above method, after other annotations | +| C# | `[TracesRequirement("REQ-F-XXX")]` | Above method, after other attributes | +| TypeScript/JS | `/** @traces REQ-F-XXX */` | Above function/method, merged into existing JSDoc if present | +| Python | `@traces_requirement("REQ-F-XXX")` | Below other decorators, above `def` | +| Go | `// traces: REQ-F-XXX` | Line above function signature | +| Rust | `/// traces: REQ-F-XXX` | In doc comment block above function | +| Other/Unknown | `// traces: REQ-F-XXX` | Line above function/method | + +### Multiple Requirements Per Method + +Stack annotations when a single method implements multiple requirements: + +```java +@TracesRequirement("REQ-F-044") +@TracesRequirement("REQ-F-048") +public void postTransaction(Transaction txn) { ... } +``` + +```python +@traces_requirement("REQ-F-044") +@traces_requirement("REQ-F-048") +def post_transaction(self, txn: Transaction) -> None: ... +``` + +```typescript +/** @traces REQ-F-044 @traces REQ-F-048 */ +async postTransaction(txn: Transaction): Promise { ... } +``` + +### Annotation Type Definition + +Include the annotation type definition in the project when generating the first annotated file: + +**Java** — Create `TracesRequirement.java`: +```java +package com.example.traceability; + +import java.lang.annotation.*; + +@Retention(RetentionPolicy.SOURCE) +@Target({ElementType.METHOD, ElementType.TYPE}) +@Repeatable(TracesRequirements.class) +public @interface TracesRequirement { + String value(); +} +``` +And the container annotation for `@Repeatable`: +```java +package com.example.traceability; + +import java.lang.annotation.*; + +@Retention(RetentionPolicy.SOURCE) +@Target({ElementType.METHOD, ElementType.TYPE}) +public @interface TracesRequirements { + TracesRequirement[] value(); +} +``` + +**C#** — Create `TracesRequirementAttribute.cs`: +```csharp +[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = true)] +public sealed class TracesRequirementAttribute : Attribute +{ + public string RequirementId { get; } + public TracesRequirementAttribute(string requirementId) => RequirementId = requirementId; +} +``` + +**Python** — Create `traceability.py`: +```python +def traces_requirement(*req_ids: str): + """Decorator marking a function as implementing the given requirement(s). No runtime effect.""" + def decorator(func): + func._traces_requirements = getattr(func, '_traces_requirements', []) + list(req_ids) + return func + return decorator +``` + +**Go/Rust/Other** — No type definition needed (comment-based annotations). + +--- + +## Step 3: Generate `traceability-modern.yaml` + +After the completeness gate passes for a service, produce this artifact. Write one file per service into `outputs/microservices/`: + +```yaml +service: # e.g., account-service +generated_at: '' +source_commit: '' +target_language: '' +architecture: '' +project_root: '' + +# The source functions this service was built from (from the spec header) +source_functions: + - # e.g., OnlineTransactionProcessing-AccountManagement + - # e.g., BatchDataProcessing-AccountProcessing + +summary: + total_requirements: + covered: # requirements with at least one trace in code + excluded: # user-confirmed out-of-scope (with reasons) + gaps: # neither implemented nor excluded (should be 0 after gate) + +traces: +- req_id: REQ-F-XXX + legacy_rule_ids: + # Populated from spec//traceability.yaml. + # Find all captured rules where this REQ-* ID appears in either: + # req_id: REQ-F-XXX (singular — rule maps to one requirement) + # req_ids: [REQ-F-XXX, ...] (plural — rule maps to multiple requirements) + # Both forms exist in the real data. List every matching rule_id here. + # Use the exact underscore-separated UUID format, e.g.: + - 139833a6_6bfd_4ba1_ade8_4f6380850ac4 + locations: + - target_file: + element_type: + element_name: + start_line: + end_line: + annotations: + - '' + +# For excluded requirements: +- req_id: REQ-F-YYY + status: excluded + reason: '' + locations: [] +``` + +### Writing Rules + +- One file per microservice (e.g., `outputs/microservices/account-service-traceability-modern.yaml`) +- One entry per REQ-* ID +- `legacy_rule_ids` is always populated in the mainframe reimagine context. For each REQ-* ID, scan all `spec//traceability.yaml` files for the source functions covered by this service. Match rules where: + - `req_id: ` (singular field — rule maps to exactly one requirement), OR + - `req_ids: [, ...]` (plural field — rule maps to multiple requirements) + - Both forms appear in the real data; check for both +- If a service covers multiple source functions, search all their `traceability.yaml` files +- Multiple locations per requirement are normal (one requirement implemented across several methods) +- Use dot-notation for qualified names regardless of language (e.g., `AccountService.getBalance`) +- File paths use forward slashes, relative to `project_root` +- If `source_commit` cannot be determined, use `"unknown"` + +--- + +## Step 4: Completeness Validation + +This step produces a persistent, auditable report that can be run in CI/CD pipelines independently of the agent. + +### Process + +1. Load all `spec//traceability.yaml` files for functions covered by this service — extract every `req_id`/`req_ids` entry where `disposition: captured` (both singular and plural forms appear in the real data — see Step 3 Writing Rules) +2. Load `outputs/microservices/-traceability-modern.yaml` — extract all entries with their locations and status +3. Classify each requirement: + - **covered** — at least one trace location exists in code + - **excluded** — user-confirmed out-of-scope with a recorded reason + - **gap** — neither implemented nor excluded (should be zero if the gate passed) + +4. Produce two outputs per service: + - `outputs/microservices/-traceability-validation.md` — human-readable + - `outputs/microservices/-traceability-validation.yaml` — machine-readable for CI/CD + +### Validation Report Template + +```markdown +# Traceability Validation — + +**Generated:** +**Target language:** () +**Source functions:** , +**Spec artifact:** outputs/microservices/-specification.md +**Modern artifact:** outputs/microservices/-traceability-modern.yaml + +| Status | Count | Percentage | +|--------|-------|-----------| +| Covered (implemented) | N | X% | +| Excluded (out of scope) | N | X% | +| Gap (unresolved) | N | X% | + +### Excluded Requirements + +| Req ID | Reason | +|--------|--------| +| REQ-F-013 | Handled by shared DateUtils library in platform-commons service | + +### Gaps (Unresolved) + +``` + +--- + +## Key Principles + +- **Requirements-driven** — The REQ-* list is loaded from `outputs/microservices/-specification.md` BEFORE code generation begins. Code generation is not complete until every requirement is traced or explicitly excluded. +- **Write-time only** — Annotations are inserted AS code is being generated. No post-hoc scanning. +- **Gated completion** — The agent cannot declare code generation done until the completeness check passes. +- **Language-agnostic by default** — Never assume a target language. Always detect first. +- **One service at a time** — Process one microservice specification completely (including its traceability gate and YAML output) before moving to the next. This mirrors the "one service at a time" principle from Phase 3 (specgen). +- **Deterministic** — All traces are inserted by the agent at generation time with full knowledge of which requirement is being implemented. +- **Composable** — Works alongside the existing `workload-mainframe-reimagine-verify.md` verification (which checks specs), extending the chain one step further into code. + +--- + +## Example Workflow + +``` +User: "Implement the account-service from the spec" + +Agent: +1. Reads outputs/microservices/account-service-specification.md + → Extracts 49 REQ-* IDs into tracking checklist + → Notes source functions: BatchDataProcessing-AccountProcessing, + OnlineTransactionProcessing-AccountManagement +2. Detects target: Java (found pom.xml) +3. Generates TracesRequirement.java annotation type (first time only) +4. Writes AccountService.java with @TracesRequirement annotations on each + method — marks REQ-F-001, REQ-F-002, etc. as traced +5. Continues generating remaining service classes... +6. Post-generation gate: checks tracking list + → 48/49 traced, REQ-F-013 has no implementation + → Asks user: "REQ-F-013 (timestamp formatting) isn't implemented yet. + Should I implement it, or is it handled elsewhere?" +7. User says "implement it" → agent writes DateUtils with annotation +8. 49/49 traced — gate passes +9. Generates outputs/microservices/account-service-traceability-modern.yaml + → For each REQ-*, scans spec/OnlineTransactionProcessing-AccountManagement/traceability.yaml + and spec/BatchDataProcessing-AccountProcessing/traceability.yaml + → Matches rules with req_id: (singular) OR req_ids: [, ...] (plural) + → Populates legacy_rule_ids with all matching rule_id values +10. Generates account-service-traceability-validation.md (100% coverage) +``` diff --git a/aws-transform/steering/workload-mainframe-reimagine.md b/aws-transform/steering/workload-mainframe-reimagine.md index c2f089a..9bf5fe6 100644 --- a/aws-transform/steering/workload-mainframe-reimagine.md +++ b/aws-transform/steering/workload-mainframe-reimagine.md @@ -24,6 +24,7 @@ After a mainframe modernization job completes analysis and generates requirement | DDD Bounded Context Design | `ddd-analysis.md` | Domain model with contexts, aggregates, events | `workload-mainframe-reimagine-ddd.md` | | Microservice Spec Generation | DDD model + `spec/` | One `*-specification.md` per service | `workload-mainframe-reimagine-specgen.md` | | Traceability Verification | Specs + `spec/` | `traceability-dashboard.html` (pass/fail) | `workload-mainframe-reimagine-verify.md` | +| Modern Code Traceability | `outputs/microservices/*-specification.md` | Annotated code + `*-traceability-modern.yaml` per service | `workload-mainframe-reimagine-modern-traceability.md` | **User confirmation is required before starting the pipeline (see Gate below).** Once started, phases run sequentially without additional prompts. @@ -111,7 +112,7 @@ Ask the user via AskUserQuestion: **Question:** "Workspace is ready. Would you like to start the reimagine analysis?" **Options:** -- **"Start reimagine" (Recommended)** — "I'll run 4 phases to decompose your legacy system into microservice specifications: business function analysis → domain model design → microservice spec generation → traceability verification. I'll give you a summary after each phase." +- **"Start reimagine" (Recommended)** — "I'll run 5 phases to decompose your legacy system into microservice specifications and generate modern code: business function analysis → domain model design → microservice spec generation → traceability verification → modern code generation with traceability annotations. I'll give you a summary after each phase." - **"Explore with AWS Transform plugin"** — "Install the AWS Transform VS Code extension to browse specs and source interactively with traceability and AI-powered docs." - **"Stop here"** — "Workspace is set up. You can come back later to start." @@ -144,7 +145,8 @@ Before starting any phase, check what output files already exist in the workspac | `ddd-working.md` (without `ddd-bounded-contexts.md`) | Resume Domain Model Design mid-way — read the working file and continue from the last completed step | | `ddd-bounded-contexts.md` | Microservice Spec Generation | | `outputs/microservices/*.md` | Traceability Verification | -| `traceability-dashboard.html` | Done — show results | +| `traceability-dashboard.html` (without `outputs/microservices/*-traceability-modern.yaml`) | Modern Code Traceability | +| `outputs/microservices/*-traceability-modern.yaml` | Done — show results | If a previous phase's output exists, tell the user: "I can see you've already completed [phase]. Continuing from [next phase]." @@ -156,12 +158,13 @@ This allows the user to resume in a new conversation if context runs out. Once the user confirms, tell them: -> "Starting the reimagine process. I'll run 4 phases and give you a summary along the way:" +> "Starting the reimagine process. I'll run 5 phases and give you a summary along the way:" > > 1. **Business function analysis** — consolidate all spec artifacts into a single analysis document > 2. **Domain model design** — identify bounded contexts, aggregates, and domain events > 3. **Microservice spec generation** — produce one detailed specification per service -> 4. **Traceability verification** — confirm every business rule and requirement is covered +> 4. **Traceability verification** — confirm every business rule and requirement is covered in specs +> 5. **Modern code traceability** — generate annotated code with requirement traces linked back to legacy rules > > If we run into context limits, you can start a new conversation — I'll detect the progress and resume from where we left off. @@ -200,3 +203,13 @@ Tell the user: "Specs generated. Running traceability verification..." Read and follow `workload-mainframe-reimagine-verify.md`. When complete, present the coverage results (percentage, any gaps) and the path to the HTML dashboard. + +### Modern Code Traceability + +Tell the user: "Specs verified. Ready to generate modern code with full traceability annotations." + +Read and follow `workload-mainframe-reimagine-modern-traceability.md`. + +Process one microservice specification at a time. For each service: detect the target language, build the REQ-* tracking list from the spec, generate the annotated code, run the completeness gate, then produce `outputs/microservices/-traceability-modern.yaml` before moving to the next service. + +When all services are complete, summarize: language detected, total services implemented, total requirements traced across all services, any exclusions, and paths to the generated `*-traceability-modern.yaml` files.