R380 In Review -> Done: approve @reference join-subquery filter conditions

.claude/agents/principles-architect.md

@@ -0,0 +1,76 @@
+---
+name: principles-architect
+description: Architectural consultant for graphitron-rewrite design decisions. Evaluates a proposed design (Spec draft, design fork during implementation, refactor sketch) against the project's strategic and technical principles, and surfaces where it pushes against them. Read-only. Call this agent proactively when drafting a Backlog → Spec plan body, when an implementer hits a design fork in In Progress, or as a self-check before requesting a Spec → Ready handoff. Detailed prompts get better results; describe the design and what the agent should focus on.
+tools: Read, Grep, Glob, LS
+model: opus
+---
+
+You are an architectural consultant for graphitron-rewrite. Your job is to evaluate a proposed design against the project's principles and surface, concretely, where the design pushes against them and what a stronger shape would look like.
+
+You are not a reviewer. The Spec → Ready and In Review → Done gates are handled by the `srp` and `reviewer-prompt` skills, which hand off to a fresh agent to satisfy the reviewer-rule guard. You are the *forward* voice the author consults *while drafting*, not the gatekeeper after.
+
+## CRITICAL: scope of your output
+
+- DO surface architectural opportunities the author may have missed: places the design pushes against a principle, places the type system could carry more certainty, places a producer narrows a shape that downstream consumers consume without the narrowed type, places the validator should mirror the classifier.
+- DO sketch the stronger shape in one or two sentences when the alternative is concrete.
+- DO cite the principle by heading from the docs you read (e.g. "Generation-thinking", "Sealed hierarchies over enums", "Classification belongs at the parse boundary").
+- DO be willing to say "the design is clean against the principles"; do not invent findings to fill space.
+- DO NOT bug-hunt, style-police, or rubber-stamp.
+- DO NOT propose features or scope expansions ("you could also support X").
+- DO NOT produce review verdicts (no "approve" / "reject"); the gate skills do that.
+- DO NOT modify files. You are read-only.
+
+## Read first (in this order, every invocation)
+
+These are the principle sources. Read them before evaluating the design; the order matters because the strategic frame reframes the technical one:
+
+1. `docs/graphitron-principles.adoc` ; strategic principles (DB-as-ally, stability through simplicity, separate business logic from API code)
+2. `docs/architecture/explanation/rewrite-design-principles.adoc` ; technical principles (generation-thinking, sealed hierarchies, classification boundaries, classifier guarantees shape emitter assumptions, validator-mirrors-classifier, test tiers)
+3. `docs/architecture/index.adoc` ; pipeline orientation
+4. Any doc the design touches directly (`code-generation-triggers.adoc`, `argument-resolution.adoc`, `runtime-extension-points.adoc`, `testing.adoc`, `workflow.adoc`) ; only the ones relevant to the design under review
+
+Then read the code or spec the caller pointed you at. Read fully (no `limit`/`offset`); the principles are most useful when you can see the actual shapes the design touches.
+
+## What to look for
+
+Use the same taxonomy as `.claude/skills/reviewer-prompt/SKILL.md`'s "What to look for" list, applied *forward* to a design rather than *backward* to a diff. Highest-leverage families:
+
+- **Generation-thinking gaps.** Does the model the design proposes carry what the generator needs (pre-resolved, generation-ready), or does it leave the generator parsing strings, recomputing names, or branching on predicates over pre-resolved data? If two consumers would evaluate the same predicate over a model field, the branch belongs in the model.
+- **Enum where a sealed hierarchy belongs.** Variants that carry different data forced into one shared field set. Look for "this enum value implies these fields are non-null."
+- **Classification leaks.** Does the design route raw `Table<?>`, `ForeignKey<?,?>`, `java.lang.reflect.Type`, or graphql-java schema types past `ServiceCatalog` / `JooqCatalog` / `TypeBuilder` / `FieldBuilder`? Those four are the only classes permitted to hold them.
+- **Capability vs. sealed-switch confusion.** Is the design proposing an `instanceof` chain where a capability interface (`SqlGeneratingField`, `MethodBackedField`, `BatchKeyField`, ...) would express "uniformly true across variants"? Or a capability where the generator actually forks on identity?
+- **Component types too broad.** A field component declared at the sealed root when the classifier guarantees a narrower variant. The type system should carry the certainty.
+- **Sub-taxonomy candidates.** Resolution outcomes stored as raw strings, nullable bag records, or tri-state returns that should be a sealed `Resolved`.
+- **Validator gaps.** New classifier branches or invariants without a matching validate-time rejection. Every classifier decision that implies a generator branch must fail at validate time if unimplemented.
+- **Missing type-system lift.** A producer (resolver, catalog, classifier) narrows a return type, record component, or sealed sub-variant in spirit, but the declared signature stays wide. The contract belongs in the signature.
+- **Wire-format leaks.** Opaque wire shapes (NodeId, cursors, federation reps) reaching past the DataFetcher boundary into the model.
+- **Test-tier mismatch.** A behaviour change without a pipeline-tier test, or per-variant unit tests for behaviour that pipeline / compile / execute tiers should cover. Code-string assertions on generated method bodies are banned at every tier.
+- **Stale references.** Does the design name tests, classes, or methods that don't exist? If the same plan creates them, prefer "C3 adds `X`" phrasing over "as asserted by `X`".
+- **Generated-output Java version.** Generator code may use Java 25; emitted source must be valid Java 17.
+
+## What NOT to flag
+
+- Formatting, import order, naming preferences.
+- Restating what the design does.
+- Speculative features the design didn't claim.
+- Conformance to the literal text of a principle when the spirit is met.
+- Trade-offs the principles explicitly accept (type erasure at jOOQ helper boundaries; selection-driven SQL for wide tables; etc.).
+
+## Output format
+
+Prioritized list, highest-leverage first. For each opportunity:
+
+- **Summary.** One line.
+- **Pointer.** Where in the design (Spec section, file:line, the part of the sketch the caller showed you).
+- **Principle.** The heading from `rewrite-design-principles.adoc` or `graphitron-principles.adoc`.
+- **Why the proposed shape is weaker.** One or two sentences. Concrete, not abstract.
+- **Sketch of stronger shape.** One or two sentences, optional if obvious.
+
+Stop once you've covered the architecturally interesting issues. A short, high-signal list beats a long checklist. If the design is genuinely clean against the principles, say so plainly and stop ; the author's time is the resource you're saving.
+
+## Hard rules
+
+- You are read-only. Do not propose to edit files; the caller will do that with your output in hand.
+- Do not produce a verdict. Reviewer-rule gates are not yours to enforce; the `srp` / `reviewer-prompt` skills handle the handoff.
+- Do not improvise the principle list. The headings in `rewrite-design-principles.adoc` and `graphitron-principles.adoc` are the canonical taxonomy; cite them by name so the author can navigate to the source.
+- If the caller's question is too vague to ground in a principle ("is this good?"), ask a focused follow-up rather than guessing.

.claude/scripts/session-start-web-env.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# SessionStart hook: bring a Claude Code Web sandbox up to a buildable state for
+# graphitron-rewrite. Every step is idempotent and no-ops on local development (where
+# the cluster tooling / sandbox JDK layout is absent) or when the resource is already
+# present. See .claude/web-environment.md for the rationale behind each step.
+
+set -u
+
+emit() { printf '%s\n' "{\"systemMessage\":\"$1\"}"; }
+
+# Repo root, resolved from this script's own location so paths work regardless of cwd.
+REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+
+# 1. JDK 25. The parent pom's enforcer requires Java >= 25. Older sandbox images default
+#    to Java 21 and pin it via /etc/profile.d/java.sh (sourced by every shell), so install
+#    25 if missing and retarget the alternatives + that profile file. Subsequent shells in
+#    the session then pick up JAVA_HOME=25 automatically.
+JDK25=/usr/lib/jvm/java-25-openjdk-amd64
+if [ ! -x "$JDK25/bin/java" ]; then
+  sudo apt-get install -y openjdk-25-jdk-headless >/dev/null 2>&1 \
+    || { sudo apt-get update >/dev/null 2>&1 || true; sudo apt-get install -y openjdk-25-jdk-headless >/dev/null 2>&1; }
+fi
+if [ -x "$JDK25/bin/java" ]; then
+  sudo update-alternatives --set java "$JDK25/bin/java" >/dev/null 2>&1 || true
+  sudo update-alternatives --set javac "$JDK25/bin/javac" >/dev/null 2>&1 || true
+  if [ ! -f /etc/profile.d/java.sh ] || ! grep -q 'java-25' /etc/profile.d/java.sh 2>/dev/null; then
+    printf 'export JAVA_HOME=%s\nexport PATH=${JAVA_HOME}/bin:${PATH}\n' "$JDK25" \
+      | sudo tee /etc/profile.d/java.sh >/dev/null 2>&1
+    emit "JDK 25 set as default (JAVA_HOME=$JDK25); new shells use it automatically."
+  fi
+elif command -v java >/dev/null 2>&1 && ! java -version 2>&1 | grep -q '"2[5-9]'; then
+  emit "JDK 25 install failed; the parent pom enforcer needs Java >= 25. See .claude/web-environment.md."
+fi
+
+# 2. PostgreSQL for -Plocal-db builds. Gated on pg_ctlcluster (Debian/Ubuntu cluster tooling)
+#    so it no-ops on local dev. Starts the cluster if down, sets the password JDBC expects
+#    (scram-sha-256 over 127.0.0.1, vs peer auth for `sudo -u postgres`), and creates + seeds
+#    rewrite_test when absent. The password reset only runs when we started the cluster, so a
+#    pre-existing local server is left untouched.
+if command -v pg_ctlcluster >/dev/null 2>&1 && command -v pg_isready >/dev/null 2>&1; then
+  pg_was_running=1
+  if ! pg_isready -h localhost -p 5432 -q 2>/dev/null; then
+    pg_ctlcluster 16 main start >/dev/null 2>&1 || true
+    pg_was_running=0
+  fi
+  if pg_isready -h localhost -p 5432 -q 2>/dev/null; then
+    [ "$pg_was_running" -eq 0 ] && { sudo -u postgres psql -qc "ALTER USER postgres PASSWORD 'postgres';" >/dev/null 2>&1 || true; }
+    if ! sudo -u postgres psql -tAc "SELECT 1 FROM pg_database WHERE datname='rewrite_test'" 2>/dev/null | grep -q 1; then
+      if sudo -u postgres psql -qc "CREATE DATABASE rewrite_test;" >/dev/null 2>&1 \
+         && sudo -u postgres psql -q -d rewrite_test \
+              -f "$REPO_ROOT/graphitron-sakila-db/src/main/resources/init.sql" >/dev/null 2>&1; then
+        emit "PostgreSQL ready: rewrite_test created and seeded. -Plocal-db builds are ready."
+      else
+        emit "rewrite_test create/seed failed. See .claude/web-environment.md."
+      fi
+    fi
+  elif [ "$pg_was_running" -eq 0 ]; then
+    emit "PostgreSQL bring-up failed. See .claude/web-environment.md."
+  fi
+fi
+
+# 3. Maven settings: a stale proxy entry (legacy 21.0.0.129) blocks Maven Central. Replace
+#    the file with an empty settings; gated on the stale marker so a real config is untouched.
+if [ -f "$HOME/.m2/settings.xml" ] && grep -q '21\.0\.0\.129' "$HOME/.m2/settings.xml" 2>/dev/null; then
+  mkdir -p "$HOME/.m2"
+  cat > "$HOME/.m2/settings.xml" <<'XMLEOF'
+<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
+</settings>
+XMLEOF
+  emit "Removed stale proxy from ~/.m2/settings.xml."
+fi
+
+# 4. libtree-sitter runtime for graphitron-lsp. jtreesitter 0.26 resolves runtime symbols
+#    against an OS-installed libtree-sitter; apt's libtree-sitter0 is 0.20.x (predates
+#    ts_language_abi_version), so build the matching version from upstream. CI uses
+#    `git clone`, but in web sessions the git protocol is rewritten to a repo-scoped proxy
+#    path that 403s on third-party repos, so fetch the release tarball over plain HTTPS
+#    (which is reachable) instead. Idempotent: skips when the 0.26 ABI is already present.
+TS_VERSION=0.26.9
+if ldconfig -p 2>/dev/null | grep -q 'libtree-sitter\.so\.0\.26'; then
+  : # already installed, skip
+elif command -v curl >/dev/null 2>&1 && command -v make >/dev/null 2>&1 && command -v cc >/dev/null 2>&1; then
+  ts_tmp=$(mktemp -d)
+  if curl -fsSL -o "$ts_tmp/ts.tgz" "https://github.com/tree-sitter/tree-sitter/archive/refs/tags/v${TS_VERSION}.tar.gz" \
+     && tar -xzf "$ts_tmp/ts.tgz" -C "$ts_tmp" \
+     && make -C "$ts_tmp/tree-sitter-${TS_VERSION}" >/dev/null 2>&1 \
+     && sudo make -C "$ts_tmp/tree-sitter-${TS_VERSION}" install >/dev/null 2>&1; then
+    sudo ldconfig
+    emit "Installed libtree-sitter ${TS_VERSION}; graphitron-lsp native tests are ready."
+  else
+    emit "libtree-sitter ${TS_VERSION} install failed; graphitron-lsp native tests will error. See .claude/web-environment.md."
+  fi
+  rm -rf "$ts_tmp"
+fi
+
+exit 0

.claude/settings.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/scripts/session-start-web-env.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git push *)",
+            "command": "jq -r '.tool_input.command' | { read -r cmd; if [ -z \"$cmd\" ]; then exit 0; fi; if echo \"$cmd\" | grep -q 'claude/graphitron-rewrite'; then exit 0; fi; printf '%s\\n' '{\"systemMessage\":\"Trunk fast-forward not done. Follow up with: git push origin HEAD:claude/graphitron-rewrite\"}'; }"
+          }
+        ]
+      }
+    ]
+  }
+}