aiwg 2026.5.3 → 2026.5.5

package/CLAUDE.md

@@ -87,7 +87,7 @@ All 10 providers receive all 4 artifact types (agents, commands, skills, rules).
 | Warp Terminal | `.warp/agents/` + WARP.md | `.warp/commands/` | `.warp/skills/` + `.agents/skills/` | `.warp/rules/` | `aiwg use sdlc --provider warp` |
 | Windsurf | AGENTS.md | `.windsurf/workflows/` | `.windsurf/skills/` + `.agents/skills/` | `.windsurf/rules/` | `aiwg use sdlc --provider windsurf` |
 | OpenClaw | `~/.openclaw/agents/` | `~/.openclaw/commands/` | `~/.openclaw/skills/` + `.agents/skills/` | `~/.openclaw/rules/` | `aiwg use sdlc --provider openclaw` |
-| Hermes | AGENTS.md | — | `~/.hermes/skills/` | — | `aiwg use sdlc --provider hermes` |
+| Hermes | AGENTS.md + .hermes.md | via MCP `command-run` | `~/.hermes/skills/` (kernel) + `~/.hermes/skills/.aiwg/` (standard) | inlined in AGENTS.md + MCP `rule-list`/`rule-show` | `aiwg use sdlc --provider hermes` |
 
 **Special cases:**
 - **Codex**: Commands and skills deploy to home directory (`~/.codex/prompts/`, `~/.codex/skills/`) for user-level availability across all projects. `.codex/commands/` also deploys at project scope for operator visibility, but Codex commands are a static built-in enum in codex-rs and these files are not auto-scanned by the loader; AGENTS.md is the discovery bridge per ADR-1. Reference: `src/smiths/platform-paths.ts:23`.
@@ -95,6 +95,7 @@ All 10 providers receive all 4 artifact types (agents, commands, skills, rules).
 - **Warp**: Agents and commands are also aggregated into `WARP.md` for single-file context loading
 - **Windsurf**: Agents are aggregated into `AGENTS.md` at project root
 - **OpenClaw**: All artifacts deploy to home directory (`~/.openclaw/`). First provider to support behaviors (`~/.openclaw/behaviors/`)
+- **Hermes**: MCP sidecar architecture (`Hermes → MCP → AIWG`). Commands reach AIWG via `mcp_aiwg_command_run` (allow-listed). Standard skills (~385) live under `~/.hermes/skills/.aiwg/` and are recursively discovered; kernel skills (~9) live at the top level and are protected from the Curator (v0.12.0+) via the `.bundled_manifest`. The MCP server has ~12 core tools by default; ~45 additional via `AIWG_MCP_TOOLSETS=<csv>`. See `docs/integrations/hermes-quickstart.md`.
 
 ## Writing Principles
 

package/README.md

@@ -49,6 +49,17 @@ AIWG is a deployment tool and support utility for AI context. At its core, `aiwg
 
 Around that core, AIWG ships utilities for things the base platforms do not handle on their own: persistent artifact memory (`.aiwg/`), background orchestration (`aiwg mc`), autonomous loops (`aiwg ralph`), artifact indexing (`aiwg index`), cost telemetry, health diagnostics, and more. Most are opt-in. The deployment layer works standalone as plain text files the platform reads natively.
 
+### Project scope (recommended) vs user scope (global)
+
+`aiwg use` writes artifacts at one of two scopes. Both are first-class supported (see ADR-NUA-001 in `.aiwg/studies/novice-user-adoption/`):
+
+- **Project scope** — default. Run `aiwg use sdlc` from a project root and the artifacts land in `./.claude/agents/`, `./.claude/skills/`, etc. One project's agent set never bleeds into another's session. **This is the recommended default for most use cases.**
+- **User scope (global install)** — `aiwg use sdlc --scope user` writes to `~/.claude/agents/`, `~/.claude/skills/`, etc. Same artifact set loads into every session, regardless of project. Fits "AIWG in every conversation" workflows and is the canonical mode for OpenClaw and Hermes (whose primary discovery is user-scope).
+
+The trade-off is real: when the same agent set loads into every session, context from one project can bleed into reasoning about another. Research (REF-720, *Lost in Multi-Turn Conversation*, MSR/Salesforce 2025) measured a 39% capability drop when this happens. The non-blocking project-isolation warning surfaces the trade-off at deploy time so the scope choice is informed. Neither scope is wrong; pick the one that fits the workflow.
+
+See `docs/cli-reference.md` (under `aiwg use` → "Scope models") for the per-provider details and the global-install rough-edge inventory.
+
 ## Simple Building Blocks
 
 AIWG ships five primitive artifact types. All are plain text:

package/agentic/code/addons/aiwg-utils/manifest.json

@@ -36,7 +36,8 @@
   "consolidation": {
     "strategy": "index-with-links",
     "rulesIndex": "rules/RULES-INDEX.md",
-    "deployIndexOnly": true
+    "deployIndexOnly": false,
+    "_note": "deployIndexOnly was true (#1343); changed to false 2026-05-14 so individual rule files (including skill-discovery.md) deploy to every provider's rules directory alongside the index. RULES-INDEX.md remains the canonical entry point; its links now resolve to local files on every provider, not just Claude/Cursor."
   },
   "commands": [],
   "agents": [

package/agentic/code/frameworks/sdlc-complete/templates/aiwg-sections/02b-discover-first.md

@@ -0,0 +1,42 @@
+## Discover-First Protocol (CRITICAL)
+
+Before declining a user request as "outside AIWG's scope" or improvising a workflow from training data, you MUST consult AIWG's artifact index.
+
+AIWG ships ~400 skills, ~190 agents, ~70 commands, and ~60 rules across its installed frameworks. Most are NOT loaded into your context — they live at the install location and reach you via two CLI commands:
+
+```bash
+aiwg discover "<paraphrased user need>"
+aiwg show <type> <name>          # e.g. aiwg show skill flow-deploy-to-production
+```
+
+### When to run discover
+
+You MUST run `aiwg discover` when any of the following is true:
+
+- You are about to tell the user "AIWG doesn't have a way to do that"
+- You are about to write a custom workflow / script / procedure from scratch
+- The user's request mentions AIWG, a framework name (sdlc, research, forensics, ops, security-engineering, marketing, media-curator, knowledge-base), or capability keywords (skill, agent, command, rule, workflow, flow, template, addon)
+- You are uncertain whether a curated AIWG artifact already addresses the request
+
+You MAY skip discover only when:
+
+- The user named a specific skill/command (e.g. `/flow-deploy-to-production`)
+- The capability is clearly outside AIWG's scope (weather, translation, unrelated programming)
+- You already ran `aiwg discover` for the same need this session
+- A loaded quickref directly names the skill the user needs
+
+### Discover-first, NOT filesystem-first
+
+When the user's request mentions an AIWG keyword, `aiwg discover` is your FIRST tool call — not `Grep` / `Glob` / `Read` against provider directories like `.claude/`, `.codex/`, `.factory/`, `.warp/`, `.windsurf/`, `~/.openclaw/`, or `~/.hermes/`.
+
+Filesystem search against those paths is FORBIDDEN as a first move for AIWG-internal lookups. The reason: the discover index covers 10x the surface area that any single provider directory holds, and gives you ranked results with capability summaries. Grep gives you a literal-string hit and stops.
+
+### After discover returns a match
+
+Use `aiwg show <type> <name>` to fetch the body — never `Read` on the returned path, never `find` / `ls` against the corpus directory. The CLI handles the read; you handle the application.
+
+### Why this matters
+
+Most AIWG skills are not in your context by design — that's how the kernel-skill model keeps your context lean while making the full corpus reachable. Enumerating from memory will miss obvious matches. The cost of running `aiwg discover` is one CLI invocation; the cost of skipping it is recommending a workflow AIWG already has, or declining a request AIWG can already serve.
+
+The full discover-first rule (with detection heuristics, recovery procedure, and integration with other rules) is deployed at the framework's rules path as `skill-discovery.md`. Read it once at session start if you have not already.

package/agentic/code/frameworks/sdlc-complete/templates/aiwg-sections/manifest.json

@@ -15,6 +15,13 @@
       "required": true,
       "description": "Orchestration responsibilities, multi-agent workflow pattern, NL translations, available commands"
     },
+    {
+      "id": "discover-first",
+      "file": "02b-discover-first.md",
+      "title": "Discover-First Protocol",
+      "required": true,
+      "description": "Mandates `aiwg discover` + `aiwg show` before declining requests or improvising workflows. Closes hookup-matrix Finding #2 (#1344) — the discover-first protocol now reaches every provider that loads AIWG.md (Codex, Windsurf, OpenCode, Hermes, plus Warp via twin emission)."
+    },
     {
       "id": "aiwg-rules",
       "file": "03-aiwg-rules.md",

package/agentic/code/frameworks/sdlc-complete/templates/copilot/copilot-instructions.md.aiwg-template

@@ -8,6 +8,17 @@ This file provides project-specific instructions for GitHub Copilot.
 
 This project uses the AIWG SDLC Framework for software development lifecycle management.
 
+### Discover-First Protocol (CRITICAL)
+
+Before declining a user request as "outside AIWG's scope" or improvising a workflow from training data, you MUST consult AIWG's artifact index. AIWG ships ~400 skills, ~190 agents, ~70 commands, and ~60 rules — most are NOT loaded into your context. Reach them via:
+
+```bash
+aiwg discover "<paraphrased user need>"
+aiwg show <type> <name>          # e.g. aiwg show skill flow-deploy-to-production
+```
+
+Run `aiwg discover` whenever the user mentions AIWG, a framework name (sdlc, research, forensics, ops, marketing, security-engineering, media-curator, knowledge-base), or capability keywords (skill, agent, command, rule, workflow). Filesystem search against `.github/agents/`, `.github/skills/`, or `.github/instructions/` is FORBIDDEN as a first move for AIWG-internal lookups — `aiwg discover` covers 10x the surface area with ranked results. The full protocol is documented at `.github/copilot-rules/skill-discovery.md` (or `.github/instructions/skill-discovery.instructions.md`); read it once at session start.
+
 ### Available Custom Agents
 
 AIWG agents are deployed to `.github/agents/` and can be invoked via `@agent-name`:

package/agentic/code/frameworks/security-engineering/manifest.json

@@ -43,8 +43,8 @@
     "last_updated": "2026-05-13",
     "total_agents": 0,
     "total_commands": 0,
-    "total_skills": 11,
-    "total_rules": 0,
+    "total_skills": 15,
+    "total_rules": 6,
     "status": "active"
   },
   "memory": {

package/agentic/code/frameworks/security-engineering/rules/RULES-INDEX.md

@@ -1,10 +1,10 @@
 # Security Engineering Rules Index
 
-Applied-security enforcement rules for cryptographic primitive choices, chain-of-trust integrity, secret handling, and related design-time concerns. Deployed when the `security-engineering` framework is installed.
+Applied-security enforcement rules for cryptographic primitive choices, chain-of-trust integrity, secret handling, supply-chain pinning, dependency-source policy, and related design-time concerns. Deployed when the `security-engineering` framework is installed.
 
 ---
 
-## Tier 1 Rules (4 rules — applied cryptography)
+## Tier 1 Rules (6 rules — applied cryptography + supply chain)
 
 ### HIGH
 
@@ -32,6 +32,18 @@ Applied-security enforcement rules for cryptographic primitive choices, chain-of
 **Maps to review finding**: H6
 **Full rule**: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/crypto-flag-verification.md
 
+#### ci-action-pinning
+**Summary**: Every CI workflow `uses:` reference MUST be a 40-character commit SHA (not a tag); every `container:`/`image:` reference MUST be `<name>:<tag>@sha256:<digest>`. Tools downloaded via `curl | sh` must record an observed-SHA log and support strict-mode SHA enforcement. Floating tags expose CI to silent supply-chain attacks (Shai-Hulud-class worm propagation). Maintain a pin manifest (`ci/digests.txt` or equivalent) as source of truth for diffs.
+**When to apply**: Any workflow file under `.github/workflows/`, `.gitea/workflows/`, or equivalent; any tool-install step in CI
+**Maps to issue**: #1293 (B3 / Mini Shai-Hulud)
+**Full rule**: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/ci-action-pinning.md
+
+#### dependency-source-policy
+**Summary**: Non-registry dependency sources (`git+`, `github:`, raw tarball URLs, `file:`, `link:`) are PROHIBITED — they bypass registry signature verification and can execute arbitrary code at install time via `prepare` scripts (Mini Shai-Hulud's primary propagation vector). Policy applies to `package.json` AND transitive lockfile entries. Exceptions require an allowlist entry with owner, reason, review_date, and explicit risk acceptance. pnpm workspaces must set `blockExoticSubdeps: true` for workspace-scope enforcement.
+**When to apply**: Any change to `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `bun.lockb`; CI lint should run on every push
+**Maps to issue**: #1297 (Mini Shai-Hulud follow-up)
+**Full rule**: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/dependency-source-policy.md
+
 ---
 
 ## Quick Reference by Context
@@ -43,7 +55,10 @@ Applied-security enforcement rules for cryptographic primitive choices, chain-of
 | **Multi-key systems** | no-key-reuse-across-purposes, no-adhoc-kdf |
 | **Password handling** | no-adhoc-kdf (Argon2id/PBKDF2 ≥600k) |
 | **CLI crypto invocations** | crypto-flag-verification, no-unauthenticated-encryption |
-| **Reviewing cryptographic decisions** | All four rules in sequence |
+| **CI workflow review** | ci-action-pinning |
+| **Container image references** | ci-action-pinning |
+| **package.json / lockfile review** | dependency-source-policy |
+| **Reviewing cryptographic decisions** | All four crypto rules in sequence |
 
 ---
 
@@ -53,5 +68,5 @@ Future Tier 2 rules will cover authentication-factor architecture, degraded-mode
 
 ---
 
-*Generated from security-engineering framework — 4 rules in Tier 1*
+*Generated from security-engineering framework — 6 rules in Tier 1*
 *Full rule files: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/*

package/agentic/code/frameworks/security-engineering/rules/ci-action-pinning.md

@@ -0,0 +1,145 @@
+# CI Action and Container Pinning
+
+**Enforcement Level**: HIGH
+**Scope**: All CI workflow files (`.github/workflows/`, `.gitea/workflows/`, equivalent) and any `container:` references therein
+**Issue**: #1293
+
+## Principle
+
+CI workflows execute third-party code with broad permissions on every push. A workflow that references `actions/checkout@v4` or `node:24` resolves the reference at run time — the bytes that execute today are not guaranteed to be the bytes that execute tomorrow. Anyone who can move the `v4` tag (a GitHub Action maintainer compromise, a registry account takeover, a published-but-malicious update) silently runs new code in your CI. Pinning by immutable digest closes this attack surface.
+
+This is the same standard AIWG applies to its own CI per [`dev-idempotent-builds.md`](.claude/rules/dev-idempotent-builds.md) rule 2 ("no `:latest` in production"). B3 extends the standard to user projects as a deployable rule.
+
+## Mandatory Rules
+
+### Rule 1: GitHub Actions references pinned by 40-char commit SHA
+
+Every `uses:` reference in a workflow file MUST point at a 40-character commit SHA, not a tag or branch.
+
+**FORBIDDEN**:
+```yaml
+- uses: actions/checkout@v4              # tag — can move
+- uses: actions/checkout@main            # branch — definitely moves
+- uses: actions/checkout@v4.3.1          # version tag — usually immutable but a compromised account can re-point it
+```
+
+**REQUIRED**:
+```yaml
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+```
+
+The trailing comment is non-optional. It preserves human-readable diffability without compromising the immutability of the SHA pin.
+
+### Rule 2: Container images pinned by sha256 digest
+
+Every `container:` or `image:` reference in a workflow MUST be `<name>:<tag>@sha256:<digest>`.
+
+**FORBIDDEN**:
+```yaml
+container: node:24
+container: node:latest
+container: node:24-bookworm
+container: ghcr.io/owner/image:v2.1.0
+```
+
+**REQUIRED**:
+```yaml
+container: node:24@sha256:050bf2bbe33c1d6754e060bec89378a79ed831f04a7bb1a53fe45e997df7b3bb  # 24.15.0
+```
+
+The `<name>:<tag>` prefix is retained for human readability; the digest is the trust anchor. Trailing comment captures the resolved version for diff context.
+
+### Rule 3: Pin manifest at `ci/digests.txt` (or equivalent)
+
+Every project that enforces this rule MUST maintain a pin manifest listing each pinned reference, its resolved version, the date pinned, and the rationale. The manifest is the source of truth for diffs — a SHA change without a corresponding manifest entry is a red flag.
+
+Reference manifest format: see AIWG's own [`ci/digests.txt`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/ci/digests.txt).
+
+Minimum row format:
+```
+<kind>  <name>            <pin>                                          <resolved-version>  <date-pinned>  <update-rationale>
+container  node:24       sha256:050bf2bbe33c1d6754e060bec89378a79ed831f04a7bb1a53fe45e997df7b3bb  24.15.0  2026-05-12  initial pin
+action  actions/checkout  93cb6efe18208431cddfb8368fd83d5badbf9bfd       v5.0.1              2026-05-12  initial pin
+```
+
+### Rule 4: Pin bumps go through review
+
+Every pin update is a reviewable change. The commit should:
+- Reference the issue or advisory motivating the bump (CVE, needed feature, scheduled rotation)
+- Update the manifest row in the same commit as the workflow file edit
+- Include `chore(ci): bump <name> pin to <version> (refs #<issue>)` style commit message
+
+Workflow diffs that change a digest without a corresponding manifest update fail review.
+
+### Rule 5: Standalone tools pinned by version + checksum
+
+Tools downloaded by `curl | sh` or equivalent in CI (e.g., `syft install.sh`, ad-hoc binary releases) MUST pin a specific version AND record the installer's content hash. The version pin gives reproducibility; the content hash detects upstream tampering.
+
+**Acceptable pattern** (strict-mode opt-in, with observed-SHA logging):
+```yaml
+- name: Install syft
+  run: |
+    VERSION=v1.18.0
+    EXPECTED_INSTALL_SHA=""  # populate after first run; logs `observed` SHA
+    SCRIPT=$(curl -fsSL "https://raw.githubusercontent.com/anchore/syft/${VERSION}/install.sh")
+    OBSERVED_SHA=$(printf '%s' "$SCRIPT" | sha256sum | awk '{print $1}')
+    echo "observed install-script SHA: ${OBSERVED_SHA}"
+    if [ -n "$EXPECTED_INSTALL_SHA" ] && [ "$OBSERVED_SHA" != "$EXPECTED_INSTALL_SHA" ]; then
+      echo "✗ install-script SHA drift — refusing to execute"
+      exit 1
+    fi
+    printf '%s' "$SCRIPT" | sh -s -- -b /usr/local/bin "$VERSION"
+```
+
+## Detection Patterns
+
+CI lint should flag the following:
+
+```bash
+# Floating action tags
+grep -rE '^\s*-\s*uses:\s*[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+@(v?[0-9]+(\.[0-9]+)*|main|master|latest)\s*(#.*)?$' \
+  .github/workflows/ .gitea/workflows/ 2>/dev/null
+
+# Unpinned container images
+grep -rE '^\s*(container|image):\s*[a-zA-Z0-9._/-]+:[a-zA-Z0-9._-]+\s*(#.*)?$' \
+  .github/workflows/ .gitea/workflows/ 2>/dev/null \
+  | grep -v 'sha256:'
+
+# Bare :latest anywhere
+grep -rnE ':latest\b' .github/workflows/ .gitea/workflows/ 2>/dev/null
+
+# Curl-pipe-shell installers without a content hash check
+grep -rnE 'curl[^|]+\|\s*(bash|sh)' .github/workflows/ .gitea/workflows/ 2>/dev/null
+```
+
+Wire these into a `npm run lint:ci-pins` script (or equivalent) and call it from the CI workflow itself so the rule is self-enforcing.
+
+## Acceptable Exceptions
+
+The following are NOT subject to this rule:
+
+1. **Dockerfile `FROM` instructions in build stages** that are NOT consumed by CI directly — those are governed by the project's image-build pipeline (which should follow the same standard, but the rule lives in the Dockerfile review, not the workflow review).
+2. **Ephemeral self-hosted runners** that pull pre-baked AMIs/images with their own attestation chain — the chain-of-trust is at the AMI level, not the workflow level.
+3. **Reusable workflows from the same repository** (`uses: ./.github/workflows/foo.yml`) — these are pinned to the repository state at the calling commit.
+4. **Build-arg substitutions for the same digest** — `FROM ${BASE_IMAGE}` where `BASE_IMAGE` is built from a digest-pinned reference one level up.
+
+Document any other exception in a code comment adjacent to the unpinned reference, with reasoning and an issue link tracking eventual migration to a pin.
+
+## Rationale
+
+The mutable-tag attack surface is one of the largest unaddressed components of npm-ecosystem supply-chain risk as of 2026. The recent Shai-Hulud worm campaign demonstrated that compromised maintainer accounts can push malicious updates that propagate via floating version tags within hours. Workflows pinned by SHA stop that propagation at the boundary of every individual project that pins.
+
+Pin-bump cost is low (one curl/git ls-remote command); incident cost from an unpinned dependency executing in CI with secret access is high. The asymmetry justifies the rule.
+
+## References
+
+- [`dev-idempotent-builds.md`](.claude/rules/dev-idempotent-builds.md) — base rule on reproducible builds
+- AIWG's own pin manifest: `ci/digests.txt`
+- Defenses brief C7 (action pinning) and C8 (container pinning)
+- Shai-Hulud worm post-mortem references
+- GitHub Actions documentation: pinning third-party actions to a full-length commit SHA
+
+---
+
+**Rule Status**: ACTIVE
+**Last Updated**: 2026-05-13

package/agentic/code/frameworks/security-engineering/rules/dependency-source-policy.md

@@ -0,0 +1,177 @@
+# Dependency Source Policy
+
+**Enforcement Level**: HIGH
+**Scope**: `package.json` and lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`) — direct AND transitive entries
+**Issue**: #1297
+
+## Principle
+
+Non-registry dependency sources (`git+`, `github:`, raw tarball URLs, `file:`, `link:`) bypass registry signature verification AND can execute arbitrary code during install via lifecycle scripts (especially `prepare`). The May 2026 Mini Shai-Hulud campaign's primary propagation vector was an `optionalDependencies` entry sourced from `git+https://...attacker-repo` whose `prepare` script ran during every `npm install` of any project that pulled in the affected package.
+
+Registry-hosted tarballs (`registry.npmjs.org/.../foo.tgz`, `registry.yarnpkg.com/...`, `npm.pkg.github.com/...`) are fine — they're the normal `resolved` URL format `npm install` emits for every registry-published dep. The policy only flags non-registry sources.
+
+Companion to [`ci-action-pinning`](ci-action-pinning.md) (CI execution-environment trust) and the per-package-manager release-age-gate skills (which gate freshly-published registry versions). Together they cover the three primary supply-chain attack vectors: CI environment poisoning, registry-version poisoning, and direct dep-source injection.
+
+## Mandatory Rules
+
+### Rule 1: Six dep-source patterns are forbidden by default
+
+Every dep in `package.json` AND every entry in the lockfile (including transitive) MUST be a registry-published version reference. The following patterns are blocked:
+
+| Pattern | Example | Reason |
+|---|---|---|
+| `git+*` scheme | `"foo": "git+https://github.com/owner/foo.git"` | npm clones the repo and runs its `prepare` script — arbitrary code execution at install time |
+| `git://` scheme | `"foo": "git://github.com/owner/foo.git"` | Same as above |
+| `github:` shorthand | `"foo": "github:owner/foo"` | Same as above; npm expands to git+ |
+| Non-registry tarball | `"foo": "https://example.com/foo-1.0.0.tgz"` | Tarball can contain any payload and lifecycle scripts; bypasses registry signature verification |
+| `file:` path | `"foo": "file:./vendor/foo"` | Local-path deps bypass dep-resolution review and lockfile signature checks |
+| `link:` symlink | `"foo": "link:./packages/foo"` | Follows the symlink target wherever it points; same gaps as `file:` |
+
+Registry-hosted patterns that are ALWAYS acceptable:
+
+- `"foo": "^1.2.3"` — registry semver range
+- `"foo": "1.2.3"` — exact registry version
+- `"foo": "npm:@scope/foo@^1.2.3"` — aliased registry dep
+- Lockfile `"resolved": "https://registry.npmjs.org/..."` — registry-served tarball
+
+### Rule 2: Exceptions require an allowlist entry
+
+If a legitimate non-registry source exists (e.g., temporary fork pending upstream merge, monorepo-internal `file:` link with a known security boundary), it MUST be allowlisted with:
+
+- **Owner** — who took the risk-acceptance decision
+- **Reason** — why a registry version isn't viable today
+- **Expiry / review date** — when this exception must be re-evaluated (max 1 year)
+- **Risk acceptance** — explicit statement that the operator accepts the dep-source bypass
+
+Allowlist file format (committed at `.aiwg/security/dep-source-allowlist.yaml` or equivalent):
+
+```yaml
+allowlist:
+  - dep: "foo"
+    source: "git+https://github.com/owner/foo.git#sha-or-tag"
+    owner: "alice@example.org"
+    reason: "Upstream PR #123 not yet merged; we need fix from main for issue X"
+    review_date: "2026-08-01"
+    risk_acceptance: "Source pinned to commit SHA; reviewed prepare script line-by-line; no shell exec in install path"
+  - dep: "@internal/shared"
+    source: "file:./packages/shared"
+    owner: "bob@example.org"
+    reason: "Monorepo-internal package; not published to registry"
+    review_date: "2027-01-01"
+    risk_acceptance: "Source within same security boundary as host package; no external code path"
+```
+
+Allowlist entries beyond their `review_date` are treated as policy violations.
+
+### Rule 3: Lockfile entries are policy targets
+
+Direct deps in `package.json` are easy to spot. Transitive entries in the lockfile are the actual attack surface — Mini Shai-Hulud propagated via transitive `optionalDependencies` with exotic sources. The CI lint MUST scan the lockfile for the same patterns, including:
+
+- `"resolved": "git+..."` in `package-lock.json`
+- `tarball: ...` URLs in `pnpm-lock.yaml` that don't match a registry origin
+- `resolution: ` blocks in `yarn.lock`
+- Binary lockfile (`bun.lockb`) — extract via `bun pm ls --all` and pattern-match the output
+
+### Rule 4: pnpm workspaces enable `blockExoticSubdeps`
+
+When pnpm is the package manager, the workspace MUST set `blockExoticSubdeps: true` (in `pnpm-workspace.yaml`) or the per-repo equivalent in `.npmrc`:
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'packages/*'
+blockExoticSubdeps: true
+```
+
+This is the pnpm advantage over npm: workspace-scope enforcement that npm has no equivalent for. The `pnpm-release-age-gate` skill documents the wiring.
+
+### Rule 5: Failure messages point to remediation
+
+When CI rejects a violation, the failure message MUST:
+
+1. State which dep and which source pattern matched
+2. Reference the operator's choices: switch to a registry version, request an allowlist entry, or accept install-time compromise risk
+3. Link to this rule (or the project's adaptation of it) so the receiving developer can read the policy
+
+Reference failure-message format (from AIWG's own `tools/lint/dep-source.mjs`):
+
+```
+✗ Dependency source policy violation
+
+  foo (in package.json)
+    source: git+https://github.com/owner/foo.git
+    pattern: git+ scheme
+
+  This dependency source bypasses registry signature verification and
+  executes arbitrary code at install time via the prepare script.
+
+  Options:
+    1. Switch to a registry-published version: npm install foo@<version>
+    2. Add an allowlist entry: see .aiwg/security/dep-source-allowlist.yaml
+    3. Read the policy: docs/contributing/dependency-sources.md
+```
+
+## Detection Patterns
+
+```bash
+# package.json — direct deps with exotic sources
+node -p "
+  const p = require('./package.json');
+  const all = {...p.dependencies, ...p.devDependencies, ...p.optionalDependencies, ...p.peerDependencies};
+  for (const [name, source] of Object.entries(all || {})) {
+    if (/^(git\+|git:|github:|file:|link:)/.test(source) ||
+        (/^https?:\/\//.test(source) && /\.tgz/.test(source))) {
+      console.log(name, '=', source);
+    }
+  }
+"
+
+# package-lock.json — transitive entries with exotic resolved URLs
+node -p "
+  const lock = require('./package-lock.json');
+  function walk(pkgs, prefix = '') {
+    for (const [path, entry] of Object.entries(pkgs || {})) {
+      if (entry.resolved && /^(git\+|git:)/.test(entry.resolved)) {
+        console.log(prefix + path, '=', entry.resolved);
+      }
+    }
+  }
+  walk(lock.packages);
+"
+
+# pnpm-lock.yaml — exotic resolution blocks
+grep -E 'resolution:\s*\{(git|tarball:.*[^.]https?://[^/]+/[^.]*\.tgz)' pnpm-lock.yaml 2>/dev/null
+
+# yarn.lock — exotic resolved entries
+grep -E '"?resolved"?\s*"?:?\s*"?(git\+|git:)' yarn.lock 2>/dev/null
+```
+
+Reference implementation: AIWG's own [`tools/lint/dep-source.mjs`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/tools/lint/dep-source.mjs) — runs `npm run lint:dep-sources` and exits non-zero on any violation.
+
+## Acceptable Exceptions
+
+Three exception categories beyond explicit allowlist entries:
+
+1. **Monorepo workspace links** — `file:` or `link:` deps between packages in the same `pnpm-workspace.yaml` / `lerna.json` / `nx.json` / `package.json workspaces` configuration. These are within the same security boundary; flag as INFO only.
+2. **Lockfile resolved-URL prefixes that look exotic but ARE registry URLs** — e.g., `https://registry.npmjs.org/...` matches `^https://` but is a registry origin. The detection logic above already excludes these correctly by checking the host.
+3. **Dev-only deps for build tooling that consume only `package.json`-declared scripts** — debatable; recommend treating as standard policy violations and using allowlist entries for the temporary cases.
+
+## Rationale
+
+Mini Shai-Hulud demonstrated that a single transitive `optionalDependencies` entry from a compromised maintainer can propagate a `prepare`-script payload to every downstream `npm install`. The registry's "this version was published by an authenticated maintainer" guarantee is the foundation of `npm audit signatures`; non-registry sources bypass that guarantee entirely.
+
+Cost of compliance is low (most deps are already registry-published). Cost of a single exotic-source incident is high (full secret-rotation cycle, downstream user trust loss, potential CVE assignment). The asymmetry justifies the rule.
+
+## References
+
+- [`ci-action-pinning`](ci-action-pinning.md) — CI execution-environment trust (companion rule)
+- AIWG's lint implementation: [`tools/lint/dep-source.mjs`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/tools/lint/dep-source.mjs)
+- AIWG's contributor doc: [`docs/contributing/dependency-sources.md`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/docs/contributing/dependency-sources.md)
+- ADR: `.aiwg/architecture/adr-dep-source-policy.md` (in AIWG's own repo)
+- pnpm `blockExoticSubdeps`: <https://pnpm.io/settings#blockexoticsubdeps>
+- Mini Shai-Hulud post-mortem references
+
+---
+
+**Rule Status**: ACTIVE
+**Last Updated**: 2026-05-13