guardian-framework 0.1.105 → 0.1.109

package/templates/pi/scripts/languages/typescript/coverage.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# ============================================================================
+# coverage.sh — TypeScript/JavaScript: real line coverage via the project's
+# coverage-enabled test runner
+#
+# Runs the test suite with coverage enabled, using the first runner that is
+# actually installed: vitest → jest → bun test --coverage → c8. All of them
+# emit a text table with an "All files" summary row; the "% Lines" column is
+# parsed from it (header-driven — istanbul-style tables have 5 percentage
+# columns, bun's has 2). No heuristic grep counting.
+#
+# Usage (normally via the .pi/scripts/coverage.sh dispatcher):
+#   bash coverage.sh            # measure coverage
+#   bash coverage.sh --gate     # fail if lines < COVERAGE_THRESHOLD
+#   bash coverage.sh --lcov     # report an existing lcov artifact, if any
+#
+# Env:
+#   COVERAGE_THRESHOLD  minimum line-coverage % (default: 60)
+# ============================================================================
+set -uo pipefail
+
+COVERAGE_THRESHOLD="${COVERAGE_THRESHOLD:-60}"
+GATE=0
+LCOV=0
+
+for arg in "$@"; do
+    case "$arg" in
+        --gate) GATE=1 ;;
+        --lcov) LCOV=1 ;;
+        *) echo "unknown arg: $arg" >&2; exit 2 ;;
+    esac
+done
+
+# Walk up from CWD to the project root (package.json).
+ROOT="$(pwd)"
+while [ "$ROOT" != "/" ] && [ ! -f "$ROOT/package.json" ]; do
+    ROOT="$(dirname "$ROOT")"
+done
+if [ ! -f "$ROOT/package.json" ]; then
+    echo "✗ No package.json found in this directory tree" >&2
+    exit 1
+fi
+cd "$ROOT" || exit 1
+
+OUT_FILE="$(mktemp)"
+trap 'rm -f "$OUT_FILE"' EXIT
+
+run_and_capture() {
+    # shellcheck disable=SC2015
+    "$@" >"$OUT_FILE" 2>&1 || true
+}
+
+echo "═══ Coverage (real test-runner coverage) ═══"
+RUN=""
+if [ -x "node_modules/.bin/vitest" ]; then
+    echo "  runner: vitest"
+    run_and_capture node_modules/.bin/vitest run --coverage
+    RUN="vitest"
+elif command -v vitest >/dev/null 2>&1; then
+    echo "  runner: vitest (PATH)"
+    run_and_capture vitest run --coverage
+    RUN="vitest"
+elif [ -x "node_modules/.bin/jest" ]; then
+    echo "  runner: jest"
+    run_and_capture node_modules/.bin/jest --coverage
+    RUN="jest"
+elif command -v jest >/dev/null 2>&1; then
+    echo "  runner: jest (PATH)"
+    run_and_capture jest --coverage
+    RUN="jest"
+elif command -v bun >/dev/null 2>&1; then
+    echo "  runner: bun test --coverage"
+    run_and_capture bun test --coverage
+    RUN="bun"
+elif [ -x "node_modules/.bin/c8" ]; then
+    # c8 (istanbul) wraps the project's own test command.
+    echo "  runner: c8 (npm test)"
+    run_and_capture node_modules/.bin/c8 --reporter=text npm test
+    RUN="c8"
+else
+    echo "✗ No coverage-enabled test runner found (vitest/jest/bun/c8)" >&2
+    echo "  run .pi/scripts/install_coverage_tools.sh for guidance" >&2
+    exit 1
+fi
+
+# Parse the "% Lines" column of the "All files" row from the runner's text
+# table. Header-driven: locate the "% Lines" column in the header row, then
+# read it from the "All files" summary row (istanbul-style tables list
+# % Stmts, % Branch, % Funcs, % Lines; bun lists % Funcs, % Lines).
+COVERAGE="$(python3 - "$OUT_FILE" <<'PY'
+import sys, re
+with open(sys.argv[1], encoding="utf-8", errors="replace") as fh:
+    lines = [ln.strip() for ln in fh]
+
+header = next((ln for ln in lines if ln.startswith("File") and "%" in ln), None)
+allrow = next((ln for ln in lines if ln.startswith("All files")), None)
+if not header or not allrow:
+    m = re.search(r"([0-9]+(?:\.[0-9]+)?)%", lines[-1] if lines else "")
+    print(m.group(1) if m else "")
+    raise SystemExit
+
+cols = [c.strip() for c in header.split("|")]
+idx = next(
+    (i for i, c in enumerate(cols) if c.replace("%", "").strip().lower() == "lines"),
+    None,
+)
+if idx is None:
+    idx = next((i for i, c in enumerate(cols) if c.startswith("%")), 1) + 1
+
+cells = [c.strip() for c in allrow.split("|")]
+if idx is not None and idx < len(cells):
+    val = cells[idx].replace("%", "").strip()
+    if val.replace(".", "", 1).isdigit():
+        print(val)
+        raise SystemExit
+m = re.search(r"([0-9]+(?:\.[0-9]+)?)%", allrow)
+print(m.group(1) if m else "")
+PY
+)"
+
+tail -8 "$OUT_FILE"
+echo ""
+echo "Line coverage: ${COVERAGE:-unavailable}% (threshold: ${COVERAGE_THRESHOLD}%, runner: ${RUN})"
+
+if [ -z "$COVERAGE" ]; then
+    echo "✗ Could not extract an 'All files' line-coverage percentage from ${RUN} output." >&2
+    echo "  Ensure the runner is configured to emit a text coverage summary" >&2
+    echo "  (vitest: coverage.reporter includes 'text'; jest: coverageReporters includes 'text')." >&2
+    exit 1
+fi
+
+if [ "$LCOV" -eq 1 ]; then
+    LCOV_FOUND=""
+    for cand in "coverage/lcov.info" "lcov.info"; do
+        if [ -f "$cand" ]; then
+            echo "lcov artifact found: $cand"
+            LCOV_FOUND=1
+            break
+        fi
+    done
+    if [ -z "$LCOV_FOUND" ]; then
+        echo "⚠️  no lcov.info artifact found — configure your runner's lcov reporter" >&2
+    fi
+fi
+
+if [ "$GATE" -eq 1 ]; then
+    if awk "BEGIN { exit !($COVERAGE >= $COVERAGE_THRESHOLD) }"; then
+        echo "✓ Coverage gate passed"
+    else
+        echo "✗ Coverage below threshold (${COVERAGE}% < ${COVERAGE_THRESHOLD}%)" >&2
+        exit 1
+    fi
+fi
+exit 0

package/templates/pi/scripts/languages/typescript/install_coverage_tools.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# ============================================================================
+# install_coverage_tools.sh — TypeScript/JavaScript: install a real coverage
+# tool
+#
+# The coverage gate (languages/typescript/coverage.sh) prefers the runner
+# your project already uses (vitest → jest → bun → c8). This script installs
+# whatever is missing for that chain:
+#   - vitest coverage needs the matching provider package
+#   - jest coverage is built-in (text reporter via config)
+#   - bun test --coverage is built into the Bun runtime (no install)
+#   - c8 is a universal fallback that wraps `npm test`
+#
+# Run this inside the project root (where package.json lives).
+# ============================================================================
+set -euo pipefail
+
+if [ ! -f "package.json" ]; then
+    echo "✗ No package.json found in the current directory" >&2
+    exit 1
+fi
+
+if grep -q '"vitest"' package.json; then
+    if grep -q 'coverage-v8\|coverage-istanbul' package.json; then
+        echo "vitest + coverage provider present."
+    else
+        echo "vitest detected — installing @vitest/coverage-v8 (required for vitest --coverage)..."
+        npm install --save-dev @vitest/coverage-v8 \
+            || { echo "✗ install failed — run: npm install --save-dev @vitest/coverage-v8" >&2; exit 1; }
+    fi
+elif grep -q '"jest"' package.json; then
+    echo "jest detected — enable 'coverageReporters': ['text', 'lcov'] in jest config for the coverage gate."
+elif command -v bun >/dev/null 2>&1; then
+    echo "bun detected — 'bun test --coverage' is built in; no install needed."
+else
+    echo "No vitest/jest/bun detected — installing c8 as a universal coverage runner..."
+    npm install --save-dev c8 \
+        || { echo "✗ install failed — run: npm install --save-dev c8" >&2; exit 1; }
+fi
+
+echo "TypeScript coverage tooling ready."

package/templates/pi/scripts/languages/typescript/validate-canonical.sh

@@ -46,11 +46,15 @@ echo "--- Module-to-Implementation Mapping ---"
 if [ -d ".pi/architecture/modules" ]; then
     MAPPED=0
     UNMAPPED=0
+    # Modules are mapped by canonical reference headers in source files
+    # (// Canonical: .pi/architecture/modules/<module>.md) — with a filename
+    # heuristic fallback for repos that name directories after modules.
+    REFERRED=$(grep -rEho '\.pi/architecture/modules/[a-z0-9-]+\.md' "$SRC_DIR" --include="*.ts" 2>/dev/null | sort -u) || true
     for module_doc in .pi/architecture/modules/*.md; do
         [ -f "$module_doc" ] || continue
         MODULE_NAME=$(basename "$module_doc" .md)
-        # Look for matching TS files (by convention: module name maps to src/<module>/ or similar)
-        if find "$SRC_DIR" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null | grep -qi "$MODULE_NAME" 2>/dev/null; then
+        if echo "$REFERRED" | grep -q "$MODULE_NAME\.md" 2>/dev/null \
+           || find "$SRC_DIR" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null | grep -qi "$MODULE_NAME" 2>/dev/null; then
             MAPPED=$((MAPPED + 1))
         else
             UNMAPPED=$((UNMAPPED + 1))

package/templates/pi/scripts/languages/typescript/validate-ci.sh

@@ -152,13 +152,13 @@ echo ""
 echo "--- Format ---"
 if [ -f "biome.json" ]; then
     if command -v biome &>/dev/null; then
-        if biome format . --check 2>/dev/null; then
+        if biome ci . 2>/dev/null; then
             pass "Format check passed (biome format)"
         else
             fail "Format check failed (biome format)"
         fi
     elif command -v npx &>/dev/null; then
-        if npx biome format . --check 2>/dev/null; then
+        if npx biome ci . 2>/dev/null; then
             pass "Format check passed (npx biome format)"
         else
             fail "Format check failed (npx biome format)"

package/templates/pi/scripts/validate-architecture-readiness.sh

@@ -26,6 +26,7 @@ FAIL=0
 log_pass() { echo -e "  ${GREEN}✓ PASS${NC} $1"; PASS=$((PASS + 1)); }
 log_fail() { echo -e "  ${RED}✗ FAIL${NC} $1 — $2"; FAIL=$((FAIL + 1)); }
 log_skip() { echo -e "  ${YELLOW}⊘ SKIP${NC} $1 — $2"; PASS=$((PASS + 1)); }
+log_warn() { echo -e "  ${YELLOW}⚠ WARN${NC} $1 — $2"; }
 
 echo "═══ Architecture Readiness Checks ═══"
 echo ""
@@ -134,6 +135,34 @@ else
     log_skip "Architecture conformance" "check_architecture_conformance.sh not found"
 fi
 
+
+# ── 7. ADR-009: runtime wiring gates ──
+# a) ADR-acceptance: an IMPLEMENTED module that documents runtime integration
+#    must not leave its referenced feature ADR Proposed.
+echo "Checking ADR-acceptance + legacy-removal (ADR-009)..."
+ADR_GATE_FAIL=0
+for doc in .pi/architecture/modules/*.md; do
+    [ -f "$doc" ] || continue
+    if ! grep -q "status: implemented" "$doc"; then continue; fi
+    if ! grep -qE "^##{2,3}.*Integration|^#{2,3}.*Dispatch" "$doc"; then continue; fi
+    refs=$(grep -oE "ADR-[0-9]{3}" "$doc" | sort -u | tr "\n" " ")
+    for adr in $refs; do
+        adrfile=$(ls .pi/architecture/decisions/${adr}-*.md 2>/dev/null | head -1)
+        [ -n "$adrfile" ] || continue
+        if grep -q "\*\*Status:\*\* Proposed" "$adrfile" || grep -qE "^\*\*Status:\*\* *Proposed" "$adrfile"; then
+            log_fail "ADR-acceptance (ADR-009)" "${doc##*/} is implemented + documents runtime integration but ${adr} is still Proposed — wire it and Accept the ADR"
+            ADR_GATE_FAIL=1
+        fi
+    done
+    # b) legacy-removal warning (declared migration rule / legacy note)
+    if grep -qE "legacy .*still|still uses|GAP-.*migration" "$doc"; then
+        log_warn "legacy-removal (ADR-009)" "${doc##*/} declares a legacy path/migration rule — verify it is removed or delegating (validate-runtime-wiring.sh)"
+    fi
+done
+if [ $ADR_GATE_FAIL -eq 0 ]; then
+    log_pass "ADR-acceptance (ADR-009)" "no implemented module left a runtime-integration ADR Proposed"
+fi
+
 # ── Summary ──
 
 echo ""

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.*