@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/cf-token-scope/scripts/cf-token-scope.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# cf-token-scope — verify a Cloudflare API token's retained scope after a widen,
+# and (with --target-entrypoint) confirm a newly-added scope is live.
+#
+# Deterministic, read-only probe. The widen itself is driven by Playwright MCP
+# per the skill (SKILL.md) — this script never touches the browser and never
+# mutates anything (no Doppler write, no infra apply).
+#
+# It runs the ADR-130 retained-scope probe set against CF_API_TOKEN_RULESETS and
+# is fail-closed in three layers (per learning
+# 2026-07-23-live-api-fail-closed-guard-counts-degraded-200-as-empty-and-control-probe-must-cover-every-scheme):
+#   1. status      — 403 / 000 / 5xx / empty / no-newline / non-numeric = FAIL.
+#   2. body-shape  — a 200 passes ONLY when the JSON body has success==true AND
+#                    .result is an array. A degraded 200 (e.g.
+#                    {"success":false,...} OR {"success":true,"result":null}) is a
+#                    FAIL. Never key on `.result | length` — jq reads null as 0.
+#   3. per-scheme control — the probes span two schemes: four zone phases and one
+#                    account list. The account list is itself the account-scheme
+#                    control (must be an authorized 200; an account 404 = FAIL). A
+#                    zone 404 (ADR-130's "phase exists, empty") is trusted ONLY for
+#                    http_config_settings — the one phase whose 403-on-missing was
+#                    empirically verified — and only under an authorized zone
+#                    control (http_request_dynamic_redirect). Every other phase's
+#                    404 fails closed (a dropped scope that 404s must not pass).
+#
+# The probe set is a CANARY for the whole-list REPLACE failure mode (a dashboard
+# "save" that replaces rather than appends drops every scope at once → every probe
+# catches it). It is NOT exhaustive per-permission coverage: Zone WAF
+# (firewall_custom) is now probed, but Transform Rules (response_headers_transform)
+# and account Filter Lists are not, so a surgical single-permission drop of those
+# can pass. The probe issues GET, so it attests READ reachability, not :Edit
+# retention. See SKILL.md § Sharp Edges.
+
+set -euo pipefail
+
+# (#7797) Refuse to run under shell tracing. UNCONDITIONAL — deliberately NOT
+# gated on a non-emptiness test of the credential variable, because
+# CF_API_TOKEN_RULESETS is acquired by `doppler secrets get` BELOW this point, so a
+# conditional arm would test an empty variable at guard time, open, and then trace
+# the acquisition itself.
+#
+# STREAM CONTRACT: this script's stdout is a DATA channel — SKILL.md's probe-set
+# contract documents `PASS: …` verdict lines a consumer reads. So the refusal is
+# emitted as a `FAIL:` verdict in this module's own vocabulary: it cannot be
+# mistaken for a PASS row, which a bare `[FATAL] …` line could be if the consumer
+# only greps for verdicts. Stdout, not stderr, because agent runtimes surface
+# stdout and swallow stderr (constitution.md > Code Style).
+case "$-" in
+  *x*)
+    printf 'FAIL: refusing to run under xtrace — this script handles a live credential and -x would print it (see #7797). No probe was issued.\n'
+    exit 78
+    ;;
+esac
+
+# (#7873) `--disable` closes ~/.curlrc and `--noproxy '*'` closes the proxy vars,
+# but neither touches the env that subverts TLS ITSELF. SSLKEYLOGFILE writes the
+# session keys and the CA vars substitute the trust store, so a CURL_CA_BUNDLE
+# MITM of the Cloudflare token works with every other guard fully intact.
+unset SSLKEYLOGFILE CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR CURL_HOME \
+      HOSTALIASES LOCALDOMAIN RES_OPTIONS
+
+DOPPLER_PROJECT="soleur"
+DOPPLER_CONFIG="prd_terraform"
+TOKEN_SECRET="CF_API_TOKEN_RULESETS"
+ZONE_SECRET="CF_ZONE_ID"
+ACCT_SECRET="CF_ACCOUNT_ID"
+API="https://api.cloudflare.com/client/v4"
+
+# The ADR-130 retained-scope zone phases. http_request_dynamic_redirect is the
+# known-granted zone control (ADR-130 § Consequences: the 200 control probe).
+# http_request_firewall_custom (Zone WAF:Edit) is added to the retained set
+# because it is a hijack-class scope on the same token (ADR-130 axis 1).
+ZONE_CONTROL="http_request_dynamic_redirect"
+ZONE_PHASES=(http_config_settings http_request_dynamic_redirect http_request_cache_settings http_request_firewall_custom)
+
+# 403-vs-404-on-missing-scope semantics are EMPIRICALLY VERIFIED (ADR-130 probe
+# #6746) for ONLY http_config_settings: a missing scope there returns 403, never
+# 404, so a 404 is unambiguously "phase exists, empty" and passes. For every other
+# phase that fact is UNVERIFIED, so a 404 fails closed — a dropped scope that
+# returned 404 instead of 403 must never read as green (user-impact P1, #6892).
+trust404_for() { [[ "$1" == "http_config_settings" ]] && echo 1 || echo 0; }
+
+usage() {
+  cat <<'EOF'
+Usage:
+  cf-token-scope.sh [--target-entrypoint <phase>] [--dry-run]
+
+Runs the ADR-130 retained-scope probe set against CF_API_TOKEN_RULESETS
+(read-only). The widen itself is driven via Playwright MCP — see SKILL.md.
+
+Flags:
+  --target-entrypoint <phase>  Also probe <phase> and assert the target scope is
+                               present (use after a widen; confirm the
+                               403->present transition against your baseline).
+  --dry-run                    Print the probe commands (token unexpanded) and
+                               run nothing.
+  -h, --help                   Show this help.
+
+Exit codes:
+  0  every retained scope authorized (and the target, if given)
+  2  usage error, missing prerequisite binary, or absent Doppler secret
+  3  probe failed — a scope was dropped, degraded, or denied
+EOF
+}
+
+TARGET=""
+DRY_RUN=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target-entrypoint)
+      if [[ -z "${2:-}" ]]; then
+        echo "cf-token-scope: --target-entrypoint requires a phase name" >&2
+        exit 2
+      fi
+      TARGET="$2"; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "cf-token-scope: unknown argument: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  printf '%s\n' "# dry-run — would read the token read-only and probe (nothing executed):"
+  printf '%s\n' "TOK=\$(doppler secrets get $TOKEN_SECRET -p $DOPPLER_PROJECT -c $DOPPLER_CONFIG --plain)"
+  printf '%s\n' "ZONE=\$(doppler secrets get $ZONE_SECRET -p $DOPPLER_PROJECT -c $DOPPLER_CONFIG --plain)"
+  printf '%s\n' "ACCT=\$(doppler secrets get $ACCT_SECRET -p $DOPPLER_PROJECT -c $DOPPLER_CONFIG --plain)"
+  # The token is passed from a private fd (never argv) — mirror that here so a
+  # copy-pasted recipe does not leak the token to ps / /proc (security #6892).
+  # The recipes also carry `--disable` literally first (it aborts ~/.curlrc
+  # parsing, and later is too late) and `--noproxy '*'`, so a copy-pasted probe
+  # teaches the confined form rather than the one this change removes (#7873).
+  for p in "${ZONE_PHASES[@]}" ${TARGET:+"$TARGET"}; do
+    printf '%s\n' "curl --disable --noproxy '*' -sS --max-time 15 -H @<(printf 'Authorization: Bearer %s' \"\$TOK\") $API/zones/\$ZONE/rulesets/phases/$p/entrypoint"
+  done
+  printf '%s\n' "curl --disable --noproxy '*' -sS --max-time 15 -H @<(printf 'Authorization: Bearer %s' \"\$TOK\") $API/accounts/\$ACCT/rulesets"
+  exit 0
+fi
+
+# Prerequisites.
+for bin in curl doppler jq; do
+  command -v "$bin" >/dev/null 2>&1 || {
+    echo "cf-token-scope: missing required binary: $bin" >&2
+    exit 2
+  }
+done
+
+get_secret() {
+  local name="$1" val
+  val="$(doppler secrets get "$name" -p "$DOPPLER_PROJECT" -c "$DOPPLER_CONFIG" --plain 2>/dev/null || true)"
+  if [[ -z "$val" ]]; then
+    echo "cf-token-scope: $name is empty or absent in Doppler $DOPPLER_PROJECT/$DOPPLER_CONFIG" >&2
+    exit 2
+  fi
+  printf '%s' "$val"
+}
+
+TOK="$(get_secret "$TOKEN_SECRET")"
+ZONE="$(get_secret "$ZONE_SECRET")"
+ACCT="$(get_secret "$ACCT_SECRET")"
+# shellcheck disable=SC2317  # invoked indirectly via the EXIT trap
+cleanup() { unset TOK ZONE ACCT; }
+trap cleanup EXIT
+
+# Body-shape layer: a 200 is authorized ONLY with success==true AND .result of the
+# type the endpoint's scheme returns — a zone .../entrypoint returns a single
+# ruleset OBJECT; the account /rulesets list returns an ARRAY. A degraded 200
+# ({"success":false,...} or {"success":true,"result":null}) fails either way (null
+# is neither object nor array). $2 is the expected type: object (zone) | array (account).
+authorized_body() {
+  printf '%s' "$1" | jq -e --arg t "$2" '.success == true and (.result | type == $t)' >/dev/null 2>&1
+}
+
+ZONE_CONTROL_OK=0
+
+# check <url> <scheme:zone|account> <trust404:0|1> — probes one URL, sets VERDICT,
+# returns 0 (pass: authorized / empty-404-under-control-when-trusted) or 1 (fail).
+# The Authorization header is passed from a private fd so the token never lands
+# in the process argv (readable via ps / /proc/<pid>/cmdline).
+check() {
+  local url="$1" scheme="$2" trust404="${3:-0}" resp code body want_type
+  want_type="object"; [[ "$scheme" == "account" ]] && want_type="array"
+  resp="$(curl --disable --noproxy '*' -sS --max-time 15 -w '\n%{http_code}' \
+    -H @<(printf 'Authorization: Bearer %s' "$TOK") "$url" 2>/dev/null || true)"
+  if [[ "$resp" != *$'\n'* ]]; then VERDICT="empty (no response)"; return 1; fi
+  code="${resp##*$'\n'}"
+  body="${resp%$'\n'*}"
+  if [[ ! "$code" =~ ^[0-9]+$ ]]; then VERDICT="empty (non-numeric status)"; return 1; fi
+  if [[ "$code" == "200" ]]; then
+    if authorized_body "$body" "$want_type"; then VERDICT="authorized (200)"; return 0; fi
+    VERDICT="degraded (200 body not success/$want_type)"; return 1
+  fi
+  # A 404 is trusted as "phase exists, empty" ONLY for an entrypoint whose
+  # 403-on-missing semantics are verified (trust404=1) AND under an authorized
+  # zone control. Every other 404 fails closed.
+  if [[ "$code" == "404" ]]; then
+    if [[ "$scheme" == "zone" && "$ZONE_CONTROL_OK" == "1" && "$trust404" == "1" ]]; then
+      VERDICT="empty (404, verified phase exists)"; return 0
+    fi
+    VERDICT="denied (404, unverified — fail-closed)"; return 1
+  fi
+  VERDICT="denied ($code)"; return 1
+}
+
+report() { printf '  %-42s %s\n' "$1" "$2"; }
+
+FAILED=0
+
+echo "cf-token-scope: probing CF_API_TOKEN_RULESETS retained scope (read-only)"
+
+# 1. Zone control first — every zone 404's trust depends on it. The control must
+# be an authorized 200 (trust404=0: a control that only 404s proves nothing).
+if check "$API/zones/$ZONE/rulesets/phases/$ZONE_CONTROL/entrypoint" zone 0; then ZONE_CONTROL_OK=1; fi
+report "$ZONE_CONTROL" "$VERDICT"
+[[ "$ZONE_CONTROL_OK" == "1" ]] || FAILED=1
+
+# 2. Remaining retained zone phases (trust404 per the verified-phase rule).
+for p in "${ZONE_PHASES[@]}"; do
+  [[ "$p" == "$ZONE_CONTROL" ]] && continue
+  check "$API/zones/$ZONE/rulesets/phases/$p/entrypoint" zone "$(trust404_for "$p")" || FAILED=1
+  report "$p" "$VERDICT"
+done
+
+# 3. Account list — the account-scheme control (an account 404 is a FAIL).
+check "$API/accounts/$ACCT/rulesets" account 0 || FAILED=1
+report "accounts/<acct>/rulesets" "$VERDICT"
+
+# 4. Target entrypoint (the newly-widened scope), if given. TARGET_PRESENT gates
+# the success line so it cannot print unless the target probe actually passed.
+TARGET_PRESENT=0
+if [[ -n "$TARGET" ]]; then
+  if check "$API/zones/$ZONE/rulesets/phases/$TARGET/entrypoint" zone "$(trust404_for "$TARGET")"; then
+    TARGET_PRESENT=1
+  else
+    FAILED=1
+  fi
+  report "target: $TARGET" "$VERDICT"
+fi
+
+echo
+if [[ "$FAILED" -eq 0 ]]; then
+  echo "PASS: no scope dropped"
+  # "present", not "added": a single run cannot observe the 403->authorized
+  # transition — the operator confirms that against the pre-widen baseline.
+  [[ -n "$TARGET" && "$TARGET_PRESENT" == "1" ]] && \
+    echo "PASS: target scope present ($TARGET) — confirm the 403->present transition against your pre-widen baseline"
+  exit 0
+fi
+
+if [[ "$ZONE_CONTROL_OK" != "1" ]]; then
+  echo "FAIL: zone control ($ZONE_CONTROL) is not authorized — the token is likely bad or missing its base scope, not a single dropped scope." >&2
+fi
+echo "FAIL: retained-scope probe failed — inspect the denied/degraded entrypoints above." >&2
+exit 3

package/skills/changelog/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: changelog
+description: "This skill should be used when creating changelogs for recent merges. Analyzes PR labels, issues, and descriptions to generate formatted summaries."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Changelog Generator
+
+Generate a fun, engaging changelog for an internal development team by summarizing the latest merges to the main branch, highlighting new features, bug fixes, and giving credit to the developers.
+
+## Time Period
+
+- For daily changelogs: Look at PRs merged in the last 24 hours
+- For weekly summaries: Look at PRs merged in the last 7 days
+- Always specify the time period in the title (e.g., "Daily" vs "Weekly")
+- Default: Get the latest changes from the last day from the main branch of the repository
+
+## PR Analysis
+
+Analyze the provided GitHub changes and related issues. Look for:
+
+1. New features that have been added
+2. Bug fixes that have been implemented
+3. Any other significant changes or improvements
+4. References to specific issues and their details
+5. Names of contributors who made the changes
+6. Use gh cli to lookup the PRs as well and the description of the PRs
+7. Check PR labels to identify feature type (feature, bug, chore, etc.)
+8. Look for breaking changes and highlight them prominently
+9. Include PR numbers for traceability
+10. Check if PRs are linked to issues and include issue context
+
+## Content Priorities
+
+1. Breaking changes (if any) - MUST be at the top
+2. User-facing features
+3. Critical bug fixes
+4. Performance improvements
+5. Developer experience improvements
+6. Documentation updates
+
+## Formatting Guidelines
+
+Create a changelog summary with the following guidelines:
+
+1. Keep it concise and to the point
+2. Highlight the most important changes first
+3. Group similar changes together (e.g., all new features, all bug fixes)
+4. Include issue references where applicable
+5. Mention the names of contributors, giving them credit for their work
+6. Add a touch of humor or playfulness to make it engaging
+7. Use emojis sparingly to add visual interest
+8. Keep total message under 2000 characters for Discord
+9. Use consistent emoji for each section
+10. Format code/technical terms in backticks
+11. Include PR numbers in parentheses (e.g., "Fixed login bug (#123)")
+
+## Deployment Notes
+
+When relevant, include:
+
+- Database migrations required
+- Environment variable updates needed
+- Manual intervention steps post-deploy
+- Dependencies that need updating
+
+The final output should be formatted as follows:
+
+<change_log>
+
+# 🚀 [Daily/Weekly] Change Log: [Current Date]
+
+## 🚨 Breaking Changes (if any)
+
+[List any breaking changes that require immediate attention]
+
+## 🌟 New Features
+
+[List new features here with PR numbers]
+
+## 🐛 Bug Fixes
+
+[List bug fixes here with PR numbers]
+
+## 🛠️ Other Improvements
+
+[List other significant changes or improvements]
+
+## 🙌 Shoutouts
+
+[Mention contributors and their contributions]
+
+## 🎉 Fun Fact of the Day
+
+[Include a brief, work-related fun fact or joke]
+
+</change_log>
+
+## Style Guide Review
+
+Review the changelog using the EVERY_WRITE_STYLE.md file and go one by one to ensure adherence to the style guide. Use multiple agents, run in parallel to make it faster.
+
+Remember, the final output should only include the content within the <change_log> tags. Do not include any thought process or original data in the output.
+
+## Discord Posting (Optional)
+
+Post changelogs to Discord by adding a webhook URL:
+
+First get the webhook URL with `printenv DISCORD_WEBHOOK_URL`, then post using curl with the literal URL:
+
+```bash
+curl -H "Content-Type: application/json" \
+  -d "{\"content\": \"{{CHANGELOG}}\"}" \
+  "<webhook-url>"
+```
+
+Replace `<webhook-url>` with the actual Discord webhook URL.
+
+To get a webhook URL, go to Discord server > Server Settings > Integrations > Webhooks > New Webhook.
+
+## Error Handling
+
+- If no changes in the time period, post a "quiet day" message: "🌤️ Quiet day! No new changes merged."
+- If unable to fetch PR details, list the PR numbers for manual review
+- Always validate message length before posting to Discord (max 2000 chars)
+
+## Schedule Recommendations
+
+- Run daily at 6 AM NY time for previous day's changes
+- Run weekly summary on Mondays for the previous week
+- Special runs after major releases or deployments
+
+## Audience Considerations
+
+Adjust the tone and detail level based on the channel:
+
+- **Dev team channels**: Include technical details, performance metrics, code snippets
+- **Product team channels**: Focus on user-facing changes and business impact
+- **Leadership channels**: Highlight progress on key initiatives and blockers

package/skills/code-to-prd/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: code-to-prd
+description: "This skill should be used when generating a PRD from a Next.js codebase for buyer/investor/agent handoff. Walks tracked files, redacts secrets, writes structured markdown to knowledge-base/product/prd/."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Code-to-PRD
+
+Reverse-engineer a Next.js codebase (App Router + Pages Router) into a PRD markdown document the founder can hand to a buyer, investor, or coding agent. Output lands at `knowledge-base/product/prd/<project>-prd.md`. v1 ships Next.js-only; Rails/Django and exhaustive field inventory deferred to v2 (#3794).
+
+## When to Use
+
+- Inherited Next.js prototype heading into buyer/investor due diligence.
+- Founder needs to onboard a coding agent or contractor to an unfamiliar codebase.
+- Sell-side IP handoff where the founder needs a structured artifact but cannot share raw source.
+
+## Output
+
+Single PRD at `knowledge-base/product/prd/<project>-prd.md` where `<project>` is the kebab-cased `package.json` `name`. **A second run with a target whose `package.json` `name` matches an earlier run overwrites the prior PRD** — the script emits a loud `WARNING — overwriting existing PRD at ...` on stderr so a wrong-codebase PRD does not reach a buyer's data room silently. Commit or rename the previous PRD before regenerating against a different codebase.
+
+The PRD contains:
+
+1. **Banners** — dual non-removable disclaimers (due-diligence + PII/confidentiality) + inline `### How to Read This PRD` subsection explaining redaction tokens.
+2. **Overview** — project name, framework detected, walk stats.
+3. **Routes** — App Router (`app/**/page.{tsx,jsx,ts,js}`, `app/**/route.{ts,js}`) and Pages Router (`pages/**/*.{tsx,jsx,ts,js}` excluding `pages/_*`).
+4. **State Shapes** — top-level `useState`/`useReducer`/server-component props (best-effort regex).
+5. **API & External Dependencies** — `fetch()` literal URLs + `@/lib/api*`/`@/server/*` imports + `process.env.*` names (values never read) + third-party SDK packages from `package.json`.
+6. **Coverage Caveats** — frameworks not scanned + extraction techniques + path-filter exclusion counts + Art. 9 special-category disclaimer.
+7. **Gap Analysis** — produced by `soleur:product:spec-flow-analyzer` Task spawn after the PRD is written and verified.
+8. **MIT Attribution** — footer pointing at `plugins/soleur/NOTICE`.
+
+## Redaction (3-layer, fail-closed)
+
+The skill is user-brand-critical (`single-user incident` threshold). Redaction is automated and fail-closed; the founder is NOT the last line of defense.
+
+- **Layer 1 — path exclusion.** Walker uses `git -C <target> ls-files -c -o --exclude-standard` (honors `.gitignore`) and an explicit deny-list: `.env*`, `secrets.*`, `*.pem`, `*.key`, `credentials.*`, `master.key`, `.git/**`. Symlinks resolving outside `<target>` are rejected via `realpath`.
+- **Layer 2 — pre-write sentinel.** Rendered PRD passes through [redact-sentinel.sh](../incident/scripts/redact-sentinel.sh) immediately before disk write. Exit code 1 (matches found) MUST abort the write. No partial PRD ever lands on disk.
+- **Layer 3 — pre-write verifier.** `gitleaks detect --source <rendered-file> --no-git --report-format json` is the independent verifier, run over the exact bytes about to be written. A finding (exit 1) or a scan that does not complete (exit 2) means the PRD is not written, and any previous PRD at the output path is left untouched. A runnable `gitleaks` is a Phase 0 preflight precondition — the skill refuses to start when it is missing or cannot run.
+
+## Preconditions
+
+- A runnable `gitleaks` on PATH (Layer 3 verifier). CI pins 8.24.2; a version-manager shim with no version set is refused at preflight.
+- `<target>` contains a `package.json` at the root.
+- `<target>` is under git OR contains tracked files (`git ls-files` returns ≥1 entry).
+- Framework detected as Next.js (presence of `next.config.{js,ts,mjs}` alongside `package.json`).
+
+## Resources
+
+- [prd-template.md](./references/prd-template.md) — canonical PRD section order + frontmatter (Phase 4).
+- [banner-template.md](./references/banner-template.md) — dual banners + inline How-to-Read content (Phase 4).
+- [code-to-prd.sh](./scripts/code-to-prd.sh) — entry-point script.
+
+## Implementation Status
+
+Scaffold landed (Phase 0); full implementation in progress per `knowledge-base/project/plans/archive/20261013-014038-2026-05-15-feat-code-to-prd-skill-plan.md`. See `knowledge-base/project/specs/archive/20261013-014038-feat-code-to-prd-2726/tasks.md` for phase progress.
+
+---
+
+_Adapted from `alirezarezvani/claude-skills` (MIT) — see [plugins/soleur/NOTICE](../../NOTICE)._

package/skills/code-to-prd/references/banner-template.md

@@ -0,0 +1,12 @@
+<!-- BANNER:DUE-DILIGENCE — non-removable per code-to-prd FR7 -->
+> **Due-diligence disclaimer.** This PRD is auto-generated from source code by `code-to-prd` (#2726). It is a best-effort regex-driven snapshot, not an exhaustive specification. Routes, state shapes, and external dependencies are extracted from filesystem walk + grep — no AST analysis is performed in v1. Verify any load-bearing claim against the source tree before relying on it for an acquisition, valuation, or audit decision.
+
+<!-- BANNER:PII-CONFIDENTIALITY — non-removable per code-to-prd FR7 -->
+> **Confidentiality / PII notice.** This PRD may reference business logic, environment-variable names, and route topology. Secret values, JWTs, API keys, and the 16 redaction classes enumerated in `plugins/soleur/skills/incident/scripts/redact-engine.py` are scrubbed at write-time by a 3-layer fail-closed pipeline (path filter → sentinel → gitleaks); the sentinel NFKC-normalizes and strips invisible characters before matching (defeats Unicode-confusable evasion). Redacted tokens render as `<≤4-prefix>***<≤4-suffix>` (or `***` for short tokens). Treat this document as containing the business posture of the codebase — share it with the same care you would the codebase itself.
+
+### How to Read This PRD
+
+- **Redaction-token format.** When a token would have appeared in the source, the PRD shows `<≤4-prefix>***<≤4-suffix>` (or `***` for short tokens) instead. The token format is the redaction signature, not a leak.
+- **Redacted ≠ leaked.** A redaction marker means the scanner *found and removed* a secret. Nothing sensitive landed in this document.
+- **If you see a token shape (`sk_…`, `ghp_…`, `eyJ…`, etc.) in plaintext:** the source file contained that secret. Rotate the credential, move it to `.env`, and regenerate the PRD.
+- **Coverage Caveats** at the end of this PRD enumerates what was excluded, which frameworks were not scanned, and the GDPR Art. 9 special-category gap. Read it before sharing.

package/skills/code-to-prd/references/prd-template.md

@@ -0,0 +1,41 @@
+# PRD Template — code-to-prd output structure
+
+Canonical section order for `knowledge-base/product/prd/<project>-prd.md` emitted by `plugins/soleur/skills/code-to-prd/scripts/code-to-prd.sh`. Mirrored by the `prd.md` template in `plugins/soleur/skills/spec-templates/SKILL.md`.
+
+## Required frontmatter
+
+```yaml
+---
+project: "<package.json name, kebab-case>"
+framework: "next.js"
+generator: "code-to-prd@v1"
+generated_at: "<ISO-8601 UTC>"
+walker_count: <int>
+walker_excluded: <int>
+---
+```
+
+## Section order (FR7)
+
+1. **Banners** — dual non-removable disclaimers + inline `### How to Read This PRD` (verbatim from [banner-template.md](./banner-template.md)).
+2. **Overview** — project name, framework detected, walk stats (tracked-file count, excluded-file count).
+3. **Routes**
+   - App Router — `app/**/page.{tsx,jsx,ts,js}` + `app/**/route.{ts,js}` (with HTTP methods).
+   - Pages Router — `pages/**/*.{tsx,jsx,ts,js}` excluding `pages/_*`.
+4. **State Shapes** — top-level `useState`/`useReducer`/server-component props (regex, best-effort).
+5. **API & External Dependencies** — `fetch()` literal URLs + `@/lib/api*`/`@/server/*` imports + `process.env.*` names (values never read) + third-party SDK packages from `package.json`.
+6. **Coverage Caveats** — FOUR mandatory subsections (FR10.1):
+   - Frameworks not scanned (Rails, Django, etc.).
+   - Extraction techniques used (regex-only, no AST).
+   - What was excluded by path filter (count + category, not paths).
+   - GDPR Art. 9 special-category disclaimer.
+7. **Gap Analysis** — populated by spawning the agent `soleur:product:spec-flow-analyzer` against the PRD path (FR8). When it is unavailable, `scripts/code-to-prd.sh` writes a degraded-success placeholder of the form `SKIPPED (<agent> unavailable at <ISO-8601>)`. That line names the agent by its BARE LEAF on purpose: it is a human-readable status in a generated document, never a dispatch, so it is deliberately not the canonical id the rest of this file uses.
+8. **MIT Attribution footer** — single line pointing at `plugins/soleur/NOTICE`.
+
+## Banner contract
+
+Banners are **non-removable** — operator-edit of the rendered PRD is allowed, but the dual-banner block must remain intact. Verbatim string match enforced by Phase 6 test assertion #6.
+
+## Coverage Caveats contract
+
+The `## Coverage Caveats` block MUST be non-empty on every run. "None" is forbidden. The four subsections are mandatory regardless of extractor coverage — even on a maximally simple input.