@webpresso/agent-kit 0.21.0

package/catalog/agent/commands/pll.md

@@ -0,0 +1,174 @@
+---
+description: Blueprint-aware parallel execution adapter over ultrawork/subagents
+allowed-tools: Bash, Task, Read, Write, Edit, Glob, Grep
+argument-hint: <task-list-or-file> [--max=8]
+---
+
+# /pll - Blueprint-Aware Parallel Execution
+
+Execute Blueprint-shaped work through the current parallel engine layer while keeping durable lifecycle state on the shipped `wp blueprint` surface.
+
+`/pll` is an **operator adapter**, not a standalone runtime. It is the interactive half of the same shared execution model used by `wp blueprint exec`, so both surfaces should agree on launch spec shape, backend vocabulary, and runtime-state bridge semantics.
+
+It does three things:
+
+1. understands task dependencies well enough to preserve ordering
+2. keeps Blueprint lifecycle state honest via `wp blueprint start|task|finalize`
+3. delegates generic parallel fan-out to the active engine layer (`$ultrawork`, subagents, or equivalent host-native parallel lanes)
+
+**Arguments**: $ARGUMENTS
+
+## Input Formats
+
+### Format 1: Numbered list with optional dependencies
+
+```text
+1. Fix lint errors in packages/auth
+2. Fix lint errors in packages/utils
+3. Fix typecheck errors in packages/auth [depends: 1]
+4. Fix typecheck errors in packages/utils [depends: 2]
+5. Run tests for packages/auth [depends: 3]
+6. Run tests for packages/utils [depends: 4]
+```
+
+### Format 2: Simple comma-separated list
+
+```text
+/pll "fix auth lint, fix utils lint, update docs"
+```
+
+### Format 3: File path
+
+```text
+/pll tasks.md
+/pll blueprints/in-progress/my-blueprint/_overview.md
+```
+
+### Format 4: Conversation context
+
+```text
+/pll
+```
+
+If invoked without arguments, infer the nearest task list from the latest user context. If that context is anchored to a blueprint, apply Blueprint lifecycle rules.
+
+## Blueprint Lifecycle Rules
+
+When `/pll` is executing blueprint-backed work:
+
+- use `wp blueprint start <slug>` before execution begins
+- use `wp blueprint task start <slug> <taskId>` when a task starts
+- use `wp blueprint task block <slug> <taskId> --reason "<reason>"` when work is blocked
+- use `wp blueprint task complete <slug> <taskId>` only after the task's acceptance and verification actually pass
+- use `wp blueprint finalize <slug>` only after all tasks are validly done
+- do **not** use `wp blueprint move` as the normal execution primitive; it is recovery-only
+
+
+## Roadmap-Aware Lane Picking
+
+When invoked without an explicit task list, `/pll` should prefer the roadmap-shaped queue exposed by `wp blueprint list`:
+
+1. Read `wp blueprint list` first. `ROADMAP` rows are strategic parents; indented `CHILD` rows are tactical lanes.
+2. Choose the next `planned` child under an active (`in-progress` or `planned`) roadmap, respecting each child's `depends_on:` before fan-out.
+3. Use orphan blueprints only when no roadmap child is actionable. The `ORPHANS` group is fallback work, not the primary lane queue.
+4. Keep output-shape assumptions aligned with `ROADMAP ... children=N ...`, `CHILD ... parent=<roadmap>`, and `ORPHANS` rows from `wp blueprint list`.
+5. If the roadmap/child relationship looks inconsistent, run `wp audit roadmap-links` before dispatching lanes.
+
+## What `/pll` Owns
+
+- parsing lightweight dependency hints from task lists or blueprint task structure
+- prioritizing ready work using dependency order, critical-path pressure, and practical file-scope judgment
+- choosing a safe level of parallelism for the current runtime
+- keeping lifecycle state synchronized with actual execution
+- reporting progress, blockers, and verification outcomes
+
+## Shared Execution Model
+
+`/pll` and `wp blueprint exec` are two surfaces over one repo-owned model:
+
+- same Blueprint-backed launch spec
+- same backend names and policy hooks
+- same runtime-state bridge
+- same truthfulness rules for `start`, `task`, `block`, `complete`, `finalize`, `status`, `resume`, and `stop`
+
+If the model would diverge between the two surfaces, fix the contract instead of creating a `/pll`-only exception.
+
+## What `/pll` Does **NOT** Own
+
+- durable plan storage
+- standalone runner/runtime semantics
+- a guaranteed fixed number of active agents at all times
+- host-specific background-task APIs or polling contracts
+- replacing `$ultrawork` as the generic engine layer
+
+## Execution Protocol
+
+### Phase 1: Parse and Ground
+
+1. Parse the input into discrete tasks and dependency hints.
+2. If the source is a blueprint, read the blueprint task list and lifecycle state first.
+3. Reject obvious cycles or contradictory dependency declarations before execution begins.
+4. Produce a compact `/pll DAG Analysis` summary:
+
+```text
+/pll DAG Analysis
+  Total: 8 tasks
+  Ready now: 3
+  Critical path: Task 1.1 -> Task 2.1 -> Task 4.1
+  Suggested max parallelism: 3
+```
+
+### Phase 2: Delegate Through the Engine Layer
+
+1. Start with ready tasks only.
+2. Prioritize work that unblocks the longest chain or the most downstream tasks.
+3. Delegate independent work through the current engine layer:
+   - prefer `$ultrawork` / host-native subagents for true independent lanes
+   - keep test-heavy or build-heavy work at lower concurrency when needed
+4. Update Blueprint task state before and after execution so the durable artifact stays truthful.
+5. If a task fails, block it with a concrete reason and leave downstream work blocked unless explicitly safe to continue.
+
+### Phase 3: Verify and Report
+
+1. Run the task-level verification named by the task or blueprint.
+2. Run repo-level verification when the change scope justifies it.
+3. Report:
+   - completed tasks
+   - blocked tasks with reasons
+   - remaining ready tasks
+   - verification evidence
+
+## Concurrency Guidance
+
+| Scope | Guidance |
+| --- | --- |
+| Default | Use only as much parallelism as the current runtime and task mix safely support |
+| Test-heavy work | Reduce parallelism to avoid exhausting Vitest/CPU/memory |
+| Build-heavy work | Reduce parallelism to avoid CPU/memory spikes |
+| Mixed doc + code work | Run lightweight doc/admin work beside one heavier lane when safe |
+
+## Failure Handling
+
+| Event | Action |
+| --- | --- |
+| Task fails | Mark blocked with reason; do not mark complete |
+| Lifecycle mutation fails | Stop immediately rather than continuing with stale plan state |
+| Dependency cycle detected | Reject the run and ask for plan cleanup |
+| No ready tasks remain | Report blockers and the tasks they are waiting on |
+| File-scope conflict suspected | Serialize the conflicting tasks or merge them into one lane |
+
+## Examples
+
+```text
+/pll "lint auth, lint utils, typecheck auth [depends: 1], test auth [depends: 3]"
+
+/pll blueprints/in-progress/converge-omx-and-blueprint-planning-surfaces/_overview.md
+
+/pll
+```
+
+## Verification Discipline
+
+- Prefer per-file or per-package verification first.
+- Use `wp blueprint audit` and the task's named checks to prove state transitions.
+- Never treat orchestration progress as proof of correctness.

package/catalog/agent/commands/tph.md

@@ -0,0 +1,380 @@
+---
+description: Testing Philosophy Helper - Audit test quality, detect violations, and refactor tests to follow the integration-first, anti-mocking philosophy with a target 85% mutation score
+---
+
+# Testing Philosophy Helper (`/tph`)
+
+Enforce testing philosophy compliance: integration-first, anti-mocking, meaningful assertions.
+
+## Usage
+
+```bash
+just audit-tph                 # Run TPH audit script (over-mocking, file naming)
+just audit-tph-e2e             # Run TPH E2E audit (internal API calls, mocks, dry-run, coverage heuristics)
+/tph                           # Agent: audit all recent test files
+/tph <file>                    # Agent: audit specific test file
+/tph --check                   # Agent: check current changes only (git diff)
+```
+
+> Note: `just <recipe>` commands assume your repo uses the [just](https://github.com/casey/just) task runner. Substitute your own runner (`make`, `npm run`, etc.) where needed. The `wp run` abstraction layer is planned; until then, the referenced recipes are illustrative.
+
+## Implementation
+
+TPH enforcement is split across two layers:
+
+### Layer 1: GritQL Patterns (automatic, in `.grit/patterns/`)
+
+These run during lint and catch pattern-level violations:
+
+| Pattern                     | File                             | Detects                                            |
+| --------------------------- | -------------------------------- | -------------------------------------------------- |
+| `no_wewp_assertions`        | `no-weak-assertions.grit`        | `toBeTruthy()`, `toBeFalsy()`                      |
+| `no_tobefalsy`              | `no-tobefalsy.grit`              | `toBeFalsy()` (all chains)                         |
+| `no_tobedefined`            | `no-tobedefined.grit`            | `toBeDefined()`, `toBeUndefined()`, `toBeTypeOf()` |
+| `no_bare_spy_assertions`    | `no-bare-spy-assertions.grit`    | `toHaveBeenCalled()` without args                  |
+| `no_mock_calls_length_hack` | `no-mock-calls-length-hack.grit` | `spy.mock.calls.length > 0` workarounds            |
+| `no_internal_mocks`         | `no-internal-mocks.grit`         | `vi.mock('~/<internal>/*')` — your own modules     |
+
+### Layer 2: Audit Script (`just audit-tph`)
+
+Catches file-level violations GritQL can't express:
+
+- **Over-mocking** — files with >3 `vi.mock()` calls (WARNING)
+- **Internal mocks in unit tests** — `.test.ts` files mocking your own internal modules (ERROR)
+
+## What This Command Does
+
+1. **Audits test files** for philosophy violations:
+   - Over-mocking (>3 mocks for unit, any for integration)
+   - Mocking business logic (services, parsers, validators)
+   - Weak assertions (`toBeTruthy`, `toBeDefined`, `toBeTypeOf`, `toHaveProperty(key)` without value, `.length > 0`, partial `toMatch`/`toContain`)
+   - Wrong file type (integration test named `.test.ts`)
+   - Missing real dependencies
+
+2. **Reports violations** with:
+   - Severity (ERROR, WARNING, INFO)
+   - File paths and rule names
+   - Suggested fixes
+
+3. **Auto-fixes** (agent-assisted with `/tph --fix`):
+   - Rename `.test.ts` → `.integration.test.ts` if needed
+   - Remove service/business logic mocks
+   - Add temp file setup for integration tests
+   - Strengthen weak assertions
+   - Add missing test patterns
+
+## When to Use
+
+**Trigger `/tph` when:**
+
+- After implementing new tests (proactive quality check)
+- Before claiming work is "done" (quality gate)
+- When tests pass but you're not confident (smell test)
+- During PR review (catch violations early)
+- When refactoring existing tests (improvement)
+
+**Don't use for:**
+
+- Authoring Playwright/browser E2E tests (different rules apply)
+- Pure unit tests of formatting functions (mocking OK there)
+- Tests that already follow philosophy (waste of time)
+
+## Violation Detection Rules
+
+### E2E Guidelines & Evaluation (TPH-E2E)
+
+**Scope**: E2E tests only (`*.spec.ts` for Playwright and `*.e2e.ts` for Vitest end-to-end coverage). This is a quality audit, not authoring.
+
+**Rules**:
+
+1. **No internal handler calls** (must go through real HTTP/browser paths)
+2. **No mocks in E2E** (real services/boundaries only)
+3. **No dry-run mode** (must execute real behavior)
+4. **Coverage heuristics** (should exist):
+   - Error/invalid paths
+   - Mixed/partial/graceful degradation
+
+**Run**:
+
+```bash
+just audit-tph-e2e
+```
+
+### CRITICAL Violations (Must Fix)
+
+1. **Mocking Business Logic**
+
+   ```typescript
+   // BAD — CRITICAL
+   vi.mock('~/services/blueprint/local') // Service layer
+   vi.mock('../../lib/task-graph') // Business logic
+   vi.mock('../database') // Data layer
+   ```
+
+2. **Integration Test Named as Unit Test**
+
+   ```typescript
+   // BAD — CRITICAL: Uses services but named .test.ts
+   // <package>/src/commands/exec.test.ts
+   vi.mock('~/services/blueprint/local') // Integration, not unit!
+   ```
+
+3. **Zero Real Dependencies**
+
+   ```typescript
+   // BAD — CRITICAL: Everything mocked, tests nothing
+   vi.mock('~/services/blueprint/local')
+   vi.mock('../../lib/task-graph')
+   vi.mock('../../lib/parser')
+   // = Testing mocks, not code
+   ```
+
+4. **Missing E2E Coverage for Commands**
+
+   ```typescript
+   // BAD — CRITICAL: Only routing test, no actual execution
+   it('should recognize new command', async () => {
+     await actionFn('new', ['test'], { 'dry-run': true })
+     expect(exitSpy).not.toHaveBeenCalled()
+   })
+   // Missing: Test that actually creates files!
+   ```
+
+5. **Using dry-run in Integration Tests**
+
+   ```typescript
+   // BAD — CRITICAL: Not testing real behavior
+   await executeRun('test', { dryRun: true })
+   // Should: await executeRun('test', {}) and verify files created
+   ```
+
+6. **Inline YAML in Test Files**
+
+   ```typescript
+   // BAD — CRITICAL: Inline YAML string literals
+   const yaml = `entity: tasks\nfields:\n  - name: id\n    type: uuid`
+   writeFileSync(join(dir, 'tasks.yaml'), yaml)
+
+   // GOOD: Use __fixtures__ YAML files
+   const FIXTURES_DIR = join(import.meta.dirname, '__fixtures__')
+   cpSync(join(FIXTURES_DIR, 'tasks.yaml'), join(dir, 'tasks.yaml'))
+   ```
+
+   **Exception**: Intentionally malformed YAML (1-2 lines) for error-handling tests is OK.
+   **Exception**: Programmatic YAML via `yaml.stringify()` from objects is OK.
+
+### WARNING Violations (Should Fix)
+
+1. **Weak Assertions**
+
+   ```typescript
+   // BAD — Weak: Allows equivalent mutants
+   expect(result).toBeTruthy()
+   expect(result).toBeDefined()
+   expect(array).toHaveLength(3) // Without checking contents
+
+   // BAD — Weak: toHaveBeenCalled() workarounds
+   expect(spy.mock.calls.length).toBeGreaterThan(0)
+   expect(spy.mock.calls).toHaveLength(1)
+
+   // GOOD — Strong: Verify actual values
+   expect(result).toBe(true)
+   expect(result).toMatchObject({ status: 'success', count: 3 })
+   expect(array).toEqual(['item1', 'item2', 'item3'])
+
+   // GOOD — Strong: Verify actual call arguments
+   expect(spy).toHaveBeenCalledWith('expected', 'args')
+   expect(spy).toHaveBeenCalledTimes(1)
+   const output = spy.mock.calls.map((c) => c[0]).join('\n')
+   expect(output).toContain('expected content')
+   ```
+
+2. **Too Many Mocks (>3)**
+
+   ```typescript
+   // WARNING: Convert to integration test
+   vi.mock('./service1')
+   vi.mock('./service2')
+   vi.mock('./service3')
+   vi.mock('./service4')
+   // 4+ mocks = integration in disguise
+   ```
+
+3. **Testing Implementation**
+   ```typescript
+   // WARNING: Breaks on refactoring
+   expect(spy).toHaveBeenCalledWith(mockInput)
+   ```
+
+### INFO Violations (Consider Fixing)
+
+1. **No Integration Test Coverage**
+   - Pure unit tests exist but no integration tests
+   - May want to add `.integration.test.ts` for confidence
+
+2. **Inconsistent Naming**
+   - Test file doesn't match source file name
+
+3. **Incomplete E2E Coverage for Commands**
+   - Has routing test but missing:
+     - E2E test (actual execution)
+     - Error handling test
+     - Edge case tests
+   - Required for all commands/features
+
+4. **UX Testing Anti-Patterns** (Unit tests miss user experience)
+
+   ```typescript
+   // INFO: Unit test expects throw, but no E2E for graceful degradation
+   await expect(service.listItems()).rejects.toThrow('Invalid item')
+
+   // Missing E2E test: "should show valid items when some are invalid"
+   ```
+
+   **Patterns to detect**:
+   - `expect(...list...).rejects.toThrow()` without corresponding E2E test
+   - Only testing 100% valid or 100% invalid (no mixed scenarios)
+   - No E2E test for list/browse operations with mixed data
+   - Batch operations that don't test partial success
+
+   **Why this matters**: Unit tests verify implementation (throws on error), but miss UX requirements (users need to see valid items even if some are invalid).
+
+   **Example from production**:
+   - Unit test: `expect(listBlueprints()).rejects.toThrow()` — PASSES
+   - Production: Users can't see ANY blueprints if ONE is invalid — BAD UX
+   - E2E test would catch: "should show 5 valid blueprints even if 1 is corrupted"
+
+   **Action**: Add E2E tests for graceful degradation, error recovery, and mixed valid/invalid scenarios.
+
+## Example Output
+
+```
+Auditing: <package>/src/commands/exec.test.ts
+
+CRITICAL: Mocking business logic
+  Line 10: vi.mock('~/services/blueprint/local')
+  Rule: Never mock your own services/parsers/business logic
+  Fix: Convert to .integration.test.ts with real BlueprintService
+
+CRITICAL: Wrong file type
+  File: exec.test.ts (should be exec.integration.test.ts)
+  Reason: Uses services (BlueprintService, task-graph)
+  Fix: Rename to .integration.test.ts and remove mocks
+
+WARNING: Weak assertion
+  Line 63: expect(result).toMatchObject({ totalTasks: 2 })
+  Rule: Test specific values, not just shape
+  Fix: expect(result.totalTasks).toBe(2)
+
+Summary:
+  Critical: 2
+  Warning: 1
+  Info: 0
+
+Test quality: FAILING
+   Fix violations before claiming work is done.
+```
+
+## Auto-Fix Example
+
+```bash
+/tph --fix <package>/src/commands/exec.test.ts
+```
+
+**Before:**
+
+```typescript
+// exec.test.ts
+vi.mock('~/services/blueprint/local', () => ({
+  BlueprintService: class {
+    getBlueprint = mockGetBlueprint
+  },
+}))
+
+it('should show metrics', async () => {
+  mockGetBlueprint.mockResolvedValue(mockData)
+  const result = await executeExec('test', {})
+  expect(result).toBeTruthy()
+})
+```
+
+**After:**
+
+```typescript
+// exec.integration.test.ts
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+
+const tempDir = path.join(os.tmpdir(), `exec-test-${Date.now()}`)
+const blueprintsDir = path.join(tempDir, 'blueprints')
+
+beforeEach(() => {
+  process.cwd = () => tempDir
+})
+
+it('should calculate metrics from real blueprint', async () => {
+  // Create REAL blueprint file
+  const blueprint = `---
+type: blueprint
+status: in-progress
+---
+
+# Test Plan
+
+#### Task 1.1: First
+- [ ] Work
+`
+
+  const planPath = path.join(blueprintsDir, 'test', '_overview.md')
+  await mkdir(path.dirname(planPath), { recursive: true })
+  await writeFile(planPath, blueprint, 'utf8')
+
+  // Uses REAL BlueprintService, REAL parser
+  const result = await executeExec('test', {})
+
+  expect(result.totalTasks).toBe(1)
+  expect(result.waveCount).toBeGreaterThan(0)
+})
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true })
+})
+```
+
+## Integration with Workflow
+
+**Add to quality gates:**
+
+```bash
+# Before claiming work is done
+just test --package <name>   # Tests pass
+/tph --check                 # Test quality passes
+just qa                      # Full quality check
+```
+
+**Add to PR checklist:**
+
+- [ ] Tests pass (`just test`)
+- [ ] Test quality verified (`/tph --check`)
+- [ ] No philosophy violations
+
+## Related Commands
+
+- `/verify` - Post-implementation quality gate (includes test quality)
+- `/audit` - Comprehensive code quality audit
+- `just test --mutation --package <name>` - Mutation score verification
+
+## Philosophy Quick Reference
+
+| Rule                | Violation                            | Fix                                             |
+| ------------------- | ------------------------------------ | ----------------------------------------------- |
+| Integration-first   | Mock-heavy `.test.ts`                | Convert to `.integration.test.ts`, remove mocks |
+| Anti-mocking        | `vi.mock('~/<your-internal>/*')`     | Use real service with temp files/PGlite         |
+| Test behavior       | `expect(spy).toHaveBeenCalled()`     | Test actual outputs/state                       |
+| Specific assertions | `toBeTruthy()`                       | `toBe(expected)` or `toEqual(expected)`         |
+| No inline YAML      | `writeFileSync(path, \`yaml: ...\`)` | Use `__fixtures__/*.yaml` + `cpSync`            |
+| 90% mutation        | Wewp tests pass but mutants survive  | Add boundary tests, exact assertions            |
+
+## See Also
+
+- `.agent/skills/testing-philosophy/SKILL.md` - Full philosophy
+- Your repo's integration test for the blueprint service — example of the correct pattern

package/catalog/agent/commands/verify.md

@@ -0,0 +1,9 @@
+---
+description: 'Post-implementation quality gate that verifies work is actually done, cleans up legacy/backward-compat/dead-code garbage left behind, and refreshes affected docs. Use after implementing a feature or fix, before claiming done, or when finalizing a blueprint.'
+argument-hint: '<target> [--full] where target is: package|file|plan-slug|all'
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite
+---
+
+# Verify Command
+
+Canonical doc: @.agent/skills/verify/SKILL.md

package/catalog/agent/correlate.allow.yaml

@@ -0,0 +1,5 @@
+# .agent/correlate.allow.yaml — cross-org correlation allowlist
+# Both sides must allowlist for correlation to resolve.
+# See docs/cross-repo-correlation.md for the permission model.
+permits: []
+  # - acme-corp   # permit correlations with blueprints in acme-corp org

package/catalog/agent/guides/agent-guardrails.md

@@ -0,0 +1,116 @@
+---
+type: guide
+last_updated: 2026-04-22
+---
+
+# Agent Guardrails
+
+Current guardrails for agents working in a monorepo that uses webpresso.
+
+## Core Rule
+
+Edit authored source files. Do not teach or rely on repo paths that do not
+exist in the current checkout.
+
+Typical authored source in an webpresso-configured monorepo:
+
+- entity / schema truth lives in the declared schema directory (e.g.
+  `schema/*.yaml` or `entities/*.yaml`).
+- the supported checked-in customer / app roots are documented in your
+  repo's `docs/system/` (or equivalent).
+- generated artifacts (e.g. under `.generated/`) are outputs, not authored
+  source.
+
+Agents should verify the actual authored roots in the checkout before
+instructing the user to edit anything.
+
+## Source of Truth
+
+When changing repo-owned declarative inputs, prefer the current authored
+roots. A typical set (adapt to your repo):
+
+- `<repo>/config.yaml`
+- `<repo>/entities/`
+- `<repo>/workflows/`
+- `<repo>/ui/pages/`
+- `<repo>/endpoints/`
+- `<repo>/jobs/`
+- `blueprints/`
+- `tech-debt/`
+
+Optional supported checked-in roots may also be present:
+
+- `<repo>/actions/`
+- `<repo>/events/`
+- `<repo>/permissions/`
+- `<repo>/seeds/`
+- `<repo>/types/`
+- `<repo>/ui/navigation/`
+
+Use your repo's `docs/system/` pages as the canonical contract docs when a
+workflow or path is unclear.
+
+## Generated Files
+
+Do not manually edit generated payloads under output roots such as:
+
+- `.generated/`
+- `apps/docs-site/.generated/`
+- deploy-time generated config files
+
+Allowed exception:
+
+- a tracked `package.json` stub inside the generated output root is a
+  checked-in workspace package stub, not a generated payload.
+
+If generated artifacts need to change, edit the authored source and
+regenerate.
+
+## Regeneration Paths
+
+Use the narrowest regeneration path that matches the authored change. Typical
+recipe surface:
+
+```
+schema-check
+schema-compile
+schema-codegen
+schema-frontend
+```
+
+For docs-site generated content:
+
+```
+docs-build
+```
+
+Wire these to your task runner (`just`, `pnpm`, `turbo`, etc.). The rule
+that matters is that each authored-source change maps to exactly one
+regeneration command.
+
+## Expected Agent Behavior
+
+Agents working in this repo should:
+
+1. discover the current authored source file first
+2. edit source, not generated outputs
+3. regenerate only the artifacts implied by that source change
+4. verify the result with the relevant repo checks
+5. avoid reviving removed or legacy paths as if they were current workflow
+
+## Quick Checks
+
+Before giving workflow guidance, verify these assumptions:
+
+- the path exists in the current repo
+- the command exists in the current repo
+- the guidance matches your repo's contract docs for customer-facing roots
+
+If a historical doc or audit mentions missing paths, treat that as stale
+context, not current instruction.
+
+## Related Files
+
+- `.agent/rules/agent-guide.md`
+- `.agent/rules/generated-code-governance.md`
+- `.agent/rules/repo-restrictions.md`