@afokapu/atdd-bun 0.10.42 → 0.10.44

package/conventions/_profiles/coder.yaml

@@ -114,6 +114,16 @@ conventions:
   - rule_id: "planner.wagon.features"
     path: "planner-nodes/nodes/planner.wagon.features.convention.yaml"
 relationships:
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "finish_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "final behavioral reconciliation follows review-ready RED, GREEN, REFACTOR, and full-profile proof"
+    source_ref: "atdd-bun.review.behavioral-reconciliation"
+    strength: "critical"
+    target_ref: "coder.bun.phase-discipline"
+    type: "follows"
   - confidence: 1
     constraint: "mandatory"
     control: "internal"

package/conventions/_profiles/workflow.yaml

@@ -2,6 +2,18 @@ schema_version: "1.0.0"
 profile: "workflow"
 implementations: []
 conventions:
+  - rule_id: "atdd-bun.review.behavioral-reconciliation"
+    path: "conventions/atdd-bun.review/atdd-bun.review.behavioral-reconciliation.convention.yaml"
   - rule_id: "atdd-workflow.workflow.lifecycle"
     path: "../atdd-workflow/conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml"
-relationships: []
+relationships:
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "finish_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "final behavioral reconciliation follows review-ready RED, GREEN, REFACTOR, and full-profile proof"
+    source_ref: "atdd-bun.review.behavioral-reconciliation"
+    strength: "critical"
+    target_ref: "coder.bun.phase-discipline"
+    type: "follows"

package/conventions/atdd-bun.review/atdd-bun.review.behavioral-reconciliation.convention.yaml

@@ -0,0 +1,188 @@
+schema_version: 1.1.0
+rule_id: atdd-bun.review.behavioral-reconciliation
+kind: policy
+status: active
+name: Final review reconciles delivered behavior with declared intent
+statement: >-
+  Before a delivery may be accepted after its deterministic CI and convention gates pass, a final reviewer
+  MUST reconcile the observable behavior of the assembled system with the declared intent that motivated the
+  work. Passing tests, a clean diff, and green convention checks are supporting evidence; none is a substitute
+  for observing that the delivered behavior matches the plan. The review MUST establish expected behavior
+  from the relevant acceptance, wagon, train, interlocking, journey, and delivery criteria before relying on
+  implementation details; exercise the highest meaningful assembled boundary; compare the observed result
+  with that intent and its executable proofs; and return APPROVE, RETURN, or ESCALATE. A material mismatch
+  blocks delivery.
+terms:
+- term_id: final_behavioral_review
+  text: >-
+    the post-CI review performed after implementation and guided refactoring are complete. Its purpose is to
+    determine whether the assembled running system exhibits the behavior the delivery originally intended,
+    rather than to repeat RED, GREEN, REFACTOR, or static code-quality review.
+- term_id: declared_intent
+  text: >-
+    the behavior the delivery is expected to produce, reconstructed from the authoritative planning and
+    delivery artifacts in scope: acceptance criteria, wagon responsibilities, train sequence, interlocking
+    routes, journey behavior, and task or delivery criteria when available.
+- term_id: assembled_boundary
+  text: >-
+    the highest meaningful real boundary through which the intended behavior can be exercised: for example a
+    browser journey, exposed HTTP or runtime boundary, production interlocking and train path, or another
+    assembled product-facing interface. It is not an internal function selected merely because it is easier
+    to invoke.
+- term_id: behavioral_reconciliation
+  text: >-
+    the comparison between declared intent, executable proof, and observed runtime behavior. Reconciliation
+    succeeds only when those three describe the same material behavior and no required outcome is missing or
+    materially contradicted.
+- term_id: review_evidence
+  text: >-
+    durable evidence recording the intent sources considered, boundary exercised, observations obtained,
+    discrepancies found, and final review decision. CI status, tests, screenshots, traces, runtime output, or
+    other artifacts may support the judgment but do not replace it.
+- term_id: review_decision
+  text: >-
+    APPROVE when declared intent, executable proof, and observed behavior materially agree; RETURN when
+    required behavior is missing, wrong, unreachable, unexpectedly changed, or proved by tests that no longer
+    correspond to the plan; ESCALATE when the authoritative intent is ambiguous, contradictory, or must itself
+    change before correctness can be judged.
+content:
+  summary: >-
+    Close the ATDD delivery loop by independently reconciling original intent with the observable behavior of
+    the assembled system after all deterministic gates are green.
+  normative_text: |
+    Final review is a semantic delivery gate, not another implementation phase.
+
+    RED constructed executable proof of the intended behavior. GREEN implemented the smallest compliant
+    behavior. REFACTOR improved the implementation while preserving that behavior. Deterministic CI and ATDD
+    Bun profiles establish that the resulting delivery satisfies the machine-checkable obligations. Final
+    review answers the remaining question: does the assembled system actually behave as the delivery intended?
+
+    Deterministic gates are prerequisites. Do not begin final behavioral review while required CI, tests, type
+    checks, security checks, or active strict convention checks are failing. A failing deterministic gate is
+    returned to the responsible implementation phase before semantic review consumes additional reasoning
+    capacity.
+
+    Establish the behavioral oracle from intent before studying implementation details deeply. Read the
+    authoritative artifacts relevant to the delivery: its acceptance criteria, wagon responsibilities, train
+    sequence, interlocking route decisions, exposed journey, and delivery criteria when available. State the
+    behavior that should be observable if the delivery is correct.
+
+    Do not derive expected behavior from the PR diff, implementation, or test body. Those are evidence of what
+    was built, not authority for what was supposed to be built. This ordering protects the review from
+    accepting plan/test/implementation drift merely because implementation and tests agree with each other.
+
+    Choose the highest meaningful assembled boundary that can demonstrate the declared behavior. For a
+    human-facing journey, exercise the real user-facing journey. For an API or runtime behavior, enter through
+    the exposed assembled boundary. For routed behavior, exercise the production interlocking and train path
+    when that routing is material to the claim. Do not move inward to an internal function merely because it is
+    easier to invoke.
+
+    Exercise the behavior with the minimum inputs necessary to establish the claim, then observe externally
+    meaningful consequences. Prefer user-visible outcomes, API responses, persisted effects, emitted events,
+    route selection followed by its business outcome, or other effects named by the plan. Internal calls,
+    implementation objects, mocks, or descriptive tokens are not substitutes for the declared observable
+    result.
+
+    Reconcile three sources independently:
+
+      1. DECLARED INTENT
+         What behavior do the authoritative plan and delivery criteria require?
+
+      2. EXECUTABLE PROOF
+         What behavior do the acceptance, smoke, route, train, and journey tests actually prove?
+
+      3. OBSERVED RUNTIME
+         What does the assembled system actually do when exercised through the appropriate real boundary?
+
+    All three must materially agree. Passing tests alone are insufficient because a test may have drifted with
+    the implementation. Runtime behavior alone is insufficient if it no longer satisfies the declared intent.
+    A correct plan with an unexercised or unreachable implementation is also incomplete.
+
+    Look specifically for:
+      * required behavior that is missing,
+      * intended behavior that cannot be reached through the assembled application,
+      * materially unexpected behavior introduced by the delivery,
+      * an interlocking condition selecting the wrong train,
+      * a train whose sequence produces a different business outcome than declared,
+      * a journey whose final user-visible result differs from its intended outcome,
+      * tests that pass while proving a behavior different from the plan,
+      * acceptance or planning artifacts silently changed to match the implementation rather than an explicitly
+        authorized change in intent.
+
+    Inspect the PR diff and implementation after the expected behavior has been established. Use them to
+    explain discrepancies, understand risk, or determine whether an observed result is trustworthy. Do not
+    reopen naming, decomposition, abstraction, complexity, formatting, or other design questions that already
+    passed their governing phase unless they provide concrete evidence of a behavioral defect or delivery risk.
+
+    The reviewer MUST produce a durable decision:
+
+      APPROVE
+        Declared intent, executable proof, and observed behavior materially agree. Required behavior is
+        reachable through the assembled system and no material unintended behavior was found within the
+        reviewed scope.
+
+      RETURN
+        Required behavior is missing, wrong, unreachable, materially contradicted, or the executable proof
+        does not correspond to the declared intent. Return the delivery with the concrete behavioral
+        discrepancy and evidence.
+
+      ESCALATE
+        The authoritative intent is ambiguous, contradictory, or fulfilling the observed need requires
+        changing agreed product behavior. Do not silently redefine the plan during final review.
+
+    Final review is not permission to expand scope or redesign the implementation. Its job is to decide whether
+    the delivered behavior is the intended behavior.
+  fix_hint: |
+    Re-run final review outside-in.
+
+    Intent:
+      * read the relevant acceptance, wagon, train, interlocking, journey, and delivery criteria,
+      * state the externally meaningful behavior expected from this delivery before relying on the PR diff or
+        implementation as an oracle.
+
+    Exercise:
+      * wait until deterministic CI and active strict ATDD Bun gates are green,
+      * choose the highest meaningful assembled boundary for the declared behavior,
+      * exercise the real production path with the minimum inputs necessary to demonstrate it.
+
+    Observe:
+      * record the externally meaningful result,
+      * include supporting runtime evidence such as a browser result, response, persisted effect, emitted
+        event, trace, route/train result plus business outcome, or equivalent proof.
+
+    Reconcile:
+      * compare declared intent with the executable tests,
+      * compare both with the behavior actually observed,
+      * look for missing behavior, unexpected behavior, unreachable paths, or semantic drift between plan,
+        tests, and implementation.
+
+    Decide:
+      * APPROVE only when intent, proof, and runtime materially agree,
+      * RETURN with the concrete discrepancy when they do not,
+      * ESCALATE when the intent itself is ambiguous or requires an authorized change.
+
+    Avoid:
+      * treating green CI as the final behavioral judgment,
+      * treating a passing E2E test as proof without checking what it actually proves,
+      * deriving expected behavior from the implementation,
+      * reviewing only the lines changed in the PR,
+      * redoing style or refactoring review without behavioral evidence,
+      * changing the plan merely to make the delivered implementation appear correct.
+  exceptions:
+  - >-
+    A delivery that intentionally changes no externally observable behavior still requires reconciliation. The
+    reviewer may establish that the intended invariant is "no behavioral change" and use the relevant assembled
+    proofs to verify that invariant rather than inventing a new user journey.
+  - >-
+    When the intended behavior cannot be exercised safely against production dependencies, use the highest
+    faithful environment and boundary authorized by the plan. Do not approve solely from static inspection
+    when the claimed behavior requires runtime observation.
+  - >-
+    Ambiguous or contradictory declared intent is not a reviewer failure and MUST NOT be resolved by inference.
+    Return ESCALATE so the responsible planning authority can settle it.
+metadata:
+  aliases:
+  - ATDD-BUN-REVIEW-BEHAVIORAL-RECONCILIATION-001
+  severity: 4
+implementation:
+  type: none

package/integrity.json

@@ -1,12 +1,12 @@
 {
-  "version": "0.10.42",
+  "version": "0.10.44",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
     "README.md": "edcd36ebed5853c412c89ed998cd198f7a58237a68dcf37c14be5f7f5c0e9ff4",
     "bunfig.toml": "b9fc65eca9014c5179380259d70e76385a6a80788fa9a2df5fb3eaa5554fd2fe",
     "conventions/_profiles/architecture.yaml": "f1808768b720a4e476047e4a0912002ca673946562cea9aeef5d0c214828d93a",
-    "conventions/_profiles/coder.yaml": "4cf621a1f82e90e38d5c5e848619659ab93ab8d4d9a3798f51180d5297166a30",
+    "conventions/_profiles/coder.yaml": "3fb191556a64c9ebcf249516afa189afca24da9b22fd40b2fc66908196cdfb78",
     "conventions/_profiles/design.yaml": "25a02a67152d49728ad3517f6510da7285116fa69c56cbda55613a7cfcfd3b89",
     "conventions/_profiles/docs.yaml": "05485c3b32f1757e77c42e331eec1db651cb52ef57fc4e8607bb2f73b056cbb3",
     "conventions/_profiles/htmx.yaml": "38fc8b3e1a53429e16977ed63e83e751b203deffe9b338ea171050fb64641559",
@@ -19,7 +19,7 @@
     "conventions/_profiles/tester.yaml": "348183eee5298cbb843031f6c41c3f9d0a725b11b3c66e154b47c9b340a72666",
     "conventions/_profiles/topology.yaml": "08df698c2e5419e8f7faa83f5f15c3ba9c085cc2ce72579624eb24962a6b8612",
     "conventions/_profiles/traceability.yaml": "adce93fb8392307685a01bec85e60534c59a9f4f0e4f8ea4767d79d22cf80878",
-    "conventions/_profiles/workflow.yaml": "162404ac861c77d1d4f4f2a8b731eb80f75677197636f96d198909661247b229",
+    "conventions/_profiles/workflow.yaml": "4c31d46ebb303fdf44500fc806b0ade23f36328c9b6f9d54655ab6931f836e58",
     "conventions/atdd-bun.planner/atdd-bun.planner.acceptance-identity.convention.yaml": "81c5c773d5ee15e8d99a2c237aa9846b110b2533df45ebf407d0e3ec6ed3dd03",
     "conventions/atdd-bun.planner/atdd-bun.planner.identity-required.convention.yaml": "e96d7c1455d0c221072d82e7f2b55da1c4f9ceb17718eb6ed96affdeef37675b",
     "conventions/atdd-bun.planner/atdd-bun.planner.identity-unique.convention.yaml": "409ba1d035ed46bc45f3627b62fd3a6a5967d984cc4c071c41be3f3fa887c6d6",
@@ -29,6 +29,7 @@
     "conventions/atdd-bun.planner/atdd-bun.planner.schema.convention.yaml": "16d0a26451758b759e6ca1f5b4f38ae1feff129688306ffcc2f70f6d3974b591",
     "conventions/atdd-bun.planner/atdd-bun.planner.train-wagon-resolves.convention.yaml": "6410e248351e701dcba38c671c07c4d8f6d67927984ed4d18e567abd1eb1f3f0",
     "conventions/atdd-bun.profiles/atdd-bun.profiles.presets.convention.yaml": "822c91fe1ec15ec0715a8ca2339c9379326f6a3e216829539b72ce5def272585",
+    "conventions/atdd-bun.review/atdd-bun.review.behavioral-reconciliation.convention.yaml": "e87958d918c7bec3f1428cfeff4862c324e383ba622a857d5b2def1628aa12af",
     "conventions/atdd-bun.topology/atdd-bun.topology.e2e-location.convention.yaml": "3a3b991bc851b86d597636200f5cb10a0defda3920348860cdca28955ab91f4c",
     "conventions/atdd-bun.topology/atdd-bun.topology.feature-source-coverage.convention.yaml": "2b64093f1e7f1fe0e2edcadf12e560fa80cecec19536abaa5bf09af362c6694e",
     "conventions/atdd-bun.topology/atdd-bun.topology.feature-test-coverage.convention.yaml": "279be57399c9b79a1bd758414076e3053d67b7d4a7fcbbb950ea12d1201effeb",
@@ -1191,12 +1192,12 @@
     "planner-schemas/train.schema.json": "d6fbac9067c1bffeb84eb79a71228441055af6e6e7ba141dd4e0bcb079345ec0",
     "planner-schemas/wagon.schema.json": "57b98f1ade998d745538eb3d72fb3014a50042006870f90bce47028eea336eb4",
     "planner-schemas/wmbt.schema.json": "7a3a5693bfcf01340667c2be4a3c48e74f34b1af7e8dc13372c0de06b7f4fe12",
-    "relationships.yaml": "15299f77e82c409ee6b8a7ffd37e8e1ab99fb31446f1ce303b07e968a6dbf830",
+    "relationships.yaml": "5860a308ebc3ee7fa8172fc2c6633984000ab3003f0ae4b6fa28db48879eda22",
     "src/agent.ts": "39ca8b3183063c60e00eb96e5629d0397aeb83cc82d4c4bc32c01715c906649b",
     "src/ci.ts": "67e54d2cbfc44a9e42837d5e750af526d6255c539d3c452a4d5fca3226c0d9ac",
     "src/cli.ts": "cbc50f1e7fc7d0935f78230b7da6e232ed7ee6f04828e015c599fb6f6edcbfa2",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
-    "src/enforce.ts": "2f624f2aa272466f44c552d77ce3976cb2a518491d3ec3c47815583fdd0f7ad8",
+    "src/enforce.ts": "8aee98b81552153732ab4faaf244fcad3ae1ca9d060e6bae3d61d319043f8849",
     "src/hooks.ts": "0b4ca8c857e637bbd144e737e78eda924e3cba7b038c0abe5e6916d200d73068",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
     "src/integrity.ts": "556976a42bae298df14b73675102d83b6bf4df0674d8e7211aad5315548f005f",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.42",
+  "version": "0.10.44",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/relationships.yaml

@@ -17,6 +17,7 @@ nodes:
   - atdd-bun.planner.schema
   - atdd-bun.planner.train-wagon-resolves
   - atdd-bun.profiles.presets
+  - atdd-bun.review.behavioral-reconciliation
   - atdd-bun.topology.e2e-location
   - atdd-bun.topology.feature-source-coverage
   - atdd-bun.topology.feature-test-coverage
@@ -5268,3 +5269,13 @@ edges:
     target_ref: planner.telemetry.tracking-plan-schema
     type: requires
     origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: final behavioral reconciliation follows review-ready RED, GREEN, REFACTOR, and full-profile proof
+    source_ref: atdd-bun.review.behavioral-reconciliation
+    strength: critical
+    target_ref: coder.bun.phase-discipline
+    type: follows
+    origin: "@afokapu/atdd-bun"

package/src/enforce.ts

@@ -38,15 +38,18 @@ export const profileImplementations: Record<ConcreteProfile, string[]> = {
   interlocking: ["bun_interlocking_binding", "bun_interlocking_coverage", "bun_interlocking_infrastructure"],
   htmx: ["htmx_hypermedia_detector", "htmx_tester_detector", "htmx_e2e_detector"],
   design: ["bun_design_system_detector", "bun_responsive_detector"],
-  // Operational policy only: its convention lives in the optional @afokapu/atdd-workflow package.
+  // Operational policies only: Workflow supplies lifecycle orchestration; ATDD Bun supplies delivery review semantics.
   workflow: [],
 };
 
 /** Additional policy conventions a profile loads, whether local or contributed by an installed companion package. */
 export const profileConventions: Record<ConcreteProfile, Array<{ rule_id: string; path: string }>> = {
-  traceability: [], topology: [], docs: [], planner: [], telemetry: [], coder: [{ rule_id: ["coder.bun", "phase-discipline"].join("."), path: "conventions/coder.bun/coder.bun.phase-discipline.convention.yaml" }], tester: [], security: [],
+  traceability: [], topology: [], docs: [], planner: [], telemetry: [], coder: [{ rule_id: "coder.bun.phase-discipline", path: "conventions/coder.bun/coder.bun.phase-discipline.convention.yaml" }], tester: [], security: [],
   architecture: [], metrics: [], runtime: [], interlocking: [], htmx: [], design: [],
-  workflow: [{ rule_id: "atdd-workflow.workflow.lifecycle", path: "../atdd-workflow/conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml" }],
+  workflow: [
+    { rule_id: "atdd-bun.review.behavioral-reconciliation", path: "conventions/atdd-bun.review/atdd-bun.review.behavioral-reconciliation.convention.yaml" },
+    { rule_id: "atdd-workflow.workflow.lifecycle", path: "../atdd-workflow/conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml" },
+  ],
 };
 
 /** Every profile but `all`. */