@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/compound-capture/assets/critical-pattern-template.md

@@ -0,0 +1,37 @@
+# Critical Pattern Template
+
+Use this template when adding a pattern to `knowledge-base/project/learnings/patterns/critical-patterns.md`:
+
+---
+
+## N. [Pattern Name] (ALWAYS REQUIRED)
+
+### ❌ WRONG ([Will cause X error])
+
+```[language]
+[code showing wrong approach]
+```
+
+### ✅ CORRECT
+
+```[language]
+[code showing correct approach]
+```
+
+**Why:** [Technical explanation of why this is required]
+
+**Placement/Context:** [When this applies]
+
+**Documented in:** `knowledge-base/project/learnings/[category]/[filename].md`
+
+---
+
+**Instructions:**
+
+1. Replace N with the next pattern number
+2. Replace [Pattern Name] with descriptive title
+3. Fill in WRONG example with code that causes the problem
+4. Fill in CORRECT example with the solution
+5. Explain the technical reason in "Why"
+6. Clarify when this pattern applies in "Placement/Context"
+7. Link to the full troubleshooting doc where this was originally solved

package/skills/compound-capture/assets/resolution-template.md

@@ -0,0 +1,116 @@
+---
+module: [Module name or "System" for system-wide]
+date: [YYYY-MM-DD]
+problem_type: [build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error]
+component: [rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments]
+symptoms:
+  - [Observable symptom 1 - specific error message or behavior]
+  - [Observable symptom 2 - what user actually saw/experienced]
+root_cause: [missing_association|missing_include|missing_index|wrong_api|scope_issue|thread_violation|async_timing|memory_leak|config_error|logic_error|test_isolation|missing_validation|missing_permission]
+rails_version: [7.1.2 - optional]
+resolution_type: [code_fix|migration|config_change|test_fix|dependency_update|environment_setup]
+severity: [critical|high|medium|low]
+status: open  # defaults to open — close via /soleur:resolve-debt
+tags: [keyword1, keyword2, keyword3]
+---
+
+# Troubleshooting: [Clear Problem Title]
+
+## Problem
+
+[1-2 sentence clear description of the issue and what the user experienced]
+
+## Environment
+
+- Module: [Name or "System-wide"]
+- Rails Version: [e.g., 7.1.2]
+- Affected Component: [e.g., "Email Processing model", "Brief System service", "Authentication controller"]
+- Date: [YYYY-MM-DD when this was solved]
+
+## Symptoms
+
+- [Observable symptom 1 - what the user saw/experienced]
+- [Observable symptom 2 - error messages, visual issues, unexpected behavior]
+- [Continue as needed - be specific]
+
+## What Didn't Work
+
+**Attempted Solution 1:** [Description of what was tried]
+
+- **Why it failed:** [Technical reason this didn't solve the problem]
+
+**Attempted Solution 2:** [Description of second attempt]
+
+- **Why it failed:** [Technical reason]
+
+[Continue for all significant attempts that DIDN'T work]
+
+[If nothing else was attempted first, write:]
+**Direct solution:** The problem was identified and fixed on the first attempt.
+
+## Session Errors
+
+[Process mistakes and command failures encountered during this session, beyond the main problem investigation. Omit this section entirely if no session errors occurred.]
+
+**[Brief error description]**
+
+- **Recovery:** [What fixed it]
+- **Prevention:** [How to avoid in future]
+
+[Repeat for each session error]
+
+## Solution
+
+[The actual fix that worked - provide specific details]
+
+**Code changes** (if applicable):
+
+```ruby
+# Before (broken):
+[Show the problematic code]
+
+# After (fixed):
+[Show the corrected code with explanation]
+```
+
+**Database migration** (if applicable):
+
+```ruby
+# Migration change:
+[Show what was changed in the migration]
+```
+
+**Commands run** (if applicable):
+
+```bash
+# Steps taken to fix:
+[Commands or actions]
+```
+
+## Why This Works
+
+[Technical explanation of:]
+
+1. What was the ROOT CAUSE of the problem?
+2. Why does the solution address this root cause?
+3. What was the underlying issue (API misuse, configuration error, Rails version issue, etc.)?
+
+[Be detailed enough that future developers understand the "why", not just the "what"]
+
+## Prevention
+
+[How to avoid this problem in future development:]
+
+- [Specific coding practice, check, or pattern to follow]
+- [What to watch out for]
+- [How to catch this early]
+
+## Related Issues
+
+[If any similar problems exist in knowledge-base/project/learnings/, link to them:]
+
+- See also: [another-related-issue.md](../category/another-related-issue.md)
+- Similar to: [related-problem.md](../category/related-problem.md)
+
+[If no related issues, write:]
+No related issues documented yet.

package/skills/compound-capture/references/yaml-schema.md

@@ -0,0 +1,67 @@
+# YAML Frontmatter Schema
+
+**See `plugins/soleur/skills/compound-capture/schema.yaml` for the complete schema specification.**
+
+## Required Fields
+
+- **module** (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
+- **date** (string): ISO 8601 date (YYYY-MM-DD)
+- **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
+- **component** (enum): One of [rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, authentication, payments, development_workflow, testing_framework, documentation, tooling]
+- **symptoms** (array): 1-5 specific observable symptoms
+- **root_cause** (enum): One of [missing_association, missing_include, missing_index, wrong_api, scope_issue, thread_violation, async_timing, memory_leak, config_error, logic_error, test_isolation, missing_validation, missing_permission, missing_workflow_step, inadequate_documentation, missing_tooling, incomplete_setup]
+- **resolution_type** (enum): One of [code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update]
+- **severity** (enum): One of [critical, high, medium, low]
+
+## Optional Fields
+
+- **rule_id** (string): AGENTS.md rule slug this learning relates to. Must match `^(hr|wg|cq|rf|pdr|cm)-[a-z0-9-]{3,40}$` (e.g., `hr-never-git-stash-in-worktrees`). Hit/bypass counters for rules live in `knowledge-base/project/rule-metrics.json`, not in the learning frontmatter (see plan ADR-1).
+- **rails_version** (string): Rails version in X.Y.Z format
+- **tags** (array): Searchable keywords (lowercase, hyphen-separated)
+
+## Validation Rules
+
+1. All required fields must be present
+2. Enum fields must match allowed values exactly (case-sensitive)
+3. symptoms must be YAML array with 1-5 items
+4. date must match YYYY-MM-DD format
+5. rails_version (if provided) must match X.Y.Z format
+6. tags should be lowercase, hyphen-separated
+7. rule_id (if provided) must match the six-section prefix pattern (hr, wg, cq, rf, pdr, cm)
+
+## Example
+
+```yaml
+---
+module: Email Processing
+date: 2025-11-12
+problem_type: performance_issue
+component: rails_model
+symptoms:
+  - "N+1 query when loading email threads"
+  - "Brief generation taking >5 seconds"
+root_cause: missing_include
+rails_version: 7.1.2
+resolution_type: code_fix
+severity: high
+tags: [n-plus-one, eager-loading, performance]
+---
+```
+
+## Category Mapping
+
+Based on `problem_type`, documentation is filed in:
+
+- **build_error** → `knowledge-base/project/learnings/build-errors/`
+- **test_failure** → `knowledge-base/project/learnings/test-failures/`
+- **runtime_error** → `knowledge-base/project/learnings/runtime-errors/`
+- **performance_issue** → `knowledge-base/project/learnings/performance-issues/`
+- **database_issue** → `knowledge-base/project/learnings/database-issues/`
+- **security_issue** → `knowledge-base/project/learnings/security-issues/`
+- **ui_bug** → `knowledge-base/project/learnings/ui-bugs/`
+- **integration_issue** → `knowledge-base/project/learnings/integration-issues/`
+- **logic_error** → `knowledge-base/project/learnings/logic-errors/`
+- **developer_experience** → `knowledge-base/project/learnings/developer-experience/`
+- **workflow_issue** → `knowledge-base/project/learnings/workflow-issues/`
+- **best_practice** → `knowledge-base/project/learnings/best-practices/`
+- **documentation_gap** → `knowledge-base/project/learnings/documentation-gaps/`

package/skills/compound-capture/schema.yaml

@@ -0,0 +1,181 @@
+# CORA Documentation Schema
+# This schema MUST be validated before writing any documentation file
+
+required_fields:
+  module:
+    type: string
+    description: "Module/area of CORA (e.g., 'Email Processing', 'Brief System', 'Authentication')"
+    examples:
+      - "Email Processing"
+      - "Brief System"
+      - "Assistant"
+      - "Authentication"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date when this problem was solved (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error          # Rails, bundle, compilation errors
+      - test_failure         # Test failures, flaky tests
+      - runtime_error        # Exceptions, crashes during execution
+      - performance_issue    # Slow queries, memory issues, N+1 queries
+      - database_issue       # Migration, query, schema problems
+      - security_issue       # Authentication, authorization, XSS, SQL injection
+      - ui_bug               # Frontend, Stimulus, Turbo issues
+      - integration_issue    # External service, API integration problems
+      - logic_error          # Business logic bugs
+      - developer_experience # DX issues: workflow, tooling, seed data, dev setup
+      - workflow_issue       # Development process, missing steps, unclear practices
+      - best_practice        # Documenting patterns and practices to follow
+      - documentation_gap    # Missing or inadequate documentation
+    description: "Primary category of the problem"
+
+  component:
+    type: enum
+    values:
+      - rails_model          # ActiveRecord models
+      - rails_controller     # ActionController
+      - rails_view           # ERB templates, ViewComponent
+      - service_object       # Custom service classes
+      - background_job       # Sidekiq, Active Job
+      - database             # PostgreSQL, migrations, schema
+      - frontend_stimulus    # Stimulus JS controllers
+      - hotwire_turbo        # Turbo Streams, Turbo Drive
+      - email_processing     # Email handling, mailers
+      - brief_system         # Brief generation, summarization
+      - assistant            # AI assistant, prompts
+      - authentication       # Devise, user auth
+      - payments             # Stripe, billing
+      - development_workflow # Dev process, seed data, tooling
+      - testing_framework    # Test setup, fixtures, VCR
+      - documentation        # README, guides, inline docs
+      - tooling              # Scripts, generators, CLI tools
+    description: "CORA component involved"
+
+  symptoms:
+    type: array[string]
+    min_items: 1
+    max_items: 5
+    description: "Observable symptoms (error messages, visual issues, crashes)"
+    examples:
+      - "N+1 query detected in brief generation"
+      - "Brief emails not appearing in summary"
+      - "Turbo Stream response returns 404"
+
+  root_cause:
+    type: enum
+    values:
+      - missing_association  # Incorrect Rails associations
+      - missing_include      # Missing eager loading (N+1)
+      - missing_index        # Database performance issue
+      - wrong_api            # Using deprecated/incorrect Rails API
+      - scope_issue          # Incorrect query scope or filtering
+      - thread_violation     # Real-time unsafe operation
+      - async_timing         # Async/background job timing
+      - memory_leak          # Memory leak or excessive allocation
+      - config_error         # Configuration or environment issue
+      - logic_error          # Algorithm/business logic bug
+      - test_isolation       # Test isolation or fixture issue
+      - missing_validation   # Missing model validation
+      - missing_permission   # Authorization check missing
+      - missing_workflow_step # Skipped or undocumented workflow step
+      - inadequate_documentation # Missing or unclear documentation
+      - missing_tooling      # Lacking helper scripts or automation
+      - incomplete_setup     # Missing seed data, fixtures, or config
+    description: "Fundamental cause of the problem"
+
+  resolution_type:
+    type: enum
+    values:
+      - code_fix             # Fixed by changing source code
+      - migration            # Fixed by database migration
+      - config_change        # Fixed by changing configuration
+      - test_fix             # Fixed by correcting tests
+      - dependency_update    # Fixed by updating gem/dependency
+      - environment_setup    # Fixed by environment configuration
+      - workflow_improvement # Improved development workflow or process
+      - documentation_update # Added or updated documentation
+      - tooling_addition     # Added helper script or automation
+      - seed_data_update     # Updated db/seeds.rb or fixtures
+    description: "Type of fix applied"
+
+  severity:
+    type: enum
+    values:
+      - critical             # Blocks production or development (build fails, data loss)
+      - high                 # Impairs core functionality (feature broken, security issue)
+      - medium               # Affects specific feature (UI broken, performance impact)
+      - low                  # Minor issue or edge case
+    description: "Impact severity"
+
+optional_fields:
+  rule_id:
+    type: string
+    pattern: '^(hr|wg|cq|rf|pdr|cm)-[a-z0-9-]{3,40}$'
+    description: "AGENTS.md rule slug that motivated this learning (e.g., 'hr-never-git-stash-in-worktrees'). Counters live in knowledge-base/project/rule-metrics.json, not here (see plan ADR-1)."
+
+  rails_version:
+    type: string
+    pattern: '^\d+\.\d+\.\d+$'
+    description: "Rails version where this was encountered (e.g., '7.1.0')"
+
+  related_components:
+    type: array[string]
+    description: "Other components that interact with this issue"
+
+  tags:
+    type: array[string]
+    max_items: 8
+    description: "Searchable keywords (lowercase, hyphen-separated)"
+    examples:
+      - "n-plus-one"
+      - "eager-loading"
+      - "test-isolation"
+      - "turbo-stream"
+
+validation_rules:
+  - "module must be a valid CORA module name"
+  - "date must be in YYYY-MM-DD format"
+  - "problem_type must match one of the enum values"
+  - "component must match one of the enum values"
+  - "symptoms must be specific and observable (not vague)"
+  - "root_cause must be the ACTUAL cause, not a symptom"
+  - "resolution_type must match one of the enum values"
+  - "severity must match one of the enum values"
+  - "tags should be lowercase, hyphen-separated"
+
+# Example valid front matter:
+# ---
+# module: Email Processing
+# date: 2025-11-12
+# problem_type: performance_issue
+# component: rails_model
+# symptoms:
+#   - N+1 query when loading email threads
+#   - Brief generation taking >5 seconds
+# root_cause: missing_include
+# rails_version: 7.1.2
+# resolution_type: code_fix
+# severity: high
+# tags: [n-plus-one, eager-loading, performance]
+# ---
+#
+# Example DX issue front matter:
+# ---
+# module: Development Workflow
+# date: 2025-11-13
+# problem_type: developer_experience
+# component: development_workflow
+# symptoms:
+#   - No example data for new feature in development
+#   - Rails db:seed doesn't demonstrate new capabilities
+# root_cause: incomplete_setup
+# rails_version: 7.1.2
+# resolution_type: seed_data_update
+# severity: low
+# tags: [seed-data, dx, workflow]
+# ---

package/skills/constraint-scaffold/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: constraint-scaffold
+description: "This skill should be used when generating the Layer 1 dependency-cruiser import-boundary gate (client modules importing server secrets) into a Next.js product codebase's CI."
+---
+
+<!-- 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 -->
+
+<!-- Inspired by mattpocock/skills/skills/in-progress/setup-ts-deep-modules/SKILL.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+
+# constraint-scaffold
+
+Generates **one** deterministic, no-LLM Layer-1 structural gate into a Next.js product
+codebase: a [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) **import-boundary
+gate** that fails closed when a `"use client"` module takes a **value** (non-`type-only`) import on
+the server-only tree (`server/**`) — i.e. a server secret leaking into the browser bundle. The gate
+runs in CI and rejects the violation *before* the LLM-judged review layer (`soleur:review`). See
+ADR-071 (mechanism = Option D) and `knowledge-base/project/plans/archive/20261013-032858-2026-06-30-feat-constraint-scaffold-l1-gate-generator-plan.md`.
+
+This gate covers this one boundary only, CI-only, Next.js-only. It catches BOTH direct
+client→server-secret value imports AND transitive ones (a `"use client"` module reaching a
+server secret through a chain of value imports, e.g. a non-client `lib/` helper) — the transitive
+`reachable` rule was added in the 2026-07-01 #5777 amendment (ADR-071 §Amendment). Naming /
+contract / pre-commit / multi-stack coverage remain deferred (ADR-071 Consequences).
+
+## Agent-owns-gates recovery model (load-bearing)
+
+The gate is **fail-closed**, and the target user is a non-technical founder who can never hand-edit
+a `.cjs` config, a baseline, or a workflow. So the agent — never the founder — owns gate
+maintenance and recovery:
+
+1. **The agent authors and maintains the gate.** The founder never touches `.dependency-cruiser.cjs`,
+   `.dependency-cruiser-known-violations.json`, the shared runner, or the workflow.
+2. **When the agent's own change trips the gate:**
+   - real leak → the agent fixes the offending import;
+   - legitimate new cross-boundary import → the agent runs
+     `constraint-scaffold.sh --refresh-baseline` (clean-tree + `origin/main` merge-base capture, so a
+     same-PR violation is never grandfathered); the baseline diff is PR-reviewable.
+3. **In-code escape hatch (agent-owned, used sparingly):** dependency-cruiser's native
+   `// dependency-cruiser-disable-next-line` comment on the importing line.
+4. **Founder hotfix with no agent in the loop (the brand-survival deadlock).** A GitHub-web hotfix
+   or a machine without the repo tooling can trip the gate with no agent present. Recovery is
+   **automatic and zero-touch**: the two-stage auto-recovery dispatcher (`fix-constraints-stage-a`
+   → `fix-constraints-stage-b`, **ADR-074**) fires on the PR, fixes the offending import, and opens
+   a **draft follow-up PR** the founder can merge — no comment, no command, no agent-in-the-loop
+   required. (A real leak the agent cannot fix is surfaced for a maintainer; auto-recovery is
+   fix-only and never grows the suppression baseline.) The gate stays **informational /
+   non-blocking** — it is NOT promoted to a required check (promotion is now blocked only on #5778;
+   the #5791 dispatcher half is satisfied by ADR-074), so it cannot deadlock a founder hotfix.
+   **No override label, no `.cjs` edit, no second human required.**
+5. The founder is **never** required to read or unblock the gate.
+
+## Usage
+
+Generate the gate into `apps/web-platform` (default mode — detect Next.js, require `app/`,
+`components/` and `server/` to exist under the target, emit config + shared runner + CI workflow,
+capture the initial baseline, **prove the gate bites** (see Bite-proof below), then write the
+boundary README and the agent-instructions pointer last). Non-destructive: refuses to overwrite an
+existing `.cjs`, runner, or workflow (there is no `--force`); the baseline JSON is the only
+re-writable artifact, and only via `--refresh-baseline`; the README block and the pointer line are
+append-once (marker-keyed, never rewritten):
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/constraint-scaffold/scripts/constraint-scaffold.sh"
+```
+
+Refresh the baseline after a legitimate new cross-boundary import (agent-only; clean tree required;
+captures against the `origin/main` merge-base). Refresh mode runs the bite-proof too — it catches
+config/runner drift a baseline entry can never grandfather (a rule softened to `warn`, a mis-scoped
+from-set, a runner that stopped failing on rc>0) — and it can exit **74** when HEAD carries a real
+client→server-secret violation newer than the baseline; that is the gate being live, not a broken
+gate, and the fix is the listed import, not a re-run. In refresh mode nothing is removed on failure
+(the artifacts are committed); the rewritten baseline is reviewed with `git diff`:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/constraint-scaffold/scripts/constraint-scaffold.sh" --refresh-baseline
+```
+
+## What it emits (into `apps/web-platform/`)
+
+| Artifact | Role |
+|---|---|
+| `.dependency-cruiser.cjs` | Executable CommonJS config. Computes the `"use client"` from-set at require-time (recomputed every run, **never** committed static), regex-escaping route-group paths. `tsConfig.fileName` + `tsPreCompilationDeps` give `@/*` alias resolution and the type-only/value distinction. |
+| `.dependency-cruiser-known-violations.json` | dependency-cruiser native baseline (`--output-type baseline` / `--ignore-known`). Grandfathers only pre-existing violations. |
+| `apps/web-platform/scripts/constraint-gates.sh` | Shared runner — owns the single pinned `depcruise --ignore-known … --output-type err` invocation. Fails closed on any non-zero depcruise rc; CI (and future pre-commit) both exec this. |
+| `.github/workflows/constraint-gates.yml` | Always-runs + internal path-check (reports a real conclusion on every PR; no pending-forever deadlock). On failure the two-stage auto-recovery dispatcher (`fix-constraints-stage-a/b`, ADR-074) auto-opens a follow-up PR when the gate is auto-fixable. Informational/non-blocking until promoted (now blocked only on #5778; the #5791 dispatcher half is satisfied by ADR-074). |
+| `.github/workflows/fix-constraints-stage-a.yml` | Untrusted `pull_request` producer (ADR-074): `contents: read` only. Runs the gate, dispatches the fix-only agent, re-verifies green, uploads the fix as a full-post-image-contents artifact (per-file sha256 + meta.json). No write token, no commit/push. |
+| `.github/workflows/fix-constraints-stage-b.yml` | Privileged `workflow_run` consumer (ADR-074): validates the attacker-controlled artifact (isCrossRepository==false gate, event-sourced identity, charset+traversal+symlink+size allowlist, sha256 byte-verify) and applies it via the Git Data API (blob→tree with mandatory base_tree→commit→ref) — never checks out the untrusted tree, never git-applies. Delivers a draft follow-up PR. |
+| `server/README.md` | Boundary README next to the governed path: what the boundary is, the two rule names, `import type` as the permitted shape, how to run the gate, the three-dirs requirement, what the founder sees when it trips (a red check and, when auto-fixable, an ADR-074 draft PR), that install proved pass → fail → pass, how to re-prove, and the agent-owns-recovery rule. **Append-once** between `<!-- constraint-scaffold:readme:start -->` / `:end -->` markers (existing content untouched; a symlink is refused); **written last**, after the bite-proof, so the clean-tree guard inside baseline capture never sees it. Soleur-authored; no peer sentence, no attribution line in the emission. Default mode only. |
+| repo-root `CLAUDE.md` (else `AGENTS.md`, created if absent) | One plain, informational pointer line naming `apps/web-platform/server/README.md`, ending in `<!-- constraint-scaffold:pointer -->`; append-once; never an `@path` import (that would load the README into every session) and never an imperative "read X before Y". The first scaffold write outside the target directory (ADR-071 amendment). Written last, with the README. Default mode only. |
+
+**Before editing either stage workflow (or its template), read ADR-074 + [[2026-07-01-two-stage-privileged-workflow-split-and-its-review-traps]].** The load-bearing invariants — trigger split (untrusted producer / privileged non-executing consumer), Stage B's `isCrossRepository==false` gate on the *fully attacker-controlled* artifact, event-sourced identity, mandatory `base_tree`, name-coupling (`workflow_run` matches Stage A's `name:`, not its filename), the give-up marker (no terminal state is silent), and `emit()` output-sanitization — are enforced by `test/emit-fix-constraints.test.sh` + `test/parity.test.sh` (which covers the repo-root dogfood copies, not just emitted fixtures). A change that greens those tests but breaks an invariant is the class the tests exist to catch.
+
+## Bite-proof (every run)
+
+A gate that cannot fail is not a gate. Both modes end by proving, on the committed tree, that the
+emitted gate goes **pass → fail → pass**; the founder never sees a scaffold whose only evidence is
+that it ran green once:
+
+1. **Stage.** In a detached-HEAD worktree under `$TMPDIR` (a `TMPDIR` that resolves inside the
+   repository is refused, exit 69, before anything is written, so the worktree and its logs can never
+   land in the founder's tree as untracked files), copy the three artifacts that may be uncommitted —
+   config, runner, baseline — into the target path and symlink the target's `node_modules`, exactly
+   as baseline capture does. A symlinked `server/` or `components/` is refused (71): the probes are
+   never written through a link.
+   Every runner invocation is captured to a `bite-N.log` so a failure can show its evidence before
+   the worktree is removed.
+2. **Pass.** The runner must exit 0 on the clean tree. `error <rule>:` lines in the log → exit
+   **74** (real violations on HEAD newer than the merge-base baseline — the gate is live; fix the
+   listed imports); any other non-zero → exit **71** (config or toolchain error; log tail shown).
+3. **Inject — each rule on the edge it exists for.** Under
+   `components/__constraint_scaffold_bite_probe__/`: a `"use client"` module value-importing the
+   probe server module directly, a non-client hop that imports it, and a `"use client"` module that
+   imports the hop; plus `server/__constraint_scaffold_bite_probe__.ts` exporting one string that is
+   visibly not a secret.
+4. **Fail, naming both rules on their own edges.** The runner must exit non-zero **and** the log must
+   carry `error no-client-to-server-secret: … direct.tsx` and
+   `error no-client-to-server-secret-transitive: … via-hop.tsx` — anchored on depcruise's call-form,
+   never a bare rule name. Otherwise exit **72**: the gate did NOT reject the injected import.
+5. **Revert.** The four probe files are removed.
+6. **Pass again.** The runner must exit 0, else exit **73** (non-deterministic gate).
+7. The helper removes the worktree (also on INT/TERM — the handler exits 143 with the worktree gone).
+   One verdict line on stdout: `constraint-scaffold: bite-proof pass -> fail(no-client-to-server-secret@direct, no-client-to-server-secret-transitive@via-hop) -> pass depcruise=<version>`.
+
+**Exit codes 71–74 and what the agent does next.** Every bite failure prints
+`constraint-scaffold: bite-proof FAILED (<code>): <msg>` and the last 40 lines of the relevant log
+on stdout. In **default mode** the self-cleanup is armed before the first artifact is written and
+disarmed only after the bite has passed, so this holds for every failure in between — 66..74, an
+unusable `TMPDIR`, a `set -e` abort, an INT/TERM (143), a runner interrupted by a terminal Ctrl-C
+(130): the script removes every artifact this run emitted (config, runner, the three workflows, the
+baseline; empty `scripts/` and `.github/workflows/` directories are removed too) and says so — the
+README and pointer have not been written yet — so the repo is as it was and the next run is a clean
+first install, never a 66 on a half-installed gate. Every failure message is on stdout first
+(`constraint-scaffold: FAILED (<code>): …`). Only a SIGKILL can leave residue (the six files plus a
+stale `.git/worktrees` registration); the 66 message names that recovery (`git clean -n`, `git
+worktree prune`, re-run). The base ref is `origin/main`, else the remote's default branch
+(`origin/HEAD` — a founder repo on `master`); neither present exits 69 before anything is written.
+In refresh mode nothing is removed. One run per repository at a time: a `mkdir` lock in the git
+common dir (owner pid inside) makes a concurrent run a 69 naming the pid; a stale lock is taken
+over. The 68/69 messages carry git's / dependency-cruiser's own last lines (a failing
+`post-checkout` hook, a parse error) and name a shallow clone. The generator uses POSIX tools only
+(stock macOS included). A failure while writing the README or the pointer **after** a
+successful bite is a warning on stdout, not a fatal: the gate is installed and proven; the message
+names the file and the missing doc. **Hosted-runner deviation:** `plugins/soleur/` is vendored into
+the production image, so this script can run where no human reads stdout; there a 71–74 is
+transcript-only by design — no `SOLEUR_*` marker is emitted (AC13, the marker-population caution)
+— and the mirrored-not-paged `SOLEUR_CONSTRAINT_SCAFFOLD_HALT` is #8381 (`deferred-scope-out`).
+
+**Precondition (exit 65).** Default mode requires `app/`, `components/` and `server/` to exist under
+the target before anything is emitted — the emitted runner cruises all three and would fail its own
+CI otherwise; the message names the missing one. The README names the requirement.
+
+The script carries **no test seams** (no `CONSTRAINT_SCAFFOLD_TEST_*` variable is honoured); the
+suite drives every failure arm through a fixture-owned stub `depcruise` reached via the fixture's
+`node_modules` symlink. Decision record: ADR-071 §Amendment 2026-09-19 (#8288).
+
+## Self-tests
+
+`test/bite-proof.test.sh` (scripts shard) pins the contract above: pass → fail → pass on the real
+dependency-cruiser; every 71/72/73/74 arm through the stub; both rule names asserted on their own
+probe files; worktree removal on success, on failure and on TERM; default-mode self-cleanup leaving
+the fixture tree as it was; and the `TMPDIR`-inside-repo refusal.
+
+`test/boundary.test.sh` (scripts shard) proves the gate is not vacuous: a value import of `server/**`
+via the `@/server/…` alias FAILS, an `import type` of the same PASSES, route-group/metacharacter
+paths are matched (regex-escaping), an empty from-set while `"use client"` files exist is a hard
+error, and a broken `.cjs` fails the runner closed.
+
+- **Sharp edge (transitive rule):** the "reachable baseline stays empty" guard MUST key on the
+  transitive rule NAME, never on `type:"reachability"` — dependency-cruiser softens the reachable
+  rule per-origin on `from`+`rule.name` IGNORING entry `type`, so a `type:"module"` baseline entry
+  naming the rule suppresses a real leak while a type-count reads 0 (a `--refresh-baseline` capture
+  never emits that shape, so the regression fixture must inject it by hand). See
+  `knowledge-base/project/learnings/security-issues/2026-07-01-depcruise-reachability-baseline-softens-per-rule-name-ignoring-type.md`.

package/skills/constraint-scaffold/references/boundary-readme.template

@@ -0,0 +1,35 @@
+<!-- Inspired by mattpocock/skills/skills/in-progress/setup-ts-deep-modules/SKILL.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+<!-- constraint-scaffold:readme:start -->
+<!-- Generated by soleur:constraint-scaffold (ADR-071). The agent, never the founder, owns this block: it is appended once, keyed on the start/end markers, and not rewritten by later runs; when the skill's template changes, the agent replaces the block between the markers by hand. Edit the template, not this copy. -->
+
+## Client/server import boundary
+
+A `"use client"` module under `app/` or `components/` must never take a value import on `server/**`, whether directly or through a chain of other modules. A value import pulls the server module, and any secret it reads, into the browser bundle. Types are erased at build time, so `import type { Shape } from "@/server/config"` is the permitted shape for anything a client needs to know about a server module.
+
+dependency-cruiser enforces this with two rules in `.dependency-cruiser.cjs`:
+
+- `no-client-to-server-secret` flags a client module whose own import statement targets `server/**`.
+- `no-client-to-server-secret-transitive` flags a client module that reaches `server/**` through one or more non-client helpers.
+
+### Running the gate
+
+From `__TARGET_DIR__`:
+
+```bash
+bash scripts/constraint-gates.sh
+```
+
+Exit 0 means no violation beyond the committed baseline (`.dependency-cruiser-known-violations.json`). Any other exit means either a real boundary violation or a broken toolchain, and both fail closed. The runner cruises `app/`, `components/` and `server/` and matches imports by their resolved path, so all three directories must exist and the `@/*` alias in `tsconfig.json` must resolve.
+
+### What happens when it trips
+
+The `constraint-gates` workflow runs on every pull request that touches `__TARGET_DIR__`. When the gate trips, the pull request shows a red check. When the offending import can be corrected mechanically, the two-stage recovery workflow (ADR-074) opens a draft follow-up pull request carrying the fix for review and merge. When it cannot, the check stays red until the import is changed (or, for a legitimate cross-boundary import, the agent adds the in-code exemption) — a refresh never clears a leak introduced on the current branch.
+
+### Proven to bite
+
+Installing this gate did not stop at writing files. The scaffold checked out the committed tree in a detached worktree, ran the gate (pass), injected a direct client import and a one-hop chain into `server/**`, confirmed the gate named each rule on its own edge (fail), removed the probes and ran the gate again (pass). The same proof runs on every `--refresh-baseline`, so a config edit that quietly disarms a rule is caught at the next refresh rather than at the next leak.
+
+### Ownership and recovery
+
+`.dependency-cruiser.cjs`, `scripts/constraint-gates.sh` and the baseline file are agent-owned; do not hand-edit them. To re-baseline after `main` has moved, or to re-run the bite proof, run the `soleur:constraint-scaffold` skill with `--refresh-baseline`. It refuses a dirty tree and captures the baseline against the `origin/main` merge-base, so a leak introduced on the current branch is never grandfathered.
+<!-- constraint-scaffold:readme:end -->