feat: domain-design + contract-design restructure; infra-design conso… - #711
feat: domain-design + contract-design restructure; infra-design conso…#711SiddhJog wants to merge 1 commit into
Conversation
leandrodamascena
left a comment
leandrodamascena
left a comment
There was a problem hiding this comment.
Thanks for the substantial design and artifact-model improvements. The focused suites and package parity pass, but I found four behavioral/documentation gaps plus the current merge conflict.
1. P1: upgrading can strand in-flight workflows
The latest 2.6.1 entry tells users to re-copy the shell, but the graph removes application-design without an alias or state migration. A workflow whose Current Stage is still application-design reaches emitRunStageForSlug() and fails because that slug no longer exists.
References: CHANGELOG.md:6, core/tools/aidlc-orchestrate.ts:2525-2559, :2785-2790.
Please migrate/alias persisted state, or make the latest upgrade instructions explicitly prevent shell replacement while an old-schema workflow is active.
2. P1: Code Generation does not receive contract-summary
Code Generation reads contract-summary.md in its stage prose, but does not declare contract-summary in consumes. Consequently it is absent from the resolved directive and from the architecture reviewer’s permitted shared-contract context.
Reproduction:
$ bun dist/claude/.claude/tools/aidlc-graph.ts consumers contract-summary
functional-design
References: core/aidlc-common/stages/construction/code-generation.md:16-32, :75; core/aidlc-common/protocols/stage-protocol.md:964; core/knowledge/aidlc-architecture-reviewer-agent/reviewing.md:27.
Please add contract-summary as an optional consume and add a directive-resolution test.
3. P2: Workshop always skips Contract Design
The workshop scope says it runs the full Inception design pass and executes Units Generation, but contract-design excludes workshop. A multi-unit workshop therefore cannot run the new stage even when its execution condition is satisfied.
References: core/aidlc-common/stages/inception/contract-design.md:28-31, core/scopes/aidlc-workshop.md:24-38, dist/claude/.claude/tools/data/scope-grid.json:315-318.
Please include workshop, or document and enforce the intended alternative contract source.
4. P2: current surfaces still advertise the removed graph
Several active and user-facing surfaces still describe 32 stages, Inception 2.1-2.8, and Application Design. This includes the Claude session announcement, scope descriptions, agent metadata, depth guidance, and Delivery Planning’s own numbering.
Representative references:
harness/claude/settings.json:3core/scopes/aidlc-enterprise.md:28core/scopes/aidlc-feature.md:27core/aidlc-common/protocols/stage-protocol.md:725-737core/aidlc-common/stages/inception/delivery-planning.md:80
Please complete the repository-wide rename/count/numbering sweep and regenerate dist/.
Merge blocker
The PR is currently CONFLICTING / DIRTY and is based on 2.5.36, while v2 has advanced. It needs a rebase and version/changelog reconciliation.
Verification
- 30 affected smoke/unit test files passed.
- 13 affected integration test files passed.
bun scripts/package.ts --checkpassed.git diff --checkpassed.- Remote CI is green.
I recommend keeping this at CHANGES_REQUESTED until these gaps and the merge conflict are resolved.
apackeer
left a comment
apackeer
left a comment
There was a problem hiding this comment.
Additional review findings beyond the existing changes-requested review. The Domain -> Units -> Contract -> Delivery direction is sound; these comments focus on responsibilities and end-to-end wiring that the core-stage change still needs.
One non-inline plugin issue: plugins/test-pro/contributions/construction/build-and-test.md:74 still asks for the removed business-rules artifact instead of rules, so its requirement traceability can omit the new source of truth.
The focused smoke/unit/integration slice passed (16 files, 472 assertions), but both new stages remain behaviorally uncovered in tests/.coverage-registry.json.
|
|
||
| ## [2.6.0] - 2026-07-22 | ||
|
|
||
| Inception design output restructure. Application Design becomes **Domain Design** (2.6): it now produces a single consolidated `components.md` — a fenced `yaml` component catalogue (source of truth) plus a derived human view (mermaid diagram + summary/ownership/rationale tables) — instead of the five separate `components`/`component-methods`/`services`/`component-dependency`/`decisions` artifacts. Entities are captured at the ownership level (identifier, attributes, cross-component references, external dependencies), with the full schema still deferred to Functional Design. A new **Contract Design** stage (2.8, CONDITIONAL, produces `contract-summary.md`) formalises inter-unit contracts so teams can build in parallel; Delivery Planning moves to 2.9. Functional Design's outputs are restructured into `entities.md` + `rules.md` (fenced `yaml` sources of truth) + `functional-spec.md` (derived human view), replacing `business-logic-model`/`business-rules`/`domain-entities`. The `aidlc-architect-agent` is reframed to own the logical/application concerns (domain + contract design) distinct from infrastructure. **Breaking for consumers that read inception design artifacts:** the five old app-design artifact names and the three old functional-design names are gone — read `components.md`, `contract-summary.md`, `entities.md`, `rules.md`, `functional-spec.md` instead. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; existing in-flight workflows on the old stage names should finish on the prior shell. |
There was a problem hiding this comment.
P1 - upgrade can strand any v7 workflow crossing the changed Inception graph. The state schema still reports version 7, so an old state passes --doctor even though it has an application-design row and no domain-design or contract-design rows. When the new graph advances to one of those slugs, setCheckbox() is a no-op for the missing row but Current Stage is still updated; report then fails with Stage "..." is not present in the state file. The active-application-design case also fails because that slug no longer exists. Please add a state migration/alias or bump the state version so old states are rejected, and make the 2.6.0/2.6.1 upgrade instruction unambiguous.
| reviewer: aidlc-architecture-reviewer-agent | ||
| reviewer_max_iterations: 2 | ||
| produces: | ||
| - contract-summary |
There was a problem hiding this comment.
P1 - the approved contract is not propagated through the workflow. aidlc-graph consumers contract-summary currently returns only functional-design. Delivery Planning cannot map contract ownership/blockers to Bolts or the walking skeleton; NFR and Infrastructure Design do not receive the retry/failure and integration-mechanism decisions; and Code Generation omits the artifact from consumes even though its body explicitly says to read it. This is especially risky for unit-major design and autonomous code-generation batches, which need one shared boundary contract. Please wire contract-summary into the relevant downstream stage contracts and read steps.
| - **domain-entities.md**: Entities, relationships, data structures, attributes, lifecycle states, and entity interaction patterns | ||
| - **entities.md**: The entity model. Carries a fenced ```yaml source-of-truth block listing each entity with its description, attributes (name, logical type, required/unique, references, allowed values, defaults, min/max, constraints), entity-level constraints, and relationships (cardinality + direction). Follow the block with a short human-readable summary of the entity set. | ||
| - **rules.md**: The business rules. Carries a fenced ```yaml source-of-truth block listing each numbered rule (`id: BR-NNN`) with its statement, category (validation/authorization/constraint/calculation/policy), what it applies to, trigger, logic (IF…THEN in plain language), violation behaviour, and source (FR-n/NFR-n). Follow the block with a short human-readable rules summary table. | ||
| - **functional-spec.md**: The derived human view. An entity-relationship `mermaid` diagram (reflecting entities.md — the YAML is source of truth), state machines for lifecycle entities, workflows as numbered step sequences, and a rules summary. Everything here is derived from entities.md and rules.md. |
There was a problem hiding this comment.
P2 - functional-spec.md cannot be fully derived from the declared sources. entities.md and rules.md do not define workflow sequences or state-transition models, yet this requires workflows and state machines and says everything is derived from those two files. UI units make the contradiction concrete: produces_kinds gives them functional-spec but neither entities nor rules. Please add authoritative workflow/state schemas or define functional-spec as an independently authoritative artifact with explicit upstream sources.
| slug: contract-design | ||
| phase: inception | ||
| execution: CONDITIONAL | ||
| condition: Execute when the system decomposes into more than one unit that must integrate. Skip for a single-unit system where there are no inter-unit boundaries to formalise. |
There was a problem hiding this comment.
P2 - single-unit public APIs no longer have a contract-design owner. The removed Application Design stage specified component public interfaces and service communication contracts. Domain Design deliberately omits interfaces, this condition skips Contract Design for every single-unit system, and Functional Design declares no API-spec output. A single deployable API can therefore reach Code Generation with no approved external contract. Please broaden this condition to formal contracts rather than only inter-unit contracts, or assign public API specifications to another explicit stage/artifact.
| - **Component Summary** — a table: `| Component | Purpose | Depends On | Dependents | Entities Owned |`. | ||
| - **Entity Ownership** — a table: `| Entity | Owning Component | Identifier | Attributes | References |`. | ||
| - **External Dependencies** — a table: `| Component | Dependency | Kind | Purpose |`. | ||
| - **Rationale** — a table explaining why each component is a separate building block (distinct lifecycle, distinct concern, distinct data ownership, distinct change rate — pick what applies). |
There was a problem hiding this comment.
P2 - removing decisions.md leaves the mandatory ADR contract unsatisfied. core/memory/phases/inception.md still requires ADRs with Context, Decision, Consequences, and Alternatives Rejected, and the architect persona still says it produces ADRs for significant choices. This rationale table records component-boundary reasoning but is not an ADR and has no place for the required structure. Please retain an explicit decisions/ADR artifact or update the phase rule and persona with a concrete replacement location and schema.
| - The Q&A file path (e.g., `<record>/<phase>/<stage>/<stage>-questions.md`) | ||
| - All artifact file paths produced by the stage (the `produces` artifacts) | ||
| - For a per-unit stage (`directive.unit` present), also the resolved paths in `directive.consumes` (all upstream artifacts the stage declares, including the shared inception contracts that pin cross-unit boundaries - `components.md`, `component-methods.md`, `services.md`, `unit-of-work.md` - paths only, per the context-budget rule) | ||
| - For a per-unit stage (`directive.unit` present), also the resolved paths in `directive.consumes` (all upstream artifacts the stage declares, including the shared inception contracts that pin cross-unit boundaries - `components.md`, `contract-summary.md`, `unit-of-work.md` - paths only, per the context-budget rule) |
There was a problem hiding this comment.
P2 - the new Contract Design reviewer is not passed the evidence it must verify. This protocol passes directive.consumes only when directive.unit exists. Contract Design is workflow-level, so its architecture reviewer receives the produced summary but not the unit DAG, unit definitions, requirements, or component catalogue used to justify it. Pass declared upstream artifacts to non-per-unit reviewers as well, or add a contract-stage-specific evidence rule.
| * Stage `application-design` renamed to `domain-design` (2.6); its per-stage runner becomes `/aidlc-domain-design`. Its `produces` collapses from five artifacts to a single `components` (`components.md`). | ||
| * NEW stage `contract-design` (2.8, CONDITIONAL — skips for single-unit systems); per-stage runner `/aidlc-contract-design`; produces `contract-summary`. Delivery Planning renumbered 2.8 → 2.9. The framework now ships 33 stages (was 32). | ||
| * Functional Design `produces` renamed: `business-logic-model` → `functional-spec`, `business-rules` → `rules`, `domain-entities` → `entities`. Downstream consumes in `nfr-requirements`, `nfr-design`, `infrastructure-design`, and `code-generation` were rewired accordingly. | ||
| * Stage frontmatter now honours an authored `number:` / `name:` field (the compiler prefers it over the pinned graph value), so a renamed or inserted stage controls its own display number without a manual graph edit. |
There was a problem hiding this comment.
P2 - this describes compiler behavior that is not implemented. compileStageGraph() explicitly keeps the pinned number and name for an existing slug. For new slugs, authored number: is only a relative tie-break hint; the engine assigns the next contiguous index, so the authored absolute number never overrides the graph. Please either implement this stated contract with collision/ordering safeguards or revise the release note to match the current pinning behavior.
31ba59f to
0510a82
Compare
|
Rebased onto latest v2 (2.5.55) and addressed all findings. P1State schema bumped 7→8 — pre-2.6 states now fail --doctor with a clear message instead of breaking on renamed rows (leandro #1, apackeer #1). P2workshop added to contract-design scopes (leandro #3). Verified: package --check, coverage --check, t68 green. Residual test failures are known-environmental (t248/t255/t92), SDK-gated, or pre-existing t260 cases (confirmed identical on clean v2). |
…lidation (v2.6.1) Inception design-output restructure plus infrastructure-design consolidation. Domain/Contract (was 2.6.0): - application-design -> domain-design (2.6): five artifacts collapse to a single consolidated components.md — a fenced yaml component catalogue (source of truth: behaviour, responsibilities, depends_on/dependents, external_dependencies, owned entities with identifier + cross-component references) plus a derived human view (mermaid + summary/ownership/rationale) - NEW contract-design stage (2.8, CONDITIONAL): formalises inter-unit contracts so teams build in parallel; produces contract-summary. Delivery Planning -> 2.9 - functional-design outputs -> entities / rules / functional-spec - aidlc-architect-agent reframed to own domain + contract design - compiler: honour authored frontmatter number:/name: over the stale graph pin; bump maxIndexByPhasePrefix on every number path; duplicate-number guard Infra consolidation (was 2.6.1): - infrastructure-design five artifacts -> three: deployment + services + shared fold into a tabular infrastructure-specification.md; monitoring-design and cicd-pipeline stay dedicated (Operation stages consume them independently) - consumers rewired (code-generation, observability-setup, incident-response, environment-provisioning, deployment-pipeline) Artifact registry 122 -> 117; stages 32 -> 33. Two code-review rounds addressed (12 findings). All tiers green; package --check clean across all 5 harness trees. Breaking for consumers of inception design + infra artifacts — see CHANGELOG.
0510a82 to
557b18d
Compare
|
Round-2 verification of I am keeping this at changes requested for the following: P1: two deterministic test regressions from the artifact rename
Both are branch-caused: P2: workflow-level reviewer evidence is not wired through the harnesses
P2: the state-upgrade remediation points at a retired layoutThe new doctor check works, but its fix text tells users to run Please provide a valid archive/restart command and add a regression test for "v7 state -> failing doctor row + non-zero exit". Current tests only pin the happy-path State Version 8 text. P2: the repository-wide semantics and numbering sweep is incomplete
Merge/rebase blockersThe PR is currently
Verification:
|
3 participants
Summary
Restructures the Inception design outputs and consolidates Infrastructure Design, rebased onto current v2 (2.5.36) as a single commit. Ships as v2.6.1.
Domain / Contract design
application-design→domain-design(2.6): the five artifacts (components,component-methods,services,component-dependency,decisions) collapse into a single consolidatedcomponents.md— a fenced```yamlcomponent catalogue (source of truth: behaviour, responsibilities, depends_on/dependents, external_dependencies, owned entities with identifier + cross-component references) plus a derived human view (mermaid + summary/ownership/rationale tables).contract-designstage (2.8, CONDITIONAL — skips single-unit systems): formalises inter-unit contracts so teams build in parallel; producescontract-summary. Delivery Planning → 2.9.functional-designoutputs →entities/rules/functional-spec(yaml sources of truth + derived human view).aidlc-architect-agentreframed to own the logical/application concerns (domain + contract design), distinct from infrastructure.Infrastructure design consolidation
infrastructure-designfive artifacts → three:deployment-architecture+infrastructure-services+shared-infrastructurefold into a tabularinfrastructure-specification.md;monitoring-designandcicd-pipelinestay dedicated (Operation stages consume them independently). Closer to the pre-v2 single-infra-doc shape.Numbering
Uses v2's engine-driven numbering (no authored
number:frontmatter): the rename is carried by thestage-graph.jsonpin (domain-design@2.6),contract-designand the renumbereddelivery-planning@2.9ride the pins, and v2's numeric topo-tiebreak keeps ordering consistent.Breaking changes
Consumers that read Inception design or infrastructure artifacts must migrate: the five app-design names, three functional-design names, and
deployment-architecture/infrastructure-services/shared-infrastructureare gone. Readcomponents.md,contract-summary.md,entities.md/rules.md/functional-spec.md, andinfrastructure-specification.mdinstead. See CHANGELOG 2.6.0/2.6.1.Counts
Review
Two
/code-review --effort highrounds addressed (12 findings). During the v2 rebase, four v2-owned surfaces were reconciled with the rename: thears-priors.jsoncomposer data, the05-scopes-and-depth.mdstage-by-scope matrix, and two auto-merged test helpers.Testing
bun scripts/package.ts --checkclean across all 5 harness trees.t248-codekb-scope-diffandt255-workspace-sync, both v2-owned git/LFS/worktree integration tests with zero overlap with this change (verified: our diff touches neither subject, and neither test references any renamed stage/artifact).