Skip to content

fix: constrain *-design to design-level artifacts, no code#402

Open
jeromevdl wants to merge 2 commits into
awslabs:v2from
jeromevdl:fix/code-in-design-artifacts
Open

fix: constrain *-design to design-level artifacts, no code#402
jeromevdl wants to merge 2 commits into
awslabs:v2from
jeromevdl:fix/code-in-design-artifacts

Conversation

@jeromevdl

@jeromevdl jeromevdl commented Jun 18, 2026

Copy link
Copy Markdown

Summary

Adds a ## Constraints section to infrastructure-design.md, functionnal-design.md and nfr-design.md stage files, explicitly stating that implementation-ready code belongs in code-generation, not in design stages.

Design artifacts should describe what infrastructure/patterns are needed and why — not ship complete CDK constructs, Lambda handlers, or IAM policy documents. Code snippets are limited to short illustrative pseudocode (≤15 lines) that clarify a design decision.

Fixes #396

Changes

  • core/aidlc-common/stages/construction/infrastructure-design.md — added Constraints section
  • core/aidlc-common/stages/construction/functional-design.md — added Constraints section
  • core/aidlc-common/stages/construction/nfr-design.md — added Constraints section
  • dist/ regenerated via bun scripts/package.ts

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

@jeromevdl jeromevdl requested review from a team as code owners June 18, 2026 22:05
@github-actions github-actions Bot added documentation Improvements or additions to documentation github rules labels Jun 18, 2026
@jeromevdl jeromevdl changed the base branch from main to v2 June 18, 2026 22:28
…rtifacts

Add a Constraints section to both stage files clarifying that
implementation-ready code (CDK constructs, Terraform modules, Lambda
handlers, IAM policies) belongs in code-generation, not design stages.
Code snippets are limited to short illustrative pseudocode (≤15 lines).

Fixes awslabs#396
Apply the same Constraints section to functional-design.md — business
logic models, domain entities, and rules should stay at design level,
not produce complete function bodies or framework-specific code.
@jeromevdl jeromevdl force-pushed the fix/code-in-design-artifacts branch from 50485a8 to 43200f2 Compare June 19, 2026 07:16
@jeromevdl jeromevdl changed the title fix: constrain infrastructure-design and nfr-design to design-level artifacts fix: constrain *-design to design-level artifacts, no code Jun 19, 2026

@apackeer apackeer left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the fix, this is a clean and well-placed prose change and it lines up with the intent of #396. Approving in principle, with a short punch list to land it on top of current v2.

Substantive

  1. The Constraints paragraph reads well and sits in the right place (right after the MANDATORY line, before ## Steps). The 15-line pseudocode carve-out is a sensible allowance and does not fight the existing stage text.
  2. Scope symmetry worth considering (optional, can be a follow-up): core/aidlc-common/stages/inception/application-design.md produces components.md, component-methods.md, services.md, and component-dependency.md, which have the same "code sneaks in" failure mode. Not a blocker for #396 as filed.

Mechanical must-fix before merge

  1. Version trio. core/tools/aidlc-version.ts is still "2.0.2" on the branch; v2 is at 2.2.0. Every user-visible PR bumps aidlc-version.ts, adds a matching ## [N.N.N] - YYYY-MM-DD heading + summary to CHANGELOG.md, and updates the README badge. tests/unit/t68-version-changelog-sync.test.ts enforces all three agree. Patches 2.2.1 through 2.2.13 are currently claimed by other open PRs, so at merge time this needs 2.2.14 or later depending on merge order (re-bump on rebase if collision).
  2. Regenerate dist/. You did regenerate dist at the branch base, which was correct, but v2 has moved through 2.1.0, 2.1.6, 2.1.7, 2.1.8, and 2.2.0 since then. After the rebase, run bun scripts/package.ts and commit the resulting drift across all four harness trees. bun scripts/package.ts --check is the CI gate and will fail without this.
  3. Once rebased, please confirm bun scripts/package.ts --check and the repo typecheck are clean locally.

Small housekeeping

  • The PR body spells the file functionnal-design.md; the actual filename is functional-design.md. In-repo everything is correct, just the description.

Rebase notes

Merge-base with v2 is f3ce1b8. The intervening changes to the three files (2.1.7 fde1e1a, which added the "if exists" input-fallback prose, and 2.1.0 e713c4f, which rerouted the record paths) touch different sections than your Constraints paragraph, so git merge-tree reports a clean auto-merge on all 15 files. Straight git rebase origin/v2 should resolve without hand-editing; the only real work is the regenerated dist and the version trio.

Cross-PR heads-up: your PR #404 also modifies nfr-design.md and infrastructure-design.md. Whichever of #402 and #404 lands second will need a small rebase and another bun scripts/package.ts pass, but they do not conflict textually today.

Happy to re-review as soon as the rebased branch is up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation github rules

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] Infrastructure-design and nfr-design artifacts contain implementation-level code

2 participants