guardian-framework 0.1.104 → 0.1.109

package/templates/pi/scripts/validate-exploration-depth.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-exploration-depth.sh — ADR-008 modeling-depth rules over a
+# domain-exploration session's structured result (JSON).
+#
+# Deterministic, machine-parseable checks (no LLM):
+#   depth-subdomain    every bounded context has subdomainType + rationale
+#   depth-invariants   invariant entries carry rule + illegalStatePrevented
+#   event-triage       every domain event passes >=1 triage question
+#   roots-justified    aggregate-root entities claim identity (identityPersists)
+#   ul-cross-context   no term reused across contexts without a context-map edge
+#
+# Usage:
+#   bash .pi/scripts/validate-exploration-depth.sh [<session-id>]
+#     without id: validates the most recent *.raw.json session
+#   exit 0 = all pass ; exit 1 = violations (one '[rule-id] error:' per line)
+# ============================================================================
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+EXPLORATION_DIR="${1:-}"
+RAW=""
+
+if [ -z "$EXPLORATION_DIR" ]; then
+    # No session id given: locate the most recent session raw JSON.
+    RAW="$(ls -1t "${SCRIPT_DIR}/../domain/exploration/"*.raw.json 2>/dev/null | head -1)"
+elif [[ "$EXPLORATION_DIR" == */* || "$EXPLORATION_DIR" == *.json ]]; then
+    RAW="$EXPLORATION_DIR"
+else
+    RAW="${SCRIPT_DIR}/../domain/exploration/${EXPLORATION_DIR}.raw.json"
+fi
+
+if [ -z "$RAW" ] || [ ! -f "$RAW" ]; then
+    echo "no exploration session raw.json found (expected at .pi/domain/exploration/<session>.raw.json)" >&2
+    exit 1
+fi
+
+python3 - "$RAW" <<'PY'
+import json, sys
+
+path = sys.argv[1]
+try:
+    with open(path, encoding="utf-8") as fh:
+        data = json.load(fh)
+except Exception as exc:  # noqa: BLE001
+    print(f"[json-invalid] error: {path} is not valid JSON — {exc}")
+    sys.exit(1)
+
+errors = []
+
+def err(rule, msg):
+    errors.append(f"[{rule}] error: {msg}")
+
+# Rule 1: subdomain classification present
+for bc in data.get("boundedContexts", []):
+    name = bc.get("name", "?")
+    st = bc.get("subdomainType")
+    if st not in ("core", "supporting", "generic"):
+        err("depth-subdomain", f"bounded context '{name}' missing subdomainType (core|supporting|generic)")
+    if not bc.get("subdomainRationale"):
+        err("depth-subdomain", f"bounded context '{name}' missing subdomainRationale")
+
+# Rule 2: invariants well-formed
+for bc in data.get("boundedContexts", []):
+    name = bc.get("name", "?")
+    for inv in bc.get("invariants", []) or []:
+        if not inv.get("rule"):
+            err("depth-invariants", f"context '{name}' has an invariant with an empty rule")
+        if not inv.get("illegalStatePrevented"):
+            err("depth-invariants", f"context '{name}' invariant '{inv.get('rule','')}' missing illegalStatePrevented")
+
+# Rule 3: event triage (>=1 question answered yes)
+for ev in data.get("domainEvents", []):
+    triage = ev.get("triage") or {}
+    hits = sum(bool(triage.get(k)) for k in ("domainExpertCares", "crossesAggregateBoundary", "needsAudit"))
+    if hits == 0:
+        err("event-triage", f"event '{ev.get('name','?')}' fails all triage questions (implementation detail, not a domain event)")
+
+# Rule 4: aggregate roots claim identity
+for ent in data.get("entities", []):
+    if ent.get("type") == "aggregate-root":
+        just = ent.get("justification") or {}
+        if not just.get("identityPersists"):
+            err("roots-justified", f"aggregate-root '{ent.get('name','?')}' must justify identityPersists=true")
+
+# Rule 5: cross-context term reuse needs a context-map edge
+term_contexts = {}
+for t in data.get("ubiquitousLanguage", []):
+    term = t.get("term", "")
+    ctx = t.get("boundedContext", "")
+    if not term or not ctx:
+        continue
+    term_contexts.setdefault(term, set()).add(ctx)
+edges = {
+    (e.get("from"), e.get("to"))
+    for e in data.get("contextMap", [])
+    if e.get("from") and e.get("to")
+}
+for term, contexts in term_contexts.items():
+    ctxs = sorted(contexts)
+    if len(ctxs) > 1:
+        connected = any((ctxs[0], c) in edges or (c, ctxs[0]) in edges for c in ctxs[1:])
+        if not connected:
+            err("ul-cross-context", f"term '{term}' used in contexts {', '.join(ctxs)} without a context-map edge or UL conflicts entry")
+
+if errors:
+    print("\n".join(errors))
+    sys.exit(1)
+print("depth validation passed (subdomain classification, invariants, event triage, aggregate roots, UL contexts)")
+sys.exit(0)
+PY
+exit $?

package/templates/pi/scripts/validate-runtime-wiring.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-runtime-wiring.sh — ADR-009 production-reachability dispatcher
+#
+# Deterministic check: every application-layer service must be referenced from
+# production code OUTSIDE its own module and OUTSIDE tests. A service whose
+# only callers are its own tests is implemented-but-unwired (dead code with a
+# test suite) — the recurring rigorix pattern ADR-009 fixes.
+#
+# Delegates to languages/<lang>/check_runtime_reachability.sh.
+# Usage: bash .pi/scripts/validate-runtime-wiring.sh [--root <dir>]
+# Exit:  0 all services reachable (or language not yet covered)
+#        1 unreachable service(s) — one 'file: [runtime-reachability] ...' line each
+# ============================================================================
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(pwd)"
+if [ "${1:-}" = "--root" ] && [ -n "${2:-}" ]; then ROOT="$2"; fi
+cd "$ROOT" || exit 1
+
+detect_language() {
+    if [ -f "Cargo.toml" ]; then echo "rust"
+    elif [ -f "package.json" ]; then echo "typescript"
+    elif [ -f "go.mod" ]; then echo "go"
+    elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then echo "python"
+    elif [ -f "pom.xml" ] || [ -f "build.gradle" ]; then echo "java"
+    else echo "unknown"; fi
+}
+LANG="$(detect_language)"
+SCRIPT="${SCRIPT_DIR}/languages/${LANG}/check_runtime_reachability.sh"
+if [ -f "$SCRIPT" ]; then
+    exec bash "$SCRIPT" --root "$ROOT"
+fi
+echo "runtime-wiring: no reachability check for '${LANG}' yet (ADR-009 planned: go/python/java)"
+exit 0

package/templates/pi/skills/agents/architecture-validator.md

@@ -65,6 +65,34 @@ grep -r "registry.register" [src paths]
 grep -r "#\[from\]" [error file]
 ```
 
+
+## Model Judgment Review (ADR-008) — all languages
+
+**MANDATORY** when the reviewed scope touches domain/application code. Record
+each finding as WARN with `file:line: <finding>` — never a merge block on its
+own; promotion to a gate requires a written decision after a trial. Evidence
+commands are per-language; hard gates (deterministic) live in
+`.pi/scripts/languages/<lang>/check_model_judgment.sh`.
+
+- **R1 anemic-model** — app/application layer reads object state to decide
+  (`if (x.getStatus()…)`, `x.status =`, `x.State ==`) then mutates via
+  setters; business rules outside the domain object. Evidence per language:
+  Java/TS getter/setter chains; Go struct field pokes in services; Python
+  attribute mutation on domain objects; Rust `.field` writes / `set_*` from
+  services.
+- **R2 LSP / fragile-base** — domain entities inherit from a non-abstract
+  base (Java/TS `extends`, Go embedding, Python subclassing, Rust — prefer
+  composition over inheritance, flag base-class aggregates).
+- **R3 cohesion** — `Helper | Utils | Manager | Orchestrator`-style catch-all
+  classes/structs/types in the domain layer.
+- **R4 primitive obsession** — >2 raw primitives on a domain service method
+  signature where a value object/struct/record should exist (IDs, money,
+  ranges, statuses).
+- **R5 production reachability (ADR-009)** — an `implemented` application
+  service with no production caller outside its own module and outside tests
+  is dead code: report it and require the Runtime-Integration issue. Evidence:
+  `grep -rn "<ServiceName>" <src> | grep -v tests` per language.
+
 ## Output
 Use format from `.pi/context/output-formats.md` → "Validation Report"
 

package/templates/pi/skills/agents/test-validator.md

@@ -17,7 +17,7 @@ You validate test coverage and quality.
 ## Checks
 
 1. **All tests pass** — Run full test suite
-2. **Coverage ≥ 80%** — Run coverage tool
+2. **Coverage meets the project's real threshold** — Run the project's real coverage tool/gate (no per-module heuristic *_coverage.sh)
 3. **New code tested** — Every new function has tests
 4. **AAA pattern** — Arrange-Act-Assert structure
 5. **No flaky tests** — Deterministic, no timing dependencies

package/templates/pi/skills/go-enterprise-codegen.md

@@ -471,3 +471,49 @@ go.mod
 *Version: 1.0.0*
 *Last updated: 2026-07-03*
 *Source: Guardian DDD patterns + Clean Architecture + context7 (/wesionaryteam/go_clean_architecture, /golang/go)*
+
+## Judgment Tables (ADR-008)
+
+Compact decision tables distilled from professional OOP/DDD practice (token-lean;
+the full rationale lives in the curriculum, not here).
+
+### Entity vs Value Object
+| Question | Entity | Value Object |
+|----------|--------|--------------|
+| Identity persists across state changes? | yes | no |
+| Change = mutate in place? | yes | replace entirely |
+| Equality by identity or by attributes? | identity | all attributes |
+| Immutable by nature? | no | yes |
+| Track change history? | yes | no |
+
+### Aggregate Boundaries
+- An aggregate is a **consistency boundary**, not a data grouping.
+- One aggregate modified per transaction; everything else via events.
+- Reference other aggregates **by identity**, never by object graph.
+- Design **small** aggregates; the root is the only entry point — behavior methods, no setters.
+
+### Service Classifier
+| Service | Layer | Contains | Named by |
+|---------|-------|----------|----------|
+| Domain service | domain/ | business process spanning entities | ubiquitous language |
+| Application service | application/ | use-case orchestration (thin) | technical intent |
+| Infrastructure service | infrastructure/ | technical impl (persistence, http, events) | implementation |
+| Persistence port (interface) | domain/ | aggregate persistence contract | aggregate language |
+| Persistence adapter | infrastructure/ | framework impl (ORM/DB) | — |
+
+### Event Triage (3 questions)
+Keep a candidate event only if ≥1 is true: (1) would a domain expert care?
+(2) does it cross an aggregate boundary? (3) do we need an audit trail?
+Otherwise it is an implementation detail. Publish from the aggregate;
+dispatch **after** save from the application service.
+
+### Transaction & Persistence Placement
+| Concern | Location | Why |
+|---------|----------|-----|
+| `sql.Tx` / transaction scope | application service only | one aggregate per transaction |
+| Repository interface | domain/ package | dependency inversion |
+| Repository impl (sqlx/gorm) | infrastructure/ | framework out of domain |
+| Value object | domain/ (struct, immutable by convention) | replace, don't mutate |
+| Wiring | explicit constructors in `cmd/` | no framework magic |
+
+*Distilled 2026-09-03 from professional OOP/DDD curriculum (Modules 0–6) — ADR-008/009.*

package/templates/pi/skills/java-spring-enterprise-codegen.md

@@ -540,3 +540,53 @@ pom.xml (or build.gradle)
 *Version: 1.0.0*
 *Last updated: 2026-07-03*
 *Source: Guardian DDD patterns + Spring Boot best practices + context7 (/jkazama/ddd-java, /websites/spring_io_spring-boot)*
+
+## 10. Judgment Tables (ADR-008)
+
+Compact decision tables distilled from professional OOP/DDD/Spring practice
+(keep token-lean — the full rationale lives in the curriculum, not here).
+
+### Entity vs Value Object
+| Question | Entity | Value Object |
+|----------|--------|--------------|
+| Identity persists across state changes? | yes | no |
+| Change = mutate in place? | yes | replace entirely |
+| Equality by identity or by attributes? | identity | all attributes |
+| Immutable by nature? | no | yes |
+| Track change history? | yes | no |
+
+### Aggregate Boundaries
+- An aggregate is a **consistency boundary**, not a data grouping.
+- One aggregate modified per transaction; everything else via events.
+- Reference other aggregates **by identity**, never by object graph.
+- Design **small** aggregates (size by consistency, not relationships).
+- Root is the only entry point — state changes via behavior methods (no setters).
+
+### Service Classifier
+| Service | Layer | Contains | Named by |
+|---------|-------|----------|----------|
+| Domain service | domain/ | business process spanning entities | ubiquitous language |
+| Application service | application/ | use-case orchestration (thin) | technical intent |
+| Infrastructure service | infrastructure/ | technical impl (email, storage, publishing) | implementation |
+| Repository (interface) | domain/ | aggregate persistence contract | aggregate language |
+| Repository (impl) | infrastructure/ | JPA/ORM adapter | — |
+
+### Event Triage (3 questions)
+Ask of every candidate event; keep it only if ≥1 is true:
+1. Would a domain expert care?
+2. Does it cross an aggregate boundary?
+3. Do we need an audit trail?
+Otherwise it is an implementation detail, not a domain event.
+Publish events from the aggregate (`releaseEvents()`), dispatch **after** save
+from the application service.
+
+### Transaction & Persistence Placement
+| Concern | Location | Why |
+|---------|----------|-----|
+| `@Transactional` | application service methods only | one aggregate per transaction |
+| repository `save`/`find` | no `@Transactional` | don't open transactions per call |
+| VO → `@Embeddable` | domain value objects | immutable + replaceable |
+| Aggregate id | VO (`@EmbeddedId`) | type-safe identity |
+| Optimistic lock | version field on aggregate | concurrency safety |
+
+*Distilled 2026-09-03 from professional OOP/DDD/Spring curriculum (Modules 0–6) — ADR-008.*

package/templates/pi/skills/python-enterprise-codegen.md

@@ -401,3 +401,49 @@ pyproject.toml
 *Version: 1.0.0*
 *Last updated: 2026-07-03*
 *Source: Guardian DDD patterns + Python best practices + context7 (/fastapi/fastapi)*
+
+## Judgment Tables (ADR-008)
+
+Compact decision tables distilled from professional OOP/DDD practice (token-lean;
+the full rationale lives in the curriculum, not here).
+
+### Entity vs Value Object
+| Question | Entity | Value Object |
+|----------|--------|--------------|
+| Identity persists across state changes? | yes | no |
+| Change = mutate in place? | yes | replace entirely |
+| Equality by identity or by attributes? | identity | all attributes |
+| Immutable by nature? | no | yes |
+| Track change history? | yes | no |
+
+### Aggregate Boundaries
+- An aggregate is a **consistency boundary**, not a data grouping.
+- One aggregate modified per transaction; everything else via events.
+- Reference other aggregates **by identity**, never by object graph.
+- Design **small** aggregates; the root is the only entry point — behavior methods, no setters.
+
+### Service Classifier
+| Service | Layer | Contains | Named by |
+|---------|-------|----------|----------|
+| Domain service | domain/ | business process spanning entities | ubiquitous language |
+| Application service | application/ | use-case orchestration (thin) | technical intent |
+| Infrastructure service | infrastructure/ | technical impl (persistence, http, events) | implementation |
+| Persistence port (interface) | domain/ | aggregate persistence contract | aggregate language |
+| Persistence adapter | infrastructure/ | framework impl (ORM/DB) | — |
+
+### Event Triage (3 questions)
+Keep a candidate event only if ≥1 is true: (1) would a domain expert care?
+(2) does it cross an aggregate boundary? (3) do we need an audit trail?
+Otherwise it is an implementation detail. Publish from the aggregate;
+dispatch **after** save from the application service.
+
+### Transaction & Persistence Placement
+| Concern | Location | Why |
+|---------|----------|-----|
+| Session / commit scope | application service only | one aggregate per transaction |
+| Repository Protocol/ABC | domain/ | dependency inversion |
+| Repository impl (SQLAlchemy/Django) | infrastructure/ | ORM out of domain |
+| Value object | domain/ (dataclass frozen / attrs) | replace, don't mutate |
+| Framework (FastAPI/Django) | interfaces/ | web out of domain |
+
+*Distilled 2026-09-03 from professional OOP/DDD curriculum (Modules 0–6) — ADR-008/009.*

package/templates/pi/skills/rust-enterprise-codegen.md

@@ -1021,3 +1021,49 @@ live-tests = []  # Flag for tests that hit real APIs
 *Version: 1.0.0*
 *Last updated: 2026-07-03*
 *Source: Guardian DDD patterns + context7 DDD reference (/jkazama/ddd-java, /ardalis/cleanarchitecture)*
+
+## Judgment Tables (ADR-008)
+
+Compact decision tables distilled from professional OOP/DDD practice (token-lean;
+the full rationale lives in the curriculum, not here).
+
+### Entity vs Value Object
+| Question | Entity | Value Object |
+|----------|--------|--------------|
+| Identity persists across state changes? | yes | no |
+| Change = mutate in place? | yes | replace entirely |
+| Equality by identity or by attributes? | identity | all attributes |
+| Immutable by nature? | no | yes |
+| Track change history? | yes | no |
+
+### Aggregate Boundaries
+- An aggregate is a **consistency boundary**, not a data grouping.
+- One aggregate modified per transaction; everything else via events.
+- Reference other aggregates **by identity**, never by object graph.
+- Design **small** aggregates; the root is the only entry point — behavior methods, no setters.
+
+### Service Classifier
+| Service | Layer | Contains | Named by |
+|---------|-------|----------|----------|
+| Domain service | domain/ | business process spanning entities | ubiquitous language |
+| Application service | application/ | use-case orchestration (thin) | technical intent |
+| Infrastructure service | infrastructure/ | technical impl (persistence, http, events) | implementation |
+| Persistence port (interface) | domain/ | aggregate persistence contract | aggregate language |
+| Persistence adapter | infrastructure/ | framework impl (ORM/DB) | — |
+
+### Event Triage (3 questions)
+Keep a candidate event only if ≥1 is true: (1) would a domain expert care?
+(2) does it cross an aggregate boundary? (3) do we need an audit trail?
+Otherwise it is an implementation detail. Publish from the aggregate;
+dispatch **after** save from the application service.
+
+### Transaction & Persistence Placement
+| Concern | Location | Why |
+|---------|----------|-----|
+| Transaction handle scope | application service only | one aggregate per transaction |
+| Repository trait | domain/ (crate) | dependency inversion |
+| Repository impl (sqlx/diesel) | infrastructure/ | framework out of domain |
+| Value object | domain/ (struct/type, immutable) | replace, don't mutate |
+| HTTP (axum/actix) | interfaces/ | web out of domain |
+
+*Distilled 2026-09-03 from professional OOP/DDD curriculum (Modules 0–6) — ADR-008/009.*

package/templates/pi/skills/tdd-practice.md

@@ -6,7 +6,9 @@ description: TDD practice guide for Guardian implementation agents. Use when TDD
 # TDD Practice — Red → Green → Refactor
 
 > This skill applies when TDD mode is enabled on the current epic (`--tdd`).
-> Pre-generated failing test files exist in `tests/unit/<module>/<component>/`.
+> Pre-generated failing test files exist in the project's test directory
+> (language-specific: `tests/unit/` for TypeScript, `src/test/java/` for Java,
+> `tests/` for Python/Go/Rust).
 > These tests were generated deterministically from architecture contracts — no LLM involvement.
 
 ## Core Principle
@@ -24,8 +26,14 @@ Do NOT treat the generated tests as rigid specs you must match exactly. Treat th
 
 ### 1. Red — See the test fail
 
-```
-bun test tests/unit/<module>/<component>/<component>.test.ts
+Run the project's test runner on the generated test file:
+
+```bash
+# TypeScript: bun test tests/unit/<module>/<component>/<component>.test.ts
+# Java:       mvn test -Dtest=<Component>Test
+# Python:     pytest tests/<module>/<component>/test_<component>.py
+# Go:         go test ./tests/<module>/<component>/
+# Rust:       cargo test --test <component>
 ```
 
 Confirm the test fails before writing any implementation code. This validates that:
@@ -41,7 +49,7 @@ Write the minimal implementation to make the failing test pass.
 - Write only enough code to pass the test
 - Do not over-engineer — YAGNI
 - Use the test's TODO comments as a guide for what the API should look like
-- The test file is in `tests/unit/`, implementation files go in `src/`
+- The test file is in the project's test directory (`tests/unit/`, `src/test/java/`, or `tests/`), implementation files go in `src/`
 - Import the implementation module into the test file
 
 If the generated test assumes an API shape that doesn't fit, **update the test first**, then implement.
@@ -107,11 +115,11 @@ The generated tests are **suggestions, not constraints**. You should modify them
 
 ## File Locations
 
-| Artifact | Path |
-|----------|------|
-| Tests | `tests/unit/<module>/<component>/<component>.test.ts` |
-| Implementation | `src/<module>/<component>.ts` (or appropriate layer) |
-| TDD guide | `.pi/skills/tdd-practice.md` |
+| Artifact | TypeScript | Java | Python | Go | Rust |
+|----------|------------|------|--------|-----|------|
+| Tests | `tests/unit/.../component.test.ts` | `src/test/java/.../ComponentTest.java` | `tests/.../test_component.py` | `tests/.../component_test.go` | `tests/.../mod.rs` |
+| Implementation | `src/<module>/` | `src/main/java/.../` | `src/<module>/` | `src/<module>/` | `src/<module>/` |
+| TDD guide | `.pi/skills/tdd-practice.md` | same | same | same | same |
 
 ## Anti-Patterns
 

package/templates/pi/skills/typescript-enterprise-codegen.md

@@ -431,3 +431,49 @@ tsconfig.json
 *Version: 1.0.0*
 *Last updated: 2026-07-03*
 *Source: Guardian DDD patterns + TypeScript best practices + context7 (/microsoft/typescript)*
+
+## Judgment Tables (ADR-008)
+
+Compact decision tables distilled from professional OOP/DDD practice (token-lean;
+the full rationale lives in the curriculum, not here).
+
+### Entity vs Value Object
+| Question | Entity | Value Object |
+|----------|--------|--------------|
+| Identity persists across state changes? | yes | no |
+| Change = mutate in place? | yes | replace entirely |
+| Equality by identity or by attributes? | identity | all attributes |
+| Immutable by nature? | no | yes |
+| Track change history? | yes | no |
+
+### Aggregate Boundaries
+- An aggregate is a **consistency boundary**, not a data grouping.
+- One aggregate modified per transaction; everything else via events.
+- Reference other aggregates **by identity**, never by object graph.
+- Design **small** aggregates; the root is the only entry point — behavior methods, no setters.
+
+### Service Classifier
+| Service | Layer | Contains | Named by |
+|---------|-------|----------|----------|
+| Domain service | domain/ | business process spanning entities | ubiquitous language |
+| Application service | application/ | use-case orchestration (thin) | technical intent |
+| Infrastructure service | infrastructure/ | technical impl (persistence, http, events) | implementation |
+| Persistence port (interface) | domain/ | aggregate persistence contract | aggregate language |
+| Persistence adapter | infrastructure/ | framework impl (ORM/DB) | — |
+
+### Event Triage (3 questions)
+Keep a candidate event only if ≥1 is true: (1) would a domain expert care?
+(2) does it cross an aggregate boundary? (3) do we need an audit trail?
+Otherwise it is an implementation detail. Publish from the aggregate;
+dispatch **after** save from the application service.
+
+### Transaction & Persistence Placement
+| Concern | Location | Why |
+|---------|----------|-----|
+| Unit of Work / transaction scope | application service only | one aggregate per transaction |
+| Repository interface | domain/ (interfaces/port) | dependency inversion |
+| Repository impl (TypeORM/Prisma) | infrastructure/ | framework out of domain |
+| Value object | domain/ (class/record, immutable) | replace, don't mutate |
+| DI wiring | composition root (infrastructure) | explicit assembly |
+
+*Distilled 2026-09-03 from professional OOP/DDD curriculum (Modules 0–6) — ADR-008/009.*