@raishin/vanguard-frontier-agentic 3.2.0 → 3.4.0

package/skills/java/java-transaction-and-consistency/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "java-transaction-and-consistency",
+  "name": "java-transaction-and-consistency",
+  "version": "0.1.0",
+  "type": "skill",
+  "provider": "java",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Statically reviews Spring @Transactional boundary correctness — propagation, isolation, readOnly, rollbackFor, proxy self-invocation, and boundary width — plus cross-resource consistency, flagging the save()-then-send() dual-write anti-pattern, missing outbox/relay, and post-commit side effects that skip TransactionSynchronization or REQUIRES_NEW. Reads source and sanitized configuration only.",
+  "source_type": "original",
+  "official_docs": [
+    "https://docs.spring.io/spring-framework/reference/data-access/transaction.html",
+    "https://jakarta.ee/specifications/transactions/",
+    "https://microservices.io/patterns/data/transactional-outbox.html",
+    "https://microservices.io/patterns/data/saga.html"
+  ],
+  "security_notes": "Static review only — reads Spring @Transactional-annotated classes, service/repository call graphs, and sanitized transaction-manager/datasource/broker configuration; never opens a database or broker connection, starts or commits a transaction, or executes code. Never requests connection strings, credentials, tenant identifiers, or customer data; ask for source with placeholders.",
+  "last_verified": "2026-07-17",
+  "path": "skills/java/java-transaction-and-consistency",
+  "author": "github: Raishin"
+}

package/skills/java/java-transaction-and-consistency/references/dual-write-outbox-and-saga-patterns.md

@@ -0,0 +1,125 @@
+# Dual-Write, Outbox, and Saga Patterns
+
+> Static review only. Every conclusion below requires the actual write-then-publish (or write-then-call) call site as evidence — a consistency claim without seeing both operations, and whether they share a transaction, is `inference (partial source)` or `assumption (source absent)`. Sources: the transactional outbox and saga patterns as documented on microservices.io (Chris Richardson's pattern catalog, the commonly cited reference for these two patterns); Jakarta Transactions (JTA) specification for the XA/2PC model these patterns exist to avoid at the cross-service level. Broker-specific delivery-semantics details (Kafka's idempotent producer, `transactional.id`, consumer `isolation.level`) are explicitly out of scope here — see the escalation section.
+
+## The dual-write problem
+
+```java
+@Service
+public class OrderService {
+
+    @Transactional
+    public void placeOrder(Order order) {
+        orderRepository.save(order);        // resource #1: the database
+        eventPublisher.publish(              // resource #2: the broker
+            new OrderPlacedEvent(order.getId())
+        );
+        // BAD: these two writes are to two independent resources.
+        // The @Transactional boundary only covers the database. If the
+        // process crashes, the broker is unreachable, or the publish
+        // call throws AFTER the DB transaction has already committed
+        // (or even mid-commit, depending on where publish() sits
+        // relative to the transaction's actual commit point), the
+        // event is silently lost. If publish() is retried on a
+        // transient failure after the DB already committed, the event
+        // can be silently duplicated instead.
+    }
+}
+```
+
+There is no ordering of `save()` and `publish()` inside a single `@Transactional` method that makes this atomic — a relational database commit and a message-broker publish are two separate resource managers with no shared commit protocol in this design. This holds whether `publish()` runs before or after `save()`, and whether it runs inside or outside the annotated boundary; moving it does not fix the fundamental problem, it only changes which side is more likely to lose the race.
+
+## The remedy: transactional outbox
+
+```java
+@Service
+public class OrderService {
+
+    @Transactional
+    public void placeOrder(Order order) {
+        orderRepository.save(order);
+        // GOOD: write the intent to publish into an outbox table, in
+        // the SAME database transaction as the order write. Either
+        // both rows exist after commit, or neither does — ordinary
+        // single-resource ACID, no distributed coordination needed.
+        outboxRepository.save(new OutboxEvent(
+            "OrderPlaced", order.getId(), toJson(order)
+        ));
+    }
+}
+
+// A SEPARATE process — a polling relay or a CDC-based reader
+// (e.g. reading the outbox table's change stream) — reads unpublished
+// outbox rows and publishes them, marking each processed only after
+// a successful publish acknowledgment. This relay's own delivery
+// guarantees (retry, dedup, ordering) are what actually need
+// verifying — not the original save() call site.
+```
+
+The outbox pattern converts a two-resource atomicity problem into a single-resource one (the DB write of the business row *and* the outbox row happen together, ordinarily) plus a separately-verifiable relay problem (does the relay eventually publish every unprocessed row, and does it avoid publishing the same row twice in a way consumers can't tolerate). Flag a design that writes directly to the broker from the request-handling transaction as needing an outbox; flag an outbox implementation that lacks a described relay (a table that fills up with rows nothing ever reads is not a working outbox).
+
+## Post-commit side effects that aren't publish-to-a-broker
+
+The same class of bug shows up for any post-commit side effect, not just messaging — calling another service synchronously, invalidating a cache, sending a notification:
+
+```java
+@Transactional
+public void approveOrder(Order order) {
+    order.setStatus(APPROVED);
+    orderRepository.save(order);
+    // BAD: if the transaction rolls back after this line runs (e.g. a
+    // later step in the same method throws), the notification has
+    // already gone out for an approval that never actually committed.
+    notificationService.sendApprovalEmail(order);
+}
+```
+
+```java
+@Service
+public class OrderService {
+
+    @Transactional
+    public void approveOrder(Order order) {
+        order.setStatus(APPROVED);
+        orderRepository.save(order);
+        // GOOD: defer the side effect until commit is guaranteed.
+        TransactionSynchronizationManager.registerSynchronization(
+            new TransactionSynchronization() {
+                @Override
+                public void afterCommit() {
+                    notificationService.sendApprovalEmail(order);
+                }
+            }
+        );
+    }
+}
+
+// Or, declaratively, with an application event:
+@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+public void onOrderApproved(OrderApprovedEvent event) {
+    notificationService.sendApprovalEmail(event.getOrder());
+}
+```
+
+`registerSynchronization`/`@TransactionalEventListener(phase = AFTER_COMMIT)` only guarantee the callback runs after the *current* transaction manager's commit — they do not make the side effect itself durable or exactly-once. If the process crashes between commit and the callback executing, the side effect is still lost; for a side effect that must survive that gap, it needs the same outbox treatment as messaging, not just an `AFTER_COMMIT` listener. Flag an `AFTER_COMMIT` listener presented as a complete fix for a side effect that must not be lost — it closes the pre-commit race but not the post-commit crash window.
+
+## Cross-service atomicity: XA/2PC versus saga
+
+A distributed transaction manager (XA, two-phase commit) can, in principle, make a database write and another XA-capable resource commit atomically. Across genuinely independent, separately-deployed services this is usually the wrong tool:
+
+- It requires every participant to support and correctly implement the XA protocol — most modern message brokers and NoSQL/managed data stores do not.
+- The coordinator becomes a single point of blocking: participants hold locks (and, for a DB participant, connections) until the coordinator resolves the transaction, which couples the availability of every service to the coordinator and to each other.
+- It does not compose across organizational/deployment boundaries the way a single-service ACID transaction does.
+
+The alternative for cross-service consistency is a **saga**: a sequence of local transactions, each in its own service, where every forward step that has an externally-visible effect is paired with a **compensating action** that semantically undoes it if a later step fails. Sagas can be **choreographed** (each service reacts to the previous service's event) or **orchestrated** (a coordinator service explicitly sequences the steps); either way, two properties are non-negotiable:
+
+1. **Every forward step's side effect has a compensation.** A step that reserves inventory needs a "release reservation" compensation; a step that charges a card needs a "refund" compensation — not just a log entry saying it should have one.
+2. **Every step (forward and compensating) is idempotent and safe to invoke on a step that never actually ran**, because retries and at-least-once delivery mean a step or its compensation can be invoked more than once, or a compensation can be invoked for a step that failed before doing anything.
+
+Flag a design that assumes a distributed transaction manager makes cross-service calls atomic; flag a saga missing a compensation for any forward step with an externally-visible effect; flag a saga whose steps are not clearly idempotent.
+
+## Escalation conditions
+
+- The finding is really about the broker client's own delivery guarantees — idempotent producer configuration, `transactional.id`, consumer `isolation.level`, offset-commit strategy — rather than whether a dual write exists at all → hand to `java-kafka-reliability-agent`; this agent's job stops at "this needs an outbox / transactional wiring," not designing that wiring.
+- The finding is about `@Transactional` propagation/isolation/rollback on the database side alone, with no second resource involved → see `propagation-isolation-and-proxy-pitfalls.md`; it is not a consistency finding by itself.
+- The user asks to verify actual delivery/exactly-once behavior against a running broker → out of scope for static review; describe what to test and who runs it.

package/skills/java/java-transaction-and-consistency/references/propagation-isolation-and-proxy-pitfalls.md

@@ -0,0 +1,112 @@
+# Propagation, Isolation, and Proxy Pitfalls
+
+> Static review only. Every conclusion below requires the actual `@Transactional` attributes *and* the call site (who invokes the method, and from where) as evidence — a propagation or rollback claim without both is `inference (partial source)` or `assumption (source absent)`. Sources: Spring Framework Reference — Data Access / Transaction Management (declarative transaction management, propagation, and rollback rules); Jakarta Transactions (JTA) specification for the underlying resource-transaction model Spring's `PlatformTransactionManager` abstracts over. Spring's default propagation and rollback behavior has been stable across recent Spring Framework major lines, but always confirm annotation defaults against the specific Spring Framework version in use before treating a version-specific detail as settled — this reference does not hardcode a version number.
+
+## Why propagation is the first thing to check
+
+`@Transactional` attributes on a method only fully apply when that method actually **starts** the transaction. Spring's declarative transaction management is proxy-based: it wraps the bean in an AOP proxy that opens/joins/suspends a transaction *before* the target method runs, and commits/rolls back *after* it returns. Everything below follows from that one mechanical fact.
+
+## Propagation semantics that get silently overridden
+
+| Propagation | Behavior when called with no existing transaction | Behavior when called from within an existing transaction |
+|---|---|---|
+| `REQUIRED` (default) | Starts a new transaction | **Joins** the caller's transaction — the method's own `isolation`/`timeout` are silently ignored; `readOnly` is honored only if the caller also declared it |
+| `REQUIRES_NEW` | Starts a new transaction | **Suspends** the caller's transaction, runs in a brand-new one, then resumes the caller's — the inner transaction can commit independently of the outer |
+| `MANDATORY` | Throws `IllegalTransactionStateException` | Joins the caller's transaction |
+| `SUPPORTS` | Runs non-transactionally | Joins the caller's transaction |
+| `NOT_SUPPORTED` | Runs non-transactionally | Suspends the caller's transaction and runs non-transactionally |
+| `NEVER` | Runs non-transactionally | Throws `IllegalTransactionStateException` |
+| `NESTED` | Starts a new transaction | Starts a nested transaction using a savepoint (JDBC `RESOURCE_LOCAL` only; not all `PlatformTransactionManager` implementations support it) |
+
+**The finding that matters most:** a `REQUIRED` method that declares `isolation = SERIALIZABLE`, `timeout = 5`, or similar, and is *also* called from another `@Transactional` method elsewhere in the codebase, will silently run at whatever isolation/timeout the outer transaction already established. If the call graph shows this method invoked both standalone and from inside another transaction, the inner attributes are unreliable by construction — flag it, don't just check the annotation in isolation.
+
+`REQUIRES_NEW` avoids that problem but introduces a different one: the inner transaction can commit even if the outer later rolls back. That is sometimes exactly what's wanted (e.g., an audit-log write that must survive the caller's rollback) and sometimes a bug (a "just to be safe" `REQUIRES_NEW` that breaks atomicity the caller assumed). The evidence needed to tell them apart is *why* the isolation was chosen — ask if it isn't stated.
+
+## Proxy self-invocation: the classic silent bypass
+
+```java
+@Service
+public class OrderService {
+
+    public void placeOrder(Order order) {
+        // BAD: calling another @Transactional method on `this` goes
+        // straight to the method body — it never passes through the
+        // Spring-generated proxy, so @Transactional on saveOrder() below
+        // is a complete no-op here: no transaction is started, no
+        // rollback rule applies, no propagation semantics fire.
+        this.saveOrder(order);
+    }
+
+    @Transactional
+    public void saveOrder(Order order) {
+        repository.save(order);
+    }
+}
+```
+
+This happens because Spring's default AOP is proxy-based (JDK dynamic proxies for interfaces, CGLIB subclassing for concrete classes): the proxy only intercepts calls that arrive from *outside* the bean. A call from one method to another on the same instance (`this.method()`, or simply calling a sibling method by its plain name) never goes through the proxy.
+
+Correct alternatives, in order of preference for most codebases:
+
+```java
+@Service
+public class OrderService {
+
+    // 1) Split the transactional method into a separate bean and
+    //    inject it — the cleanest fix, no proxy tricks required.
+    private final OrderWriter orderWriter;
+
+    public void placeOrder(Order order) {
+        orderWriter.saveOrder(order); // goes through orderWriter's proxy
+    }
+}
+
+@Component
+class OrderWriter {
+    @Transactional
+    void saveOrder(Order order) { repository.save(order); }
+}
+```
+
+Self-injection (`@Autowired private OrderService self;` then `self.saveOrder(order)`) or `AopContext.currentProxy()` (requires `exposeProxy = true` on the `@EnableAspectJAutoProxy`) both work but are easy to regress if a later edit reverts to `this.`; extraction to a separate bean is the more durable fix. Flag self-invocation regardless of which fix the codebase already uses elsewhere — check every `@Transactional` call site, not just the constructor-injected ones.
+
+## rollbackFor: checked exceptions do not roll back by default
+
+```java
+@Transactional // BAD if InventoryException is checked and unhandled here
+public void reserveStock(Order order) throws InventoryException {
+    inventory.decrement(order.getSku(), order.getQty()); // throws checked InventoryException
+    ledger.record(order); // never runs if the exception above propagates —
+                           // but the transaction still COMMITS on the way out
+}
+```
+
+Spring's default rollback rule is: roll back on unchecked `RuntimeException` and `Error`; **commit** on a checked exception unless told otherwise. This is the exact inverse of what most developers expect from "an exception happened, surely it rolled back." The fix is explicit:
+
+```java
+@Transactional(rollbackFor = InventoryException.class)
+public void reserveStock(Order order) throws InventoryException { ... }
+```
+
+Flag every checked exception declared or thrown from a `@Transactional` method that lacks a matching `rollbackFor` (or a global convention enforced elsewhere, such as wrapping checked exceptions in an unchecked wrapper before they leave the method — verify that convention actually holds at the site under review rather than assuming it).
+
+## readOnly: an optimization hint, not just documentation
+
+`readOnly = true` is a hint to the underlying resource: Hibernate can skip dirty-checking/flush, and some `DataSource`/driver/pool combinations route read-only connections differently (e.g., to a read replica, or reject a write outright). **This behavior is infrastructure-dependent** — Spring and JPA do not guarantee a specific outcome for a write inside a `readOnly = true` transaction; it can silently no-op, silently succeed, or throw, depending on the driver and pool configuration in use. Treat a write inside a `readOnly = true` method as a defect regardless of which of those three outcomes the current stack happens to produce, and mark the exact runtime consequence as `unknown` unless the driver/pool configuration was provided.
+
+## Isolation levels: name the anomaly, and mind vendor differences
+
+| Level | Prevents |
+|---|---|
+| `READ_UNCOMMITTED` | Nothing extra beyond `DEFAULT`'s DB baseline |
+| `READ_COMMITTED` | Dirty reads |
+| `REPEATABLE_READ` | Dirty reads, non-repeatable reads |
+| `SERIALIZABLE` | Dirty reads, non-repeatable reads, phantom reads |
+
+Treat this table as the *conceptual* SQL-standard mapping, not a promise about every database's actual implementation: some vendors alias `READ_UNCOMMITTED` up to `READ_COMMITTED`, and `REPEATABLE_READ`/`SERIALIZABLE` are implemented differently across engines (locking vs. MVCC/snapshot). Without knowing the target database and version, treat any claim about which specific anomaly a chosen isolation level prevents *on that database* as `inference (partial source)` at best.
+
+## Escalation conditions
+
+- The consistency question is really about a broker's producer/consumer transactional configuration (idempotent producer, `transactional.id`, `isolation.level`) rather than the application's transaction boundary → hand to `java-kafka-reliability-agent`.
+- The slow-query or N+1 symptom sits inside a correctly-bounded transaction → hand to `java-jpa-hibernate-performance-agent`; boundary correctness and query shape are separate defects.
+- The user asks to actually run the code to observe commit/rollback behavior → out of scope for static review; describe what to instrument and who runs it.

package/skills/java/java-transaction-and-consistency/references/workflow-and-output.md

@@ -0,0 +1,94 @@
+# Workflow and Output Contract
+
+> Static review only. Read `@Transactional`-annotated classes, their call graph, and sanitized configuration (transaction-manager beans, datasource pool settings, broker client config only insofar as it evidences a dual write). Never open a database or broker connection, start or commit a transaction, or execute code. Ask for source with placeholders — never connection strings, credentials, tenant identifiers, or customer data.
+
+## Workflow
+
+### Step 1 — Collect inputs
+
+Ask the user for whichever apply, sanitized:
+- The `@Transactional`-annotated method(s) under review, with their full attribute list (`propagation`, `isolation`, `readOnly`, `rollbackFor`/`noRollbackFor`, `timeout`).
+- The call graph: who invokes each `@Transactional` method, and from where (same class/bean vs. a different bean; inside an existing transaction vs. not).
+- Any sequence where a database write is followed by a message/event publish, a call to another service, or a cache update.
+- Any post-commit side-effect handling already in place (`TransactionSynchronization`, `@TransactionalEventListener`, an outbox table, a saga orchestrator/choreography).
+- Relevant configuration: the `PlatformTransactionManager`/datasource bean setup, connection-pool settings if boundary width is in scope, and whether an outbox/relay or saga infrastructure already exists.
+
+If the call site or the annotation attributes are missing for a method under discussion, downgrade that finding to `inference (partial source)` or `assumption (source absent)` and say so.
+
+### Step 2 — Map propagation and rollback per method
+
+For each `@Transactional` method, record: propagation, isolation, readOnly, rollbackFor/noRollbackFor, and every checked exception it declares or can throw. Cross-reference against the default rollback rule (unchecked + `Error` only) to find gaps.
+
+### Step 3 — Trace every call site for self-invocation and join behavior
+
+For each `@Transactional` method, determine: is it ever called from another method on the *same* bean (self-invocation — flag unconditionally)? Is it ever called from within another `@Transactional` method elsewhere (a `REQUIRED` join — its own isolation/timeout are then unreliable)? Is its boundary width limited to DB work, or does it wrap an external call?
+
+### Step 4 — Detect dual-write and post-commit races
+
+For each sequence that writes to the database and then touches a second resource (broker, service call, cache): is the second write inside the same DB transaction (it can't truly be — flag if the code implies otherwise), deferred to `AFTER_COMMIT`, or routed through an outbox? A direct publish/call with no outbox and no `AFTER_COMMIT` deferral is the dual-write anti-pattern regardless of ordering.
+
+### Step 5 — Assess cross-service consistency design
+
+If the consistency question spans services: is atomicity attempted via a distributed transaction manager (flag as fragile) or a saga? If a saga, does every forward step with an externally visible effect have a paired, idempotent compensation, and are steps idempotent under retry?
+
+### Step 6 — Produce the output
+
+Format using the Output contract below. Pick each remedy by the actual resources and call graph involved; never recommend a manual pseudo-outbox, a blanket `REQUIRES_NEW` everywhere, or XA/2PC across service boundaries as a default.
+
+## Evidence checklist
+
+- [ ] `@Transactional` attributes for each method in scope
+- [ ] Call graph (same-bean self-invocation and cross-transaction joins)
+- [ ] Any write-then-publish/call/cache sequence and its resource boundaries
+- [ ] Existing post-commit handling (`AFTER_COMMIT`, outbox, saga infrastructure)
+- [ ] Transaction-manager and pool configuration (if boundary width is in scope)
+
+Each unchecked item downgrades the related findings to `inference` or `assumption`.
+
+## Findings rubric
+
+| Severity | Criteria |
+|----------|----------|
+| critical | Proxy self-invocation silently skipping `@Transactional`; checked exception with no `rollbackFor` committing a failed write; save()-then-send() dual write with no outbox; a required isolation/timeout silently dropped under a `REQUIRED` join with a stated correctness dependency on it. |
+| high | Over-wide boundary wrapping an external call; post-commit side effect not deferred to `AFTER_COMMIT`/outbox; `readOnly = true` performing a write; cross-service atomicity attempted via XA/2PC. |
+| medium | Unjustified relaxed isolation level; `REQUIRES_NEW` used without stating the commit-independence trade-off; incomplete saga compensation coverage. |
+| low | Large batch operation in one long-lived transaction; a genuinely read-only method missing `readOnly = true`. |
+
+Every finding carries an evidence-basis label: `confirmed (source provided)`, `inference (partial source)`, `assumption (source absent)`, or `unknown`.
+
+## Output contract
+
+```
+## Verdict
+<pass | pass-with-conditions | block>
+
+## Evidence level
+<full source | partial source | inference>
+
+## Findings
+
+### CRITICAL
+- [C1] <finding> — <evidence basis> — <call site / resource pair> — <remedy: rollbackFor / de-duplicate self-invocation / outbox / AFTER_COMMIT>
+
+### HIGH
+- [H1] <finding> — <evidence basis> — <description> — <remediation>
+
+### MEDIUM
+- [M1] <finding> — <evidence basis> — <description> — <remediation>
+
+### LOW
+- [L1] <finding> — <evidence basis> — <description> — <remediation>
+
+## Safe next actions
+1. <action>
+
+## Open questions
+- <annotation attribute, call site, or resource boundary the user must supply>
+```
+
+## Security notes
+
+- Never request or accept connection strings, credentials, tenant identifiers, or customer data. Ask for source with placeholders.
+- Static review only: never open a database or broker connection, start or commit a transaction, or execute code.
+- Never recommend a manual pseudo-two-phase workaround, a blanket `REQUIRES_NEW`, or XA/2PC across service boundaries as a default fix.
+- Never recommend disabling a failing gate as the fix.

package/skills/php/composer-audit-supply-chain-review/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: composer-audit-supply-chain-review
+description: Use this skill to review PHP Composer dependency supply-chain posture — whether composer audit is wired into CI with a failing exit-code gate on security advisories, whether config.policy.advisories.audit and config.policy.abandoned settings are configured to actually surface risk, whether abandoned packages have a tracked replacement plan, and whether composer.lock is present, current, and pins dependencies at security-sensitive boundaries. Use when a vulnerable or abandoned Packagist dependency could reach production because the audit gate is missing or non-blocking, an abandoned package has no owner, or the lock file is absent, drifted, or bypassed by unpinned constraints. Static review only; it never installs packages, runs Composer commands, or contacts Packagist.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-16"
+  category: security
+  lifecycle: experimental
+---
+
+# Composer Audit & Supply-Chain Review
+
+## Purpose
+
+Review a PHP project's Composer dependency supply chain so a vulnerable or abandoned Packagist package cannot reach production unnoticed. The dominant failure modes are `composer audit` missing from CI (or present but not gating on its exit code), advisory/abandoned policy configured to report instead of fail, abandoned packages with no tracked replacement, and `composer.lock` that is absent, drifted, or undermined by unpinned dependency constraints at security-sensitive boundaries.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review whether `composer audit` actually gates CI on security advisories, rather than merely running and being ignored,
+- review `config.policy.advisories.audit` / `config.policy.abandoned.audit` / `config.policy.abandoned.block` settings for a PHP project,
+- assess abandoned Packagist dependencies for replacement-plan coverage,
+- review whether `composer.lock` is present, current, and consistent with `composer.json`,
+- review dependency pinning at security-sensitive boundaries (auth, crypto, serialization, payment) for unpinned or overly wide version constraints.
+
+## When not to use
+
+Do not use this skill for:
+
+- installing, updating, or removing packages, or running `composer install`/`update`/`audit` against any live, sandbox, or CI environment — this skill is static review only.
+- application architecture or dependency-injection redesign, or choosing a specific replacement package on the team's behalf — name the risk and hand the decision to the owning engineer.
+- reviewing non-Composer package ecosystems (npm, pip, RubyGems, etc.) — this skill is Composer/Packagist-specific.
+- asserting a specific deployment is free of vulnerable dependencies from configuration review alone; a clean-looking policy does not prove the last audit run was clean.
+
+## Preconditions
+
+- `composer.json` (including any `config.policy` block) and `composer.lock`, if one exists, for the project in scope.
+- The CI pipeline definition(s) that build, test, or deploy the project, to confirm whether `composer audit` runs and whether its exit code gates the pipeline.
+- Any existing `composer audit` output, report, or CI log excerpt available for the repository.
+- The Composer version in use or its constraint, since `config.policy.abandoned.audit` defaults differ between Composer 2.6 (`report`) and Composer 2.7+ (`fail`).
+- Any documented accepted-risk exceptions for specific advisories or abandoned packages, if the team maintains them.
+
+## Lean operating rules
+
+- Confirm `composer audit` is both present in CI and gating — its non-zero exit code must actually fail the job, not be discarded or logged past.
+- Read `config.policy.advisories.audit` and the `config.policy.abandoned.*` keys from `composer.json`; where a key is unset, apply the documented default for the project's Composer version rather than assuming a value.
+- Treat `composer.lock` absence for an application as a blocking finding on its own; the documented exception is that a library is not required to commit its lock file.
+- Treat `composer.lock` drift from `composer.json` (stale-lock warnings, hash mismatches) as a distinct finding from lock absence.
+- Flag unpinned or overly wide version constraints at security-sensitive boundaries even when a lock file exists, since the next `composer update` can still move far without review.
+- Never fabricate an advisory ID, CVE number, or package name; report a gap in evidence rather than inventing an identifier.
+- Label every claim `repo evidence`, `documentation-based`, or `inference`.
+
+## Context7 documentation protocol
+
+This skill's allowed tools are Read, Grep, and Glob only — it does not call Context7 or any live documentation lookup at review time. Every Composer-specific behavioral claim (exit codes, `config.policy` key names and defaults, lockfile semantics) must instead be grounded in the bundled reference files, which are sourced from the official Composer documentation and dated at authoring time. If a claim cannot be traced to a bundled reference or to evidence in the repository, label it an assumption rather than asserting it as documented behavior. See [official sources](references/composer-audit-policy.md), [abandoned-and-advisory governance](references/abandoned-and-advisory-governance.md), and [lockfile integrity](references/lockfile-integrity.md).
+
+## Workflow
+
+Follow the review in this order: (1) locate every CI job that builds, tests, or deploys the project and check for a `composer audit` step; (2) confirm that step's exit code is not suppressed (no `|| true`, no `continue-on-error`, no output-only reporting); (3) read `config.policy.advisories.audit` and the `config.policy.abandoned.*` keys, comparing against documented defaults for the Composer version in use; (4) check for abandoned packages already flagged in any available audit output or lockfile metadata, and whether a replacement plan or accepted-risk exception exists; (5) confirm `composer.lock` is present and check for drift against `composer.json`; (6) scan dependency constraints for unpinned or overly wide ranges at security-sensitive boundaries; (7) emit findings with evidence tiers, concrete remediation, and ownership handoffs.
+
+## Decision gates
+
+- Block only when `composer audit` is not run in CI with a failing exit-code gate on advisories, when an abandoned package has no replacement plan, or when `composer.lock` is absent, drifted, or dependencies are floated unpinned at a security-sensitive boundary.
+- Every Composer-specific claim traces to a bundled reference file or explicit repository evidence, never memory.
+- No advisory ID, CVE, or package name is asserted without repository evidence backing it.
+- Application architecture and replacement-package selection are handed to the owning engineer, never decided here.
+
+## Evidence classification
+
+Label each finding `repo evidence` (seen directly in `composer.json`, `composer.lock`, or CI configuration), `documentation-based` (a Composer-documented default or behavior from the bundled references), or `inference` (a reasonable conclusion not directly observed). A documented default never proves what a specific project's configuration actually is — check the file before asserting the default applies.
+
+## Security and privacy constraints
+
+Static review only. Never install packages, run `composer install`/`update`/`audit`, or make any network call to Packagist or any registry. Never fabricate advisory IDs, CVE numbers, or package names — report missing evidence instead. Treat any credential found in `auth.json` or Composer configuration as a redact-and-flag finding, never echoed in output.
+
+## Escalation conditions
+
+Escalate to incident response on any evidence a known-vulnerable or already-flagged-abandoned dependency is already reachable from a production deployment path (e.g. a deployment manifest pinning a version an existing audit output already flags). Escalate abandoned-package findings with no owner to the responsible engineering team as a tracked risk item rather than a routine comment.
+
+## References
+
+Load these only when needed:
+
+- [Composer audit policy](references/composer-audit-policy.md) — `composer audit` behavior, exit codes, and `config.policy.advisories.audit` gating.
+- [Abandoned and advisory governance](references/abandoned-and-advisory-governance.md) — `config.policy.abandoned.audit`/`config.policy.abandoned.block` and replacement-plan review criteria, with OSS-risk context.
+- [Lockfile integrity](references/lockfile-integrity.md) — `composer.lock` presence, drift, and dependency-pinning review criteria.
+
+## Response minimum
+
+Return, at minimum:
+
+- the CI audit-gating state (present and failing / present but non-gating / absent), labeled with evidence tier;
+- the `config.policy.advisories.audit` and `config.policy.abandoned.*` configuration state, compared against documented defaults for the Composer version in use;
+- abandoned-package findings with replacement-plan status;
+- `composer.lock` presence/freshness state and any unpinned-constraint exposure at security-sensitive boundaries;
+- concrete remediation and an exact verification step for each finding;
+- ownership handoffs and any incident-response escalation.
+
+## Anti-goals
+
+- Do not install packages, run any Composer command, or contact Packagist or any registry.
+- Do not fabricate advisory IDs, CVE numbers, or package names not present in repository evidence.
+- Do not redesign application architecture or select a replacement package on the team's behalf.
+- Do not present the general OSS-risk statistics used as motivation as a finding specific to the repository under review.
+- Do not assert a Composer behavior from memory when it is not grounded in a bundled reference or repository evidence.

package/skills/php/composer-audit-supply-chain-review/metadata.json

@@ -0,0 +1,20 @@
+{
+  "id": "composer-audit-supply-chain-review",
+  "name": "Composer Audit & Supply-Chain Review",
+  "type": "skill",
+  "provider": "php",
+  "harnesses": ["claude-code", "cursor", "codex", "gemini", "kiro", "other"],
+  "summary": "Skill for reviewing Composer dependency supply-chain posture: composer audit advisory scanning and CI exit-code gating, config.policy advisory/abandoned settings, and composer.lock integrity and drift, so a vulnerable or abandoned Packagist dependency cannot reach production ungated.",
+  "source_type": "original",
+  "official_docs": [
+    "https://getcomposer.org/doc/03-cli.md",
+    "https://getcomposer.org/doc/06-config.md",
+    "https://getcomposer.org/doc/01-basic-usage.md",
+    "https://owasp.org/www-project-top-ten/"
+  ],
+  "security_notes": "Static-review-only skill: Read/Grep/Glob, no execution and no network mutation. Never installs, updates, or requires packages. Reports composer audit posture from configuration and lockfile evidence, never fabricates advisory identifiers, and treats any credential in auth.json or configuration as a redact-and-flag finding.",
+  "last_verified": "2026-07-16",
+  "path": "skills/php/composer-audit-supply-chain-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/php/composer-audit-supply-chain-review/references/abandoned-and-advisory-governance.md

@@ -0,0 +1,30 @@
+# Abandoned and Advisory Governance
+
+## Why this matters
+
+An abandoned Packagist package is not necessarily vulnerable today, but it will not receive a fix if a vulnerability is found tomorrow, and it will not receive a fix now for anything already discovered. Composer can be configured to surface this risk (or block it outright), but the defaults have changed across versions, and a project pinned to an older Composer release may be relying on weaker default behavior than its authors expect. This reference exists so a reviewer checks the actual configured (or defaulted) behavior rather than assuming abandonment is handled.
+
+## NORMATIVE facts
+
+- `config.policy.abandoned.audit` controls whether and how `composer audit` reports abandoned packages. Allowed values are `ignore`, `report`, and `fail`, matching the same semantics as the advisories policy: `ignore` does not report, `report` reports without a non-zero exit code, and `fail` causes a non-zero exit code. This setting applies only to audit reporting, not to whether abandoned packages can be installed or updated.
+- The default for `config.policy.abandoned.audit` became `fail` in Composer 2.7; it defaulted to `report` in Composer 2.6. A project's Composer version constraint therefore determines which default behavior actually applies unless the key is explicitly set.
+- `config.policy.abandoned.block` is a separate key that, when enabled, prevents abandoned packages from being installed during `update`, `require`, or `remove` operations. Its default value is `false` — meaning by default, Composer does not stop an abandoned package from being installed or updated, it can only be flagged during an audit.
+
+## Reviewer evidence criteria
+
+- Read `config.policy.abandoned.audit` and `config.policy.abandoned.block` directly from `composer.json`. Do not assume a default without first confirming the key is genuinely unset.
+- If `config.policy.abandoned.audit` is unset, determine the project's Composer version constraint (from `composer.json` `require.composer` or lockfile metadata, if present) to establish which default (`report` for 2.6, `fail` for 2.7+) actually applies, and flag the ambiguity if the version constraint is broad enough to span both.
+- Treat `config.policy.abandoned.block` left at its default `false` as expected baseline behavior, not itself a finding — but combine it with the next check: search for evidence of abandoned packages already present (audit output, lockfile package names cross-referenced against known-abandoned status if such evidence is provided) and confirm each has a tracked replacement plan (a migration ticket, a comment, or documented accepted-risk exception). An abandoned package with no replacement plan and no compensating audit-gating configuration is a blocking finding.
+- Never fabricate a package's abandoned status. Only report a package as abandoned when the repository provides direct evidence (an audit run's output, a Composer warning captured in a log, or an explicit note in project documentation) — a reviewer without that evidence should report the gap ("abandonment status could not be confirmed from available evidence") rather than guessing.
+- When a replacement plan does exist, verify it names a concrete path (a specific replacement package, a scheduled removal, or an accepted-risk sign-off with an expiry or review date) rather than an open-ended "we know about it."
+
+## Context: general OSS risk (report figure only)
+
+Black Duck's Open Source Security and Risk Analysis (OSSRA) report, published February 25, 2025, found that 86% of commercial codebases evaluated contained open source software vulnerabilities, and 90% of audited codebases had open source components more than four years out of date. This is population-level report context motivating why abandoned and unpatched dependencies deserve deliberate governance — it is never evidence about the specific repository under review, and must not be cited as a finding about this codebase.
+
+## Sources
+
+- `config.policy.abandoned.audit` and `config.policy.abandoned.block` keys, allowed values, and version-dependent defaults: [Composer config documentation](https://getcomposer.org/doc/06-config.md).
+- General OSS-risk context (86% vulnerable codebases, 90% components 4+ years out of date), cited as report-figure motivation only: [Black Duck 2025 OSSRA report announcement](https://news.blackduck.com/2025-02-25-New-Black-Duck-Report-86-of-Commercial-Codebases-Contain-Vulnerable-Open-Source,-Exposing-Organizations-to-Security-Risks).
+
+Last verified: 2026-07-16

package/skills/php/composer-audit-supply-chain-review/references/composer-audit-policy.md

@@ -0,0 +1,35 @@
+# Composer Audit Policy
+
+## Why this matters
+
+`composer audit` is the built-in mechanism for catching known-vulnerable, abandoned, or malware-flagged dependencies before they ship. A repository can have this command available and still ship a vulnerable dependency to production if the command is never invoked in CI, or if it runs but its result is not allowed to fail the build. The review criteria below exist to catch exactly that gap — a policy that exists on paper but is not actually enforced.
+
+## NORMATIVE facts
+
+- `composer audit` checks installed packages against known security advisories, abandoned status, and malware flags.
+- Exit code `0` means no issues were found.
+- Exit code `1` means the command found packages matching the configured dependency policy (advisories and/or abandoned status, depending on `config.policy` settings) or failed due to missing required packages.
+- `config.policy.advisories.audit` controls how `composer audit` treats packages with security advisories. Its allowed values are `ignore` (advisories not reported), `report` (advisories reported but do not cause a non-zero exit code), and `fail` (advisories cause a non-zero exit code). The documented default is `fail`.
+- The `audit` command supports flags including `--no-dev` (skip `require-dev` packages), `--format` (table, plain, json, or summary), `--locked` (audit from the lock file instead of the installed `vendor` directory), and `--ignore-severity` (filter out advisories below a given severity).
+
+## Reviewer evidence criteria
+
+- Locate every CI job that builds, tests, or deploys the project. For each one, search for an invocation of `composer audit` (or `composer audit --locked`, or an equivalent wrapper script).
+- If no such invocation exists in any relevant pipeline, this is a blocking finding: no CI gate exists at all.
+- If an invocation exists, check whether its exit code is allowed to fail the job. Look for patterns that suppress failure: a trailing `|| true`, a shell `set +e` around the call, a CI step marked `continue-on-error: true` (or equivalent), or output redirected to a report file with no subsequent check of the exit code. Any of these means the audit runs but does not gate — treat it as equivalent to no gate, and cite the specific suppression pattern found.
+- Check `composer.json` for an explicit `config.policy.advisories.audit` value. If set to `ignore` or `report`, this weakens or removes the gate regardless of what CI does with the exit code — flag it, and look for an accompanying documented accepted-risk rationale before treating it as intentional.
+- If `config.policy.advisories.audit` is unset, the documented default (`fail`) applies — verify this is consistent with the project's actual Composer version constraint before relying on it (see abandoned-and-advisory-governance.md for the version-sensitivity of related defaults).
+- If `--locked` is not used and the pipeline audits only the installed `vendor` directory, note that a `vendor` directory that is regenerated fresh in CI from `composer.lock` should produce equivalent results, but flag if the pipeline's install step and audit step could diverge (e.g. cached `vendor` directories, conditional installs).
+- Never assert a specific advisory ID or CVE number exists for a package unless it is directly present in retrieved audit output, a lockfile annotation, or another concrete artifact in the repository.
+
+## RECOMMENDATION
+
+- Run `composer audit --locked` in CI immediately after dependency installation, as an explicit step whose failure is not caught or suppressed by later pipeline logic.
+- Keep `config.policy.advisories.audit` at its documented default (`fail`) unless there is a written, time-bound, accepted-risk exception for a specific advisory.
+
+## Sources
+
+- `composer audit` behavior, exit codes, and CLI flags: [Composer CLI documentation](https://getcomposer.org/doc/03-cli.md).
+- `config.policy.advisories.audit` key, allowed values, and default: [Composer config documentation](https://getcomposer.org/doc/06-config.md).
+
+Last verified: 2026-07-16

package/skills/php/composer-audit-supply-chain-review/references/lockfile-integrity.md

@@ -0,0 +1,27 @@
+# Lockfile Integrity
+
+## Why this matters
+
+`composer.lock` is what turns a dependency tree from "whatever the constraints in `composer.json` happen to resolve to today" into a reproducible, reviewable set of exact versions. Without it, or with a drifted or bypassed one, the versions actually running in production are not the versions anyone reviewed — which is precisely the gap OWASP's Vulnerable and Outdated Components category (A06) describes: components are used with unknown or unmanaged versions, making it impossible to know what is actually deployed.
+
+## NORMATIVE facts
+
+- `composer update` resolves dependencies against `composer.json` and writes the exact resolved package versions to `composer.lock`.
+- `composer install`, when a lock file is present, uses the exact versions recorded in `composer.lock` rather than re-resolving from `composer.json` — this is what makes installs consistent across a CI server, production machines, and every developer's environment.
+- Composer displays a warning when running `install` if `composer.lock` has not been updated since changes were made to `composer.json` that could affect dependency resolution — i.e., the lock file and the manifest have drifted apart.
+- For libraries, committing the lock file is documented as not necessary; this exception does not apply to applications, where the lock file is what makes deployment reproducible.
+
+## Reviewer evidence criteria
+
+- Confirm `composer.lock` exists in the repository for any project that is deployed as an application (not merely a library consumed by others). Its absence is a blocking finding on its own: without it, `composer install` re-resolves against `composer.json` constraints every time, so the exact versions running anywhere are not fixed, recorded, or reviewable.
+- If `composer.lock` exists, check for evidence of drift from `composer.json` — a captured CI log showing the "lock file is not up to date" warning, a lock content-hash field that does not match the current `composer.json`, or `composer.json` constraints whose ranges no longer contain the versions actually locked. Report drift as a distinct finding from lock absence; a stale lock file is not the same failure as no lock file, and the remediation differs (run `composer update` for the affected packages and commit the refreshed lock, rather than generating a lock file from scratch).
+- With or without an up-to-date lock file, separately review `composer.json` version constraints for packages at security-sensitive boundaries (authentication, cryptography, session handling, serialization/deserialization, payment processing, or any package with a documented prior advisory). Flag unpinned or unusually wide constraints (`*`, unconstrained `dev-` branch references, or a `~`/`^` floor wide enough to span multiple major or minor lines) — a lock file freezes today's resolution, but an unattended future `composer update` against a wide constraint can still move far without anyone reviewing the jump.
+- When recommending remediation, name the exact Composer command that would resolve the finding (e.g. `composer update <package>` to refresh a stale lock entry, or tightening a constraint in `composer.json`) for the owning engineer to run — this skill never executes it.
+- Treat this as an OWASP A06 (Vulnerable and Outdated Components) instance: the underlying risk is that unmanaged or unknown dependency versions make it impossible to assess exposure, independent of whether any specific advisory currently applies.
+
+## Sources
+
+- `composer.lock` purpose, `composer install` vs `composer update` behavior, the stale-lock warning, and the library exception: [Composer basic usage documentation](https://getcomposer.org/doc/01-basic-usage.md).
+- Vulnerable and Outdated Components as a named risk category: [OWASP Top Ten](https://owasp.org/www-project-top-ten/).
+
+Last verified: 2026-07-16