feat: domain-design + contract-design restructure; infra-design conso… - #711
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). |
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:
|
557b18d to
847d397
Compare
|
Rebased onto latest v2 and worked through apackeer's round-2 findings. Fixed
Rebase / new v2 surface
Verification
Merge-tree against current |
leandrodamascena
left a comment
leandrodamascena
left a comment
There was a problem hiding this comment.
Re-review of 847d397e: the previously reported graph, artifact, harness, remediation, and test-fixture issues are substantially addressed. CI is green, but two behavioral blockers and six P2 gaps remain.
1. P1: Contract Design bypasses deterministic summary confirmation
core/aidlc-common/stages/inception/contract-design.md:9-13 omits summary_confirmation: required, despite defining a question flow before artifact generation.
Because checkSummaryConfirmationEvidence() returns success when that field is absent (core/tools/aidlc-lib.ts:2753-2755), Contract Design can complete without a human-backed consolidated-summary receipt. This removes the deterministic checkpoint that comparable question-bearing design stages enforce.
Add summary_confirmation: required and test that Contract Design cannot generate or complete before the receipt exists.
2. P1: incompatible state is rejected only when the user voluntarily runs doctor
The v8 check exists only inside the doctor implementation at core/tools/aidlc-utility.ts:2034-2049. Normal orchestration loads active state without validating its schema version.
I reproduced aidlc-orchestrate.ts next against a v7 state on this head. It exited 0 and emitted a normal load-steering directive:
{
"status": 0,
"kind": "load-steering",
"stage": "requirements-analysis"
}The workflow can therefore continue until it reaches the removed application-design row or needs the new domain-design/contract-design rows. This contradicts the changelog’s claim that stale state is rejected instead of failing later.
Validate State Version whenever an active state file is loaded by runtime/mutating commands, not only in doctor. Add a regression covering next or report against v7 state.
3. P2: the retained ADR log has no downstream consumer
domain-design produces decisions, but units-generation removed the previous required consume (core/aidlc-common/stages/inception/units-generation.md:18-24). No replacement consumer exists:
$ bun dist/claude/.claude/tools/aidlc-graph.ts consumers decisions
<no output>
Consequently the retained architectural decisions are absent from downstream directives. Restore the consume where those decisions influence decomposition, or document and test that decisions.md is intentionally archival only.
4. P2: composer selection omits the single-unit public API condition
Contract Design’s authoritative condition includes either an inter-unit boundary or a single unit exposing a public/external API (core/aidlc-common/stages/inception/contract-design.md:5).
The composer’s inclusion rule only mentions multiple integrating units (core/agents/aidlc-composer-agent.md:360). A composed single-unit public API workflow can therefore skip the only stage that owns its external contract.
Mirror the complete stage condition in the composer and add a single-unit external API composition test.
5. P2: the 32-to-33 topology sweep remains incomplete
The runtime protocol still mandates /32 progress output at core/aidlc-common/protocols/stage-protocol.md:277-292.
All six authored harness skills still advertise:
28 inline / 2 subagent / 1 pipeline / 1 mob
The compiled graph is actually:
29 inline / 2 subagent / 1 pipeline / 1 mob
Active user documentation also retains the removed Application Design stage, Delivery Planning 2.8, and the 32-stage topology. Representative locations:
docs/guide/04-phases-and-stages.md:3,158-211,417docs/guide/06-agents.md:109-270docs/guide/agents/architect-agent.md:14-28docs/reference/01-architecture.md:374,458,464harness/copilot/skills/aidlc/SKILL.md:195,241
Complete the authored-source sweep and regenerate dist.
6. P2: v8 state fixtures remain structurally stale
For example, tests/fixtures/state-completed.md:15-28,59-68 claims State Version 8 but:
- Declares 32 total stages.
- Omits Contract Design.
- Ends Inception at Delivery Planning without the new 2.8/2.9 shape.
t12-state-fixture-validation.test.ts:93-146 checks headings and the version field but never compares stage rows or totals with the compiled graph, so these inconsistent fixtures pass.
Update the fixtures and add graph-parity validation for their stage rows and totals.
7. P2: the documented upgrade leaves the removed runner installed
The changelog instructs users to re-copy the distribution and says /aidlc-application-design becomes /aidlc-domain-design. The documented installation mechanism uses merging cp -R commands (README.md:103-127), which do not remove files absent from the new distribution.
An upgraded project therefore retains the old Application Design runner, which invokes a stage no longer present in the graph.
Add an explicit removal/pruning instruction for renamed generated surfaces, or provide an upgrade command that synchronizes deletions.
8. P2: changelog release chronology is invalid
The new entries are dated:
2.6.1 - 2026-07-27
2.6.0 - 2026-07-22
They appear above the existing 2.5.62 - 2026-08-08 entry, and the PR commit was produced on August 11. Use the actual release date so version history remains chronological and auditable.
Verification
- Remote CI: green
bun scripts/package.ts --check: passed across all six harnesses- Typecheck: passed
- Lint: passed with three informational notices
- Focused branch slice: 232 passed, 3 failed
- The three
t272failures reproduce identically on basev2, so they are not attributed to this PR t134-swarm-referee: 18/18 passedgit diff --check: passed
Recommendation: keep CHANGES_REQUESTED until the two P1 runtime guarantees are fixed.
|
Siddhesh, this PR restructures Inception design into Domain/Contract Design, renames the Functional Design artifacts, and consolidates Infrastructure Design outputs. I reviewed I agree this should remain changes requested. I independently verified the following blockers: P1: Contract Design bypasses the summary-confirmation guard
Please add the field and a regression proving Contract Design cannot complete without a fresh human-backed consolidated-summary receipt. P1: State Version 8 is doctor-only, not a runtime gateThe version check exists only at {"status":0,"kind":"run-stage","stage":"requirements-analysis","steeringCount":1}That stale workflow can continue until routing reaches a removed/missing row, where P2: three new data-flow/harness gaps remain
P2: the rename/count/upgrade sweep is still incompleteThe active protocol still mandates
Please complete the authored-source/fixture sweep and regenerate Release housekeeping before merge: refresh the PR body (118 artifacts, six harnesses), re-date the 2.6.0/2.6.1 changelog entries, and renumber the new Verification:
|
cc98fe6 to
6eeffaf
Compare
|
Rebased onto latest v2 + review round 3 addressed Rebased over the new v2 commits (incl. #617 batch-parallel per-unit waves, the Cursor harness fixes, and #401 per-stage traceability). All conflicts resolved keeping v2's new behavior alongside our restructure. Conflict resolutions
Ripples from our restructure into v2's new tests
Verification
|
leandrodamascena
left a comment
leandrodamascena
left a comment
There was a problem hiding this comment.
Siddhesh, this PR restructures Inception design into Domain/Contract Design, renames the Functional Design artifacts, and consolidates Infrastructure Design outputs. I reviewed 6eeffaf and ran the affected suites through the official repository runner; t208, t209, t272, t280, and t281 are green with 50/50 assertions.
I agree this should remain changes requested. I independently verified the following blockers:
P1: Domain Design has no traceability upstream resolver
core/aidlc-common/stages/inception/domain-design.md:15-18 produces traceability, and lines 35-38 enable the traceability sensor. However, core/tools/aidlc-sensor-traceability.ts:291 still recognizes only the deleted application-design slug.
A real domain-design traceability run therefore reaches the unsupported-stage fallback at core/tools/aidlc-sensor-traceability.ts:445:
stage "domain-design" has no traceability upstream resolver
The existing regression also uses the obsolete stage and path at tests/unit/t281-sensor-traceability.test.ts:246-250, so it does not exercise the renamed stage.
Please update the resolver and test to use domain-design and prove that Domain Design traceability resolves its requirements/stories upstream correctly.
P2: Inception phase verification still reads the deleted Application Design path
core/aidlc-common/stages/inception/delivery-planning.md:147-160 defines the required Inception → Construction completeness audit, but line 153 still reads:
/inception/application-design/traceability.json
That path no longer exists after the rename. As written, Delivery Planning can omit unresolved Domain Design traceability findings from the phase-boundary verdict.
Please replace it with the Domain Design path and clarify whether Contract Design contributes traceability evidence to the same phase-boundary check.
P2: The release history publishes an unreleased intermediate version
CHANGELOG.md:4 introduces 2.6.1, CHANGELOG.md:12 introduces 2.6.0, and core/tools/aidlc-version.ts:4 publishes 2.6.1. Since 2.6.0 was never released upstream, this PR should be represented by one consolidated release entry/version under the repository’s current release-prep policy.
Please reconcile this during the required rebase.
P2: The Inception reference still describes the removed design model
docs/reference/04-stages/inception.md moves from Stage 2.7 directly to Stage 2.9 without documenting Contract Design. It also says Units Generation reads "all 5 files" from Domain Design at line 953, even though this PR replaces that model with consolidated components.md and decisions.md outputs.
Please add the Contract Design section and update the remaining descriptions of removed method-signature, service-definition, and dependency-matrix artifacts.
P3: Contract Design wiring is checked for only two harnesses
tests/unit/t280-contract-design-wiring.test.ts:87-99 validates Claude and Copilot only, while the repository ships seven harness projections.
Please drive this assertion from the shared harness matrix so missing Codex, Cursor, Kiro, Kiro IDE, or OpenCode wiring cannot pass unnoticed.
Merge blocker: the published branch conflicts with current v2
The PR is currently CONFLICTING/DIRTY. The conflicts include release files, the newer observability requirements/design flow, Infrastructure and NFR stages, documentation, tests, and generated harness trees.
Please rebase onto current v2, preserve the upstream observability artifacts while applying this consolidation, resolve authored sources first, and regenerate dist/ rather than manually resolving generated files.
…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 consolidated (inception + infra design outputs); 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.
6eeffaf to
8e4de44
Compare
|
all five findings on P1 — Domain Design traceability upstream resolver
P2 — Delivery Planning read a dead pathThe Inception→Construction phase-boundary audit read P2 — Unreleased intermediate version in the changelogConsolidated P2 — Inception reference still described the removed modelAdded the missing Stage 2.8: Contract Design section to P3 — Contract Design wiring checked only two harnesses
Rebase / observability reconciliationRebased onto Verification
Branch is currently 0 behind / 1 ahead of |
leandrodamascena
left a comment
leandrodamascena
left a comment
There was a problem hiding this comment.
Siddhesh, thanks for addressing the previous review in detail. I re-reviewed 8e4de44 and verified that the earlier blockers are resolved: Domain Design traceability is wired correctly, the phase-boundary path is fixed, Contract Design is documented, the harness-matrix coverage is expanded, stale plugin vocabulary is removed, the branch is rebased, and CI is green.
I do not see a remaining hard runtime blocker, so I am approving. I did identify the following follow-ups that should be addressed before merge:
P2: Functional Design uses two incompatible business-rule ID formats
core/aidlc-common/stages/construction/functional-design.md:121 instructs the agent to author rules as BR-NNN.
However, the same stage requires traceability targets in BRx.y format at lines 125-138, and the deterministic sensor recognizes only BRx.y:
- core/tools/aidlc-sensor-traceability.ts:63
- core/tools/aidlc-sensor-traceability.ts:499
- core/knowledge/aidlc-shared/verification.md:24
- core/aidlc-common/stages/construction/code-generation.md:214-226
Following the stage instructions therefore produces rule IDs that the traceability sensor cannot discover. Because the sensor is advisory, I am treating this as P2 rather than a merge-blocking P1.
Please select one canonical rule-ID format and apply it consistently across the stage instructions, product-agent guidance, traceability schema/examples, sensor, Code Generation consumers, and tests.
P2: Missing or empty State Version bypasses the runtime compatibility check
core/tools/aidlc-orchestrate.ts:576-578 treats an absent or empty State Version as current:
if (v.length === 0 || v === CURRENT_STATE_VERSION) return null;
Explicit v7 state is correctly rejected, and the new tests cover v7/v8. However, missing, empty, or malformed state can still reach next or report, while --doctor correctly treats the same state as invalid.
Please align runtime behavior with doctor and add regressions for missing, empty, and malformed versions.
P2: Release numbering skips the minor baseline
The PR now has one consolidated release entry, which resolves the previous duplicate-heading issue, but it still moves directly from upstream 2.5.75 to 2.6.1.
Unless a separate 2.6.0 release exists outside upstream history, the consolidated minor release should be 2.6.0. Please align the changelog heading, version constant, README badge, generated harness versions, and PR/commit text.
P3: Domain Design traceability vocabulary should match the consolidated catalogue
core/aidlc-common/stages/inception/domain-design.md:163-176 tells the agent to target a component, service, or public method and uses AuthService.login() as the example.
The new Domain Design source of truth formally identifies components and entities, but not services or public methods. Please constrain the example and target guidance to identifiers represented by components.md, or add mechanical validation for any additional target vocabulary.
P3: The Inception reference still has minor documentation drift
The reference chapter:
- omits contract-summary.md from Delivery Planning’s All Inception artifacts list;
- omits traceability.json from Domain Design outputs;
- says Units Generation writes All 3 artifacts, although traceability is a fourth output;
- retains removed Domain Design descriptions such as method signatures and service definitions.
Please align these sections with the authored stage contracts.
The implementation direction looks sound and the prior blockers are resolved. Approving with the follow-ups above.
|
I've merged i'll pickup the followups in a separate branch. |
…ity, 2.6.0 baseline Addresses the approving-review follow-ups on the merged domain/contract restructure (#711): - Canonical business-rule ID format is `BRx.y` (the format the traceability sensor recognizes). functional-design.md and the product-agent functional-design guide no longer instruct `BR-NNN`, which the sensor could not discover. - Runtime state-version guard aligned with `--doctor`: `next`/`report` now refuse a state whose State Version is missing, empty, or unparseable (not only an explicitly stale one). Regressions added in t282 for missing / empty / malformed versions. - Consolidated release is renumbered 2.6.1 -> 2.6.0 (the minor baseline; no 2.6.0 shipped upstream). Version constant, CHANGELOG heading, README badge, and generated harness versions realigned. - Domain Design traceability targets are constrained to components/entities in components.md (its source of truth); the example no longer uses a service method (AuthService.login()). - Inception reference (docs/reference/04-stages/inception.md) drift fixed: contract-summary.md added to Delivery Planning inputs, traceability.json added to Domain Design and Units Generation outputs (3 -> 4), a Contract Design (2.8) section added, and the removed method-signature/service-definition Domain Design descriptions replaced with the consolidated components.md/decisions.md.
…on guard (v2.6.2) Addresses the approving-review follow-ups on the merged domain/contract restructure (#711), then leandro's round-2 review on #751: - CHANGELOG: preserve the merged `## [2.6.1]` release history and add a new `## [2.6.2]` entry for these follow-ups. Version constant, README badge, and regenerated per-harness `dist/*/.../tools/aidlc-version.ts` copies are 2.6.2. - Business-rule ID format is canonical `BRx.y` (the format the traceability sensor recognizes). Updated the stage instructions (`functional-design.md`), the product-agent functional-design guide, AND the org-level stable-ID guidance (`core/memory/org.md`) so agents no longer receive the sensor- incompatible `BR-NNN` / `BR-003` example alongside the stage prose. - Runtime state-version guard aligned with `--doctor` and hardened against three fail-open paths the reviewers found: * a PRESENT-but-zero-byte `aidlc-state.md` is now rejected (was skipped because the call sites tested `if (stateContent)` — an empty string is falsy). Both `next` and `report` call sites now check `!== null`. * the regex uses `[ \t]*` (horizontal whitespace) rather than `\s*`, so an empty version value can no longer capture the leading `-` of the next state bullet and be mislabeled as the bogus token "-". * the captured version is validated as a bare integer; a non-numeric value is reported through the unparseable branch, and a FUTURE numeric version (e.g. v9) is reported as newer than this build's v8, not as predating it. Doctor's parallel `\s*` regex received the same `[ \t]*` fix. - Domain Design traceability targets are constrained to components/entities in `components.md` (its source of truth); example is `AuthComponent`, not `AuthService.login()`. - Inception reference documentation drift fixed: Contract Design (2.8) section added, `contract-summary.md` listed in Delivery Planning inputs, `traceability.json` listed in Domain Design and Units Generation outputs, Units Generation output count corrected from 3 to 4 in BOTH the Outputs table AND its generation-step prose. Regressions added in t282: exact-remediation assertions (asserting the unparseable branch rather than either branch), a zero-byte state file case for both `next` and `report`, and a future-version (v9) case that asserts the "newer than the current" message rather than "predates".
…on guard (v2.6.2) Addresses the follow-up review items from the merged domain/contract restructure (#711), then leandro's rounds 2 and 3 review on #751. This is a correctness/consistency patch on top of 2.6.1; no artifact or stage-graph changes. - CHANGELOG: preserve the merged `## [2.6.1]` release history and add a new `## [2.6.2]` entry for these follow-ups. Version constant, README badge, and regenerated per-harness `dist/*/.../tools/aidlc-version.ts` copies are 2.6.2. - Business-rule ID format is canonical `BRx.y` (the format the traceability sensor recognizes). Updated the stage instructions (`functional-design.md`), the product-agent functional-design guide, AND the org-level stable-ID guidance (`core/memory/org.md`) so agents no longer receive the sensor- incompatible `BR-NNN` / `BR-003` example alongside the stage prose. - Runtime state-version guard and doctor now share ONE classifier (`classifyStateVersion` in `aidlc-lib.ts`), so they can no longer disagree on whether a state is unparseable / past / future / ok: * a PRESENT-but-zero-byte `aidlc-state.md` is rejected (was skipped because the call sites tested `if (stateContent)` — an empty string is falsy). Both `next` and `report` now check `!== null`. * the parser uses `[ \t]*` (horizontal whitespace) rather than `\s*`, so an empty version value can no longer capture the leading `-` of the next state bullet and be mislabeled as the bogus token "-". * the value line is anchored to end-of-line, so trailing content such as `State Version: 8 garbage` is routed through the unparseable branch rather than accepted as v8. * the captured version is validated as a bare integer; a non-numeric value is reported through the unparseable branch, and a FUTURE numeric version (e.g. v9) is reported as newer than this build's v8 with upgrade guidance (not archive-and-reinit). Doctor now emits per-branch failing rows (`state version readable` / `state version current` / `state version compatible`) mirroring the runtime classification. - Domain Design traceability targets are constrained to components/entities in `components.md` (its source of truth); example is `AuthComponent`, not `AuthService.login()`. - Inception reference documentation drift fixed: Contract Design (2.8) section added, `contract-summary.md` listed in Delivery Planning inputs, `traceability.json` listed in Domain Design and Units Generation outputs, Units Generation output count corrected from 3 to 4 in the reference doc AND in the authored stage prose (`units-generation.md` Step 6). Regressions added in t282: exact-remediation assertions (asserting the unparseable branch rather than either branch), zero-byte state file cases for both `next` and `report`, a future-version (v9) case that asserts the "newer than the current" message, trailing-content cases for both `next` and `report`, and matching doctor cases (malformed → readable-row, future → compatible-row, trailing → readable-row).
…on guard (v2.6.2) Addresses the follow-up review items from the merged domain/contract restructure (#711), then leandro's rounds 2 and 3 review on #751. This is a correctness/consistency patch on top of 2.6.1; no artifact or stage-graph changes. - CHANGELOG: preserve the merged `## [2.6.1]` release history and add a new `## [2.6.2]` entry for these follow-ups. Version constant, README badge, and regenerated per-harness `dist/*/.../tools/aidlc-version.ts` copies are 2.6.2. - Business-rule ID format is canonical `BRx.y` (the format the traceability sensor recognizes). Updated the stage instructions (`functional-design.md`), the product-agent functional-design guide, AND the org-level stable-ID guidance (`core/memory/org.md`) so agents no longer receive the sensor- incompatible `BR-NNN` / `BR-003` example alongside the stage prose. - Runtime state-version guard and doctor now share ONE classifier (`classifyStateVersion` in `aidlc-lib.ts`), so they can no longer disagree on whether a state is unparseable / past / future / ok: * a PRESENT-but-zero-byte `aidlc-state.md` is rejected (was skipped because the call sites tested `if (stateContent)` — an empty string is falsy). Both `next` and `report` now check `!== null`. * the parser uses `[ \t]*` (horizontal whitespace) rather than `\s*`, so an empty version value can no longer capture the leading `-` of the next state bullet and be mislabeled as the bogus token "-". * the value line is anchored to end-of-line, so trailing content such as `State Version: 8 garbage` is routed through the unparseable branch rather than accepted as v8. * the captured version is validated as a bare integer; a non-numeric value is reported through the unparseable branch, and a FUTURE numeric version (e.g. v9) is reported as newer than this build's v8 with upgrade guidance (not archive-and-reinit). Doctor now emits per-branch failing rows (`state version readable` / `state version current` / `state version compatible`) mirroring the runtime classification. - Domain Design traceability targets are constrained to components/entities in `components.md` (its source of truth); example is `AuthComponent`, not `AuthService.login()`. - Inception reference documentation drift fixed: Contract Design (2.8) section added, `contract-summary.md` listed in Delivery Planning inputs, `traceability.json` listed in Domain Design and Units Generation outputs, Units Generation output count corrected from 3 to 4 in the reference doc AND in the authored stage prose (`units-generation.md` Step 6). Regressions added in t282: exact-remediation assertions (asserting the unparseable branch rather than either branch), zero-byte state file cases for both `next` and `report`, a future-version (v9) case that asserts the "newer than the current" message, trailing-content cases for both `next` and `report`, and matching doctor cases (malformed → readable-row, future → compatible-row, trailing → readable-row).
…on guard (v2.6.2) (#751) Addresses the follow-up review items from the merged domain/contract restructure (#711), then leandro's rounds 2 and 3 review on #751. This is a correctness/consistency patch on top of 2.6.1; no artifact or stage-graph changes. - CHANGELOG: preserve the merged `## [2.6.1]` release history and add a new `## [2.6.2]` entry for these follow-ups. Version constant, README badge, and regenerated per-harness `dist/*/.../tools/aidlc-version.ts` copies are 2.6.2. - Business-rule ID format is canonical `BRx.y` (the format the traceability sensor recognizes). Updated the stage instructions (`functional-design.md`), the product-agent functional-design guide, AND the org-level stable-ID guidance (`core/memory/org.md`) so agents no longer receive the sensor- incompatible `BR-NNN` / `BR-003` example alongside the stage prose. - Runtime state-version guard and doctor now share ONE classifier (`classifyStateVersion` in `aidlc-lib.ts`), so they can no longer disagree on whether a state is unparseable / past / future / ok: * a PRESENT-but-zero-byte `aidlc-state.md` is rejected (was skipped because the call sites tested `if (stateContent)` — an empty string is falsy). Both `next` and `report` now check `!== null`. * the parser uses `[ \t]*` (horizontal whitespace) rather than `\s*`, so an empty version value can no longer capture the leading `-` of the next state bullet and be mislabeled as the bogus token "-". * the value line is anchored to end-of-line, so trailing content such as `State Version: 8 garbage` is routed through the unparseable branch rather than accepted as v8. * the captured version is validated as a bare integer; a non-numeric value is reported through the unparseable branch, and a FUTURE numeric version (e.g. v9) is reported as newer than this build's v8 with upgrade guidance (not archive-and-reinit). Doctor now emits per-branch failing rows (`state version readable` / `state version current` / `state version compatible`) mirroring the runtime classification. - Domain Design traceability targets are constrained to components/entities in `components.md` (its source of truth); example is `AuthComponent`, not `AuthService.login()`. - Inception reference documentation drift fixed: Contract Design (2.8) section added, `contract-summary.md` listed in Delivery Planning inputs, `traceability.json` listed in Domain Design and Units Generation outputs, Units Generation output count corrected from 3 to 4 in the reference doc AND in the authored stage prose (`units-generation.md` Step 6). Regressions added in t282: exact-remediation assertions (asserting the unparseable branch rather than either branch), zero-byte state file cases for both `next` and `report`, a future-version (v9) case that asserts the "newer than the current" message, trailing-content cases for both `next` and `report`, and matching doctor cases (malformed → readable-row, future → compatible-row, trailing → readable-row).
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).