backend-skeleton 1.5.0 → 1.7.0

package/README.md

@@ -40,6 +40,7 @@ check for a specific failure mode found the same way — see `DECISIONS.md` for
   - [Database schema (optional)](#database-schema-optional)
   - [An ERD of your database schema (optional)](#an-erd-of-your-database-schema-optional)
   - [Applying DDL to a live database (optional)](#applying-ddl-to-a-live-database-optional)
+  - [Splicing real Java source (optional, java-spring only)](#splicing-real-java-source-optional-java-spring-only)
   - [Declaring field-to-field dependencies (optional)](#declaring-field-to-field-dependencies-optional)
   - [Patching a config file (optional)](#patching-a-config-file-optional)
   - [Signed gate attestations (optional)](#signed-gate-attestations-optional)
@@ -77,8 +78,14 @@ production -- which still splits the same way it always has:
   `DECISIONS.md`'s `D-handle-registry-enforcement`/`D-resolver-authorization-action-aware`. Real
   gaps remain and are explicitly still open, not closed: registry enforcement is opt-in, off by
   default; authorization inference now recognizes both `@PreAuthorize(hasRole(...))` and
-  `hasAuthority(...)` (see `DECISIONS.md`'s `D-resolver-authorization-action-aware`), but
-  `hasAnyRole`/`hasAnyAuthority` (list-shape), ownership, and tenant policy are still unaddressed.
+  `hasAuthority(...)` (see `DECISIONS.md`'s `D-resolver-authorization-action-aware`) via an explicit
+  per-action policy contract (`D-resolver-policy-contract`) -- a companion annotation this scanner
+  cannot safely evaluate (`@PostAuthorize`, `@Secured`, `@RolesAllowed`, ownership/tenant checks,
+  `hasAnyRole`/`hasAnyAuthority`) now refuses auto-materialization and generates an
+  `AuthorizationPolicy` interface that blocks the target app from starting until a human implements
+  it -- ships default-on, `handles emit` exits non-zero (23) until acknowledged with `--force
+  --reason` or the policy is implemented. `hasAnyRole`/`hasAnyAuthority` list-shapes remain
+  unaddressed (deliberately, see `D-resolver-policy-contract`'s own EXIT).
   All three providers (Java/Python/TypeScript) now generate a real `sbf_handle`/
   `sbf_handle_snapshot` schema and support `--enforce-registry`/`recover()` -- TypeScript's own
   registration mechanism is a higher-order wrapper function, not a decorator (no Java-AOP or
@@ -376,6 +383,49 @@ the DDL surface at all unless a signing key was also given. See `D-ddl-apply` in
 the full design and every explicitly-deferred boundary (non-Postgres databases, connection
 pooling, production safety rails).
 
+### Splicing real Java source (optional, java-spring only)
+
+`bskel patch propose --kind java-source-splice` extends the same lifecycle to a third kind: a
+closed, four-operation vocabulary for editing REAL, hand-written `.java` source --
+`replace-method-body`, `insert-method-body-prologue`, `replace-field-initializer`, `add-import`.
+A member is located by its language-guaranteed identity (a type's fully-qualified name plus, for a
+method, its erased parameter types — the same rule javac itself uses to forbid two overloads
+sharing one erased signature), resolved via a real JavaParser+Symbol Solver pass and cross-checked
+by an independent, non-AST falsifier before anything is written. The postcondition is a real
+`./gradlew compileJava`; a failure automatically restores the original file, never leaves a broken
+one in place:
+
+```bash
+cat > splice.json <<'EOF'
+{
+  "schema": "sbf.java-source-splice/1",
+  "file": "src/main/java/com/example/demo/domain/widget/application/WidgetServiceImpl.java",
+  "edits": [{
+    "op": "replace-method-body",
+    "locator": {
+      "type_fqn": "com.example.demo.domain.widget.application.WidgetServiceImpl",
+      "member_kind": "method",
+      "member_name": "updateWidget",
+      "erased_param_types": ["java.util.UUID", "com.example.demo.domain.widget.presentation.dto.UpdateWidgetRequest"]
+    },
+    "replacement": "{\n\t\treturn widgetRepository.save(findWidget(widgetId));\n\t}"
+  }]
+}
+EOF
+bskel patch propose --feature 001-widget-management --kind java-source-splice --splice-file splice.json
+bskel patch approve --feature 001-widget-management --transaction <id> --reason "..."
+bskel patch apply   --feature 001-widget-management --transaction <id> --confirm WidgetServiceImpl#updateWidget
+```
+
+Every edit outside the four ops refuses outright (no member add/remove/rename, no signature/
+annotation edits, no nested/inner/anonymous/local types, no multi-top-level-type files, no
+`apply-diff`) — there is no general-purpose patch/diff applier here, only grammar-delimited,
+independently-verified regions. Requires the bundled AST helper (`bskel doctor` reports readiness
+under "java-source-splice prerequisites"). Python/TypeScript source splicing is not supported —
+neither has an equivalent AST helper or whole-project compile check in this repo. See
+`D-java-source-splice` in `DECISIONS.md` for the full three-mechanism node-identity design and
+every explicitly-deferred boundary.
+
 ### Declaring field-to-field dependencies (optional)
 
 When one feature's data actually depends on another feature's (e.g. a `WidgetDto.name` that's
@@ -393,6 +443,44 @@ bskel dependency remove --feature 001-widget-management --resource WidgetDto --f
   --reason "no longer coupled"
 ```
 
+### Cross-feature impact graph: field-level change detection with a mandatory disposition (optional)
+
+`bskel dependency declare` above records that an edge EXISTS; it does not, by itself, tell the
+*source* feature when its own contract/resource shape actually changes in a way that breaks the
+downstream side. `bskel impact check`/`bskel impact accept` close that gap -- an `impact` gate,
+complementing `dependencies`, that blocks the feature that CHANGED (not just the one depending on
+it) until every downstream impact has an explicit `compatible`/`migrate`/`waive` disposition:
+
+```bash
+bskel impact accept --feature 002-organization-management            # capture the first baseline
+# ... later, OrganizationDto.taxRate's backing file changes ...
+bskel impact check --feature 002-organization-management --json      # names the exact change_key + downstream feature
+bskel impact disposition --feature 002-organization-management \
+  --change <change_key> --downstream 001-widget-management \
+  --mode compatible --reason "purely additive"                       # or --mode migrate --tracked-by "ISSUE-42"
+                                                                       #    or --mode waive --expires-days 14
+bskel impact accept --feature 002-organization-management            # unblocked; advances the baseline
+bskel impact check --all --json                                      # the recommended CI invocation -- sweeps every feature
+```
+
+A `migrate` disposition creates a real two-sided handshake: it records an INBOUND obligation on the
+downstream feature (`001-widget-management` here), whose own `impact` gate stays blocked until it
+runs `bskel impact ack --feature 001-widget-management --from 002-organization-management --change
+<change_key> --reason "..."`. Every disposition key embeds a hash of the NEW change, so a
+disposition recorded for one shape never silently covers a later, different change to the same
+field -- there is no wildcard. Only `proven` (exact-identity) impacts block; `heuristic` ones
+(a guessed table name, a lower-confidence collision) are always reported, never blocking on their
+own. Not a `handles emit` prerequisite (gated only at `bskel verify`) -- this repo's own
+`cross_feature`-gate CI incident is why. See `D-cross-feature-impact-graph` in `DECISIONS.md`.
+
+`bskel impact export --format graphify|json|mermaid [--out <path>] [--focus <node-id>] [--rings N]`
+is the one LLM-free seam to an exploration layer: `--format graphify` writes the locally-installed
+`graphify` skill's own native extraction file shape directly (no install/detect/extract steps, no
+LLM call, no network) -- a consumer runs `graphify.build.build_from_json()` + `cluster()` +
+`to_obsidian()` on it to get a browsable Obsidian vault of the whole cross-feature graph.
+`--focus`/`--rings` write a Focus+Context data projection (`ring`/`detail`, inspired by Lamping/
+Rao/Pirolli's 1995 hyperbolic-tree technique) into the export only -- never read back by any gate.
+
 `bskel serve [--port N] [--host <addr>]` starts a small local HTTP server (loopback-only by
 default, matching this project's "safe default, explicit override" convention) that serves a
 read-only browser UI at `/` for the whole repo's dependency graph, backed by `GET /api/graph`. The
@@ -429,10 +517,13 @@ bskel patch apply --feature 001-organization-management --transaction <id>
 
 ### Signed gate attestations (optional)
 
-`bskel gate export` already produces a CI-independent report of every gate's current status. Add
-`--sign --key <privateKeyPath>` to detached-sign it (Ed25519, via Node's own `crypto` module — no
-new dependency), then verify it offline, on any machine, without network access or trusting
-whatever produced it:
+`bskel gate export` already produces a CI-independent report of every gate's current status,
+including a `live` verdict RECOMPUTED at export time (so a gate whose stored record still says
+`pass` but whose inputs have since changed is honestly reported as `stale`, never silently signed
+as passing), the tool's own version, git tree identity, unconditional artifact hashes, and a
+forced/revoked/waiver roll-up. Add `--sign --key <privateKeyPath>` to detached-sign it (Ed25519,
+via Node's own `crypto` module — no new dependency), then verify it offline, on any machine,
+without network access or trusting whatever produced it:
 
 ```bash
 bskel attest keygen --out ~/.bskel-keys        # writes attest-private.pem (0600) + attest-public.pem
@@ -441,8 +532,16 @@ bskel gate export --feature 001-organization-management \
 bskel attest verify --file attestation.json --pubkey ~/.bskel-keys/attest-public.pem
 ```
 
-`attest verify`'s exit code reflects signature validity only — whether the gates inside actually
-passed is a separate, printed summary. See `D-gate-attestation-signing` in `DECISIONS.md`.
+`--sign` refuses a dirty working tree (same `--allow-dirty` convention `bskel preflight` already
+uses) — the acknowledgement, if you pass it, is recorded inside the signed payload itself, not just
+a flag you happened to type. `attest verify`'s exit code reflects signature validity only — whether
+the gates inside actually passed is a separate, printed summary. Three opt-in, default-off checks
+narrow what "valid" is allowed to mean for your use case without touching that exit-code contract:
+`--expect-head <sha>` (refuse an attestation about the wrong commit), `--max-age-minutes N`
+(refuse a stale one), `--reject-dirty` (refuse one signed over an acknowledged-dirty tree) — each
+failing exits `22`, distinct from `1` (signature invalid), so "authentic but not what you asked
+for" is never confused with "not authentic". See `D-gate-attestation-signing` and
+`D-attestation-payload-completeness` in `DECISIONS.md`.
 
 ### Signed observe receipts (optional)
 
@@ -552,6 +651,12 @@ checking" pass). Highlights (full record in `DECISIONS.md`'s "Security hardening
 - **Authority derivation is per-method, not per-file** — a controller's first `@PreAuthorize` match
   no longer silently applies to every resolver generated from that file; an unsupported annotation
   shape (`hasAnyRole`, SpEL) fails closed to a `TODO_ROLE` placeholder rather than guessing.
+- **A companion authorization annotation (`@PostAuthorize`, `@Secured`, `@RolesAllowed`) next to an
+  otherwise-safe `@PreAuthorize` refuses auto-materialization entirely** (`D-resolver-policy-contract`)
+  — a real, closed IDOR: `@PreAuthorize("hasRole('USER')")` sitting beside
+  `@PostAuthorize("returnObject.ownerId == authentication.name")` used to auto-materialize `ROLE_USER`
+  and silently ignore the ownership check. `handles emit` now generates an `AuthorizationPolicy`
+  interface that blocks the target app from starting (not the build) until a human implements it.
 - **Handle recovery cross-checks type/kind/pointer against the registry row**, not just the raw
   UUID — the most severe finding: an attacker who controls the handle's `type` field could
   otherwise request a different, more sensitive resource's snapshot history that happens to share