@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/guidelines/e2e/playwright.md

@@ -0,0 +1,363 @@
+# Playwright E2E Guidelines
+
+> Best practices for writing end-to-end tests with Playwright.
+> Applies to all projects using Playwright (API, web, or hybrid).
+
+**Related Skills:** `playwright-testing`, `pest-testing`
+**Related Guidelines:** [php.md](../php/general.md)
+
+## Project Structure
+
+```
+tests/
+  e2e/
+    fixtures/           # Custom fixtures (auth, data, etc.)
+    pages/              # Page Object Models
+    specs/              # Test files grouped by feature
+      auth/
+        login.spec.ts
+        logout.spec.ts
+      dashboard/
+        overview.spec.ts
+    helpers/            # Shared utilities (API helpers, test data)
+playwright.config.ts    # Root config
+```
+
+- Group specs by **feature area**, not by page.
+- One spec file per user workflow or feature.
+- Keep Page Objects in `pages/`, fixtures in `fixtures/`.
+
+## Locator Strategy (Priority Order)
+
+| Priority | Locator | Example | When |
+|---|---|---|---|
+| 1 | **Role** | `getByRole('button', { name: 'Save' })` | Default — most accessible and resilient |
+| 2 | **Label** | `getByLabel('Email')` | Form inputs with labels |
+| 3 | **Placeholder** | `getByPlaceholder('Search...')` | Inputs without visible labels |
+| 4 | **Text** | `getByText('Welcome back')` | Static visible content |
+| 5 | **Test ID** | `getByTestId('submit-btn')` | When no semantic locator works |
+| 6 | **CSS/XPath** | `page.locator('.class')` | **Avoid** — brittle, breaks on UI changes |
+
+### Rules
+
+- **Always prefer semantic locators** (`getByRole`, `getByLabel`) over CSS.
+- Use `data-testid` as a stable fallback — add it to the component, not the test.
+- Chain and filter locators to narrow scope: `page.getByRole('listitem').filter({ hasText: 'Product' })`.
+- Never use auto-generated class names or dynamic IDs as selectors.
+
+## Assertions
+
+### Always use web-first assertions
+
+```ts
+// ✅ Auto-retrying — waits until condition is met
+await expect(page.getByText('Success')).toBeVisible()
+await expect(page.getByRole('list')).toHaveCount(5)
+await expect(page).toHaveURL('/dashboard')
+
+// ❌ Non-retrying — flaky
+const text = await page.textContent('.message')
+expect(text).toBe('Success')
+```
+
+### Use soft assertions for non-critical checks
+
+```ts
+await expect.soft(page.getByTestId('status')).toHaveText('Active')
+await expect.soft(page.getByTestId('count')).toHaveText('42')
+// Test continues even if soft assertions fail
+```
+
+## Waiting
+
+```ts
+// ✅ Wait for specific conditions
+await page.waitForResponse(resp => resp.url().includes('/api/users') && resp.status() === 200)
+await expect(page.getByText('Loaded')).toBeVisible()
+
+// ❌ Never use fixed timeouts
+await page.waitForTimeout(3000)
+```
+
+- **Never use `waitForTimeout()`** — use auto-retrying assertions or `waitForResponse`.
+- Trust Playwright's auto-waiting for actions (click, fill, etc.).
+- Use `networkidle` sparingly — prefer waiting for specific elements.
+
+## Page Object Model
+
+```ts
+// pages/LoginPage.ts
+import { type Page, type Locator } from '@playwright/test'
+
+export class LoginPage {
+  private readonly emailInput: Locator
+  private readonly passwordInput: Locator
+  private readonly submitButton: Locator
+
+  constructor(private readonly page: Page) {
+    this.emailInput = page.getByLabel('Email')
+    this.passwordInput = page.getByLabel('Password')
+    this.submitButton = page.getByRole('button', { name: 'Sign in' })
+  }
+
+  async goto(): Promise<void> {
+    await this.page.goto('/login')
+  }
+
+  async login(email: string, password: string): Promise<void> {
+    await this.emailInput.fill(email)
+    await this.passwordInput.fill(password)
+    await this.submitButton.click()
+  }
+}
+```
+
+### Rules
+
+- One Page Object per page or major component.
+- Locators are **defined in the constructor**, not inline in methods.
+- Methods represent **user actions**, not DOM manipulations.
+
+## Test Data Management
+
+### API-based setup (preferred)
+
+```ts
+test.beforeEach(async ({ request }) => {
+  // Create test data via API — faster than UI
+  await request.post('/api/test/seed', { data: { scenario: 'basic-customer' } })
+})
+
+test.afterEach(async ({ request }) => {
+  await request.post('/api/test/cleanup')
+})
+```
+
+### Rules
+
+- **Prefer API calls** over UI interactions for test data setup — faster and more reliable.
+- Use seeded test accounts with known credentials.
+- Never depend on data created by another test.
+- For database-backed apps: use a dedicated test database or transactional rollback.
+
+## Configuration
+
+### `playwright.config.ts` essentials
+
+```ts
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/e2e/specs',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { open: 'never' }],
+    ...(process.env.CI ? [['github'] as const] : []),
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+    { name: 'mobile-safari', use: { ...devices['iPhone 13'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+})
+```
+
+### Key settings
+
+| Setting | Local | CI | Why |
+|---|---|---|---|
+| `workers` | Auto (CPU cores) | `1` | Stability over speed in CI |
+| `retries` | `0` | `2` | Catch flakes in CI, fail fast locally |
+| `trace` | `off` | `on-first-retry` | Traces are expensive, only collect on failure |
+| `fullyParallel` | `true` | `true` | Tests must be isolated anyway |
+| `forbidOnly` | `false` | `true` | Prevent `.only` from reaching CI |
+
+## CI Integration (GitHub Actions)
+
+```yaml
+name: E2E Tests
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install chromium --with-deps
+      - run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 14
+```
+
+### Sharding for large suites
+
+```yaml
+strategy:
+  matrix:
+    shard: [1, 2, 3, 4]
+steps:
+  - run: npx playwright test --shard=${{ matrix.shard }}/4
+```
+
+- **Only install browsers you need** — `npx playwright install chromium --with-deps` not `npx playwright install`.
+- Use **Linux runners** in CI — cheapest and most stable.
+- Upload `playwright-report/` as artifact for failure debugging.
+- Use **sharding** when suite exceeds ~5 minutes.
+
+## Visual Regression
+
+```ts
+test('dashboard layout', async ({ page }) => {
+  await page.goto('/dashboard')
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    maxDiffPixelRatio: 0.01,
+    fullPage: true,
+  })
+})
+```
+
+- Store baselines in version control.
+- Update with `npx playwright test --update-snapshots`.
+- Pin OS + browser version in CI — visual diffs are platform-sensitive.
+- Use `maxDiffPixelRatio` or `maxDiffPixels` for tolerance.
+
+## Avoiding Flaky Tests
+
+| Problem | Solution |
+|---|---|
+| Element not ready | Use auto-retrying assertions (`toBeVisible`, `toHaveText`) |
+| Animation interference | Disable transitions: `page.addStyleTag({ content: '*, *::before, *::after { transition: none !important; animation: none !important; }' })` |
+| Network timing | Wait for specific responses, not arbitrary timeouts |
+| Test isolation | Fresh browser context per test (default) |
+| Shared state | Reset data via API before each test |
+| Date/time dependent | Use Playwright's clock API: `page.clock.setFixedTime()` |
+| Third-party resources | Mock with `page.route()` |
+
+## Debugging
+
+```bash
+# Headed mode — watch the browser
+npx playwright test --headed
+
+# Debug mode — step through with inspector
+npx playwright test --debug
+
+# Specific test
+npx playwright test -g "should login"
+
+# View HTML report
+npx playwright show-report
+
+# Generate tests interactively
+npx playwright codegen http://localhost:3000
+```
+
+## Handling Unfixable Tests
+
+When a test fails and the failure is in the **application** (not the test), use `test.fixme()`:
+
+```ts
+test.fixme('should display user avatar', async ({ page }) => {
+  // BUG: Avatar endpoint returns 404 since API v2 migration.
+  // Tracked in JIRA: GALA-1234
+  await page.goto('/profile')
+  await expect(page.getByRole('img', { name: 'Avatar' })).toBeVisible()
+})
+```
+
+### Rules
+
+- Use `test.fixme()` — **not** `test.skip()` — for tests that should work but don't due to app bugs.
+- Use `test.skip()` only for **environment-specific** skips (e.g., `test.skip(process.env.CI, 'requires local GPU')`).
+- Always add a **comment before the failing step** explaining the current behavior vs. expected.
+- Link to an issue tracker ticket if available.
+
+## Healer Workflow (Debugging Failing Tests)
+
+When tests fail, follow this systematic approach:
+
+1. **Run** — Execute the failing test(s) to see current errors
+2. **Debug** — Use `--debug` mode or trace viewer to inspect state at failure point
+3. **Investigate** — Check: selectors changed? Timing issue? Data dependency? App change?
+4. **Fix** — Update the test code (one fix at a time)
+5. **Verify** — Re-run the specific test to confirm the fix
+6. **Iterate** — Repeat until all tests pass
+
+### Common failure patterns
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| Element not found | Selector changed | Update locator, prefer semantic |
+| Timeout waiting for element | Slow load / missing element | Add `waitForResponse` or check if feature removed |
+| Assertion mismatch | App behavior changed | Update expected value or test logic |
+| Intermittent pass/fail | Race condition | Add proper waits, remove shared state |
+| Works locally, fails in CI | Environment difference | Check `baseURL`, headless mode, viewport |
+
+### When to give up
+
+If a test **consistently fails** despite correct test logic (confirmed by manual inspection):
+- Mark with `test.fixme()` + detailed comment
+- File a bug ticket for the underlying application issue
+- Move on — don't spend more than 3 attempts fixing a single test
+
+## Agent-Driven Test Pipeline
+
+For AI-assisted E2E workflows, follow this pipeline:
+
+### Phase 1: Plan
+- Explore the application (navigate pages, identify flows)
+- Document test scenarios in Markdown with numbered steps
+- Include: happy path, edge cases, error handling, validation
+
+### Phase 2: Generate
+- Convert Markdown plans into Playwright test files
+- Follow all conventions from this guideline
+- One test file per scenario group
+- Add step comments before each action
+
+### Phase 3: Heal
+- Run all generated tests
+- Debug failures systematically (see Healer Workflow above)
+- Fix or mark as `test.fixme()` if the app is broken
+- Verify all fixes, iterate until green
+
+## Do NOT
+
+- Do NOT use `page.waitForTimeout()` — always wait for a condition.
+- Do NOT use CSS selectors when `getByRole`/`getByLabel`/`getByTestId` work.
+- Do NOT put assertions in Page Objects — only in test files.
+- Do NOT share state between tests — each test must be independent.
+- Do NOT hardcode URLs — use `baseURL` from config.
+- Do NOT test third-party dependencies — mock external services with `page.route()`.
+- Do NOT commit `.only` — use `forbidOnly: !!process.env.CI` to prevent this.
+- Do NOT use `networkidle` as default `waitUntil` — it's slow and unreliable.
+- Do NOT skip writing `data-testid` when no semantic locator is available.
+- Do NOT use deprecated APIs — check Playwright changelog for removed features.

package/dist/agent-src/guidelines/gtm-handoff.md

@@ -0,0 +1,114 @@
+# GTM Handoff
+
+Wing-3-specific prose for the three load-bearing senior-skill chains
+in the GTM + Growth cluster. The mechanical contract — initiator →
+delegated(input) → output-artifact, lint rules, worktree boundary —
+lives in [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md).
+The cross-wing routing prose (when to hand off at all, L4 / C8
+boundary, decision tree) lives in
+[`docs/guidelines/cross-role-handoff.md`](cross-role-handoff.md).
+This guideline covers **what crosses each Wing-3 boundary**, **what
+the typed artifact looks like**, and **who owns the failure mode
+when the chain breaks**.
+
+Cycle / dangling / tier-mismatch enforcement is not duplicated here —
+The `lint-handoffs` task (per cross-wing-handoff § 4) is the mechanical
+gate.
+
+## Chain 1 — brand → channel
+
+Five-step chain that turns a category point-of-view into a shipped
+funnel of channel artifacts. CMO cluster owns every step.
+
+```
+positioning-strategy (H1)
+  → messaging-architecture (H2)
+    → gtm-launch (H3)
+      → editorial-calendar (H4)
+        → content-funnel-design (H5)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| H1 → H2 | Category framing + opposable-positioning audit locked. | `positioning-statement.md` — "we are X for Y, not Z" + point-of-view paragraph + opposable-positioning matrix. | H1 owns drift: if H2 cannot derive proofs from the statement, H1's POV is too soft. |
+| H2 → H3 | Primary message + supporting proofs + audience-by-message matrix locked. | `messaging-stack.md` — primary message, three supporting proofs, audience-message matrix, narrative beats. | H2 owns drift: if H3's wave-by-wave narrative drifts, the proofs were the wrong shape. |
+| H3 → H4 | Launch sequencing (alpha → beta → GA) + audience-wave logic locked; engineering-readiness signals attached. | `launch-plan.md` — wave list, narrative beats per wave, dependency map, go / no-go signals. | H3 owns drift: missing engineering-readiness signal = H3 shipped a plan that cannot land. |
+| H4 → H5 | Cadence cognition (evergreen vs campaign vs reactive) + beat-mapping locked. | `editorial-calendar.md` — cadence per audience, beat-to-asset map, content-debt ledger. | H4 owns drift: a calendar that does not map beats to funnel stages cannot be designed against. |
+| H5 self-closes | Funnel-stage-to-content-shape mapping + conversion-pathway design locked. | `content-funnel.md` — per-stage asset shapes, conversion pathways, leading indicators. | H5 owns drift: any stage without a content shape is a broken funnel hand-back to H4. |
+
+H5 also **composes** `funnel-analysis` (H14, Chain 3) — the funnel
+diagnostic feeds the conversion-pathway design without H5 absorbing
+funnel-diagnostic cognition.
+
+## Chain 2 — discovery → pipeline
+
+Five-step chain that turns customer research into a forecast-able
+pipeline. Spans the Discovery → RevOps boundary inside Wing 3 and
+hands the forecast call back to the Wing-4 finance-partner.
+
+```
+customer-research (L1, shipped)
+  → ideal-customer-profile artifact
+    → pipeline-strategy (H8)
+      → deal-qualification-meddic (H9)
+        → forecast-accuracy (H10) → forecasting (Wing-4 O2)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| `customer-research` → H8 | Switch-event interviews + JTBD framing complete; ICP synthesized from verbatims. | `icp.md` — segment definition, switch events, JTBD frame, anti-ICP. | `customer-research` owns drift: an ICP without anti-ICP boundaries leaks into H8 stage definitions. |
+| H8 → H9 | Stage definitions + conversion-rate targets + coverage reasoning locked. | `pipeline-shape.md` — stage list, per-stage conversion target, coverage ratio, leak map. | H8 owns drift: stages H9 cannot disqualify against = H8 stage definitions were not orthogonal. |
+| H9 → H10 | MEDDIC qualification rubric + disqualification heuristics locked. | `qualification-rubric.md` — MEDDIC fields per stage, disqualification triggers, champion-test. | H9 owns drift: forecasts that ignore disqualification heuristics inflate; H9 owns the rubric. |
+| H10 → Wing-4 O2 | Forecast call constructed (commit / best-case / pipeline) against the `forecast-construction-shape` ADR. | `forecast-band.json` — commit value, best-case value, pipeline value, confidence band, retro signature. | **Interface contract owned by O2** (per cross-wing-handoff § 5 / W4 chain): if the ADR drifts, O2 breaks the contract, not H10. |
+
+H10's parallel-development rule (starts after O2-interface ≥ 100 %,
+runs in parallel with O2 implementation) is recorded in the roadmap
+H10 entry and the contract — not duplicated here.
+
+## Chain 3 — funnel → retention
+
+Six-step chain that turns funnel diagnostics into a retention and
+expansion system. Growth PM cluster owns the first three steps,
+Customer Success cluster owns the last three; the H15 → H12 boundary
+crosses the cluster line inside Wing 3.
+
+```
+funnel-analysis (H14)
+  → activation-design (H16)
+    → onboarding-design (H11)
+      → retention-loops (H15)
+        → churn-prevention (H12)
+          → expansion-playbook (H13)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| H14 → H16 | Funnel-stage diagnostics + leaky-bucket-vs-growth-loop classification + leading-indicator selection locked. | `funnel-diagnostic.md` — per-stage drop-off, loop classification, leading indicators, cohort behavior. | H14 owns drift: an unselected leading indicator leaves H16 without an aha-moment signal. |
+| H16 → H11 | Aha-moment definition + activation-event selection + activation-funnel construction locked. | `activation-spec.md` — aha-moment, activation event, activation-funnel stages, leading-vs-lagging indicators. | H16 owns drift: an activation event H11 cannot instrument is the wrong event. |
+| H11 → H15 | Time-to-first-value reasoning + milestone design + friction audit locked. | `onboarding-flow.md` — milestone list, time-to-value target, friction-audit findings, drop-off diagnosis. | H11 owns drift: milestones without retention hooks force H15 to re-derive habit cognition. |
+| H15 → H12 | Habit-formation reasoning + trigger-action-reward design + loop classification locked. | `retention-loop.md` — trigger / action / reward triple, loop classification, network-vs-single-user signal. | H15 owns drift: a loop that does not surface a health signal leaves H12 without an early warning. |
+| H12 → H13 | Health-score signal design + churn-cause classification + early-warning loop locked. | `churn-signals.md` — health-score schema, churn-cause buckets, early-warning thresholds. | H12 owns drift: a health signal H13 cannot read against expansion triggers blocks NRR cognition. Also feeds **back to Wing-4 forecasting** per the cross-skill map. |
+| H13 self-closes | Account-expansion patterns + upsell-vs-cross-sell reasoning + NRR cognition locked. | `expansion-playbook.md` — expansion patterns, trigger signals, NRR levers. | H13 owns drift: expansion triggers that ignore churn signals double-count growth. |
+
+## Reading the failure-mode column
+
+The column answers one question: **when a downstream skill cannot
+do its job, which upstream skill rewrites its artifact?** The owner
+is the **upstream** skill, not the consumer — drift is always a
+producer-side fix. This mirrors the W4 / W3 forecasting chain in
+the contract (O2 owns the interface; H10 only consumes it).
+
+## See also
+
+- [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md)
+  — typed-handoff mechanical contract; the `lint-handoffs` task enforces
+  cycles, dangling references, and tier mismatches over the graph.
+- [`docs/guidelines/cross-role-handoff.md`](cross-role-handoff.md)
+  — when to hand off at all, how to phrase the routing, L4 / C8
+  boundary.
+- [`docs/contracts/context-spine.md`](../contracts/context-spine.md)
+  § Wing-3 slots — `channel-stage`, `funnel-stage`,
+  `customer-segment`; every chain step opts into ≥ 1 slot.
+- `agents/roadmaps/` § Block H (archived after merge) — the
+  sixteen H-skills this guideline maps; pending skills appear here
+  as backtick slugs until shipped.

package/dist/agent-src/guidelines/monorepo-antipatterns.md

@@ -0,0 +1,141 @@
+# Monorepo anti-patterns — the diff-detectable set
+
+Task-graph mistakes a reviewer can catch by **reading a diff**, with no build
+run and no repository checked out. That is the whole selection criterion: a
+review judge sees a patch, not a running pipeline, so a rule it cannot evaluate
+from the patch is not a rule it can enforce.
+
+> **Own analysis, corroboration outstanding.** The six rows below describe
+> publicly documented behaviour of Turborepo and Nx and are stated from that
+> behaviour, not adopted from a third-party artefact — so no
+> `provenance/borrows.jsonl` entry backs them, and none should be read into
+> them. The roadmap that commissioned this file recorded specific source line
+> numbers in an external MIT-licensed reference; that reference is **not
+> reachable from this checkout** (it was never cloned here, and the consumed
+> inbox copy carrying the real identifiers is gitignored), so those line numbers
+> could not be re-read and are deliberately **not** reproduced as citations. A
+> citation nobody in this tree can follow is worse than an honest own-analysis
+> label. See § Not harvested for what that leaves open.
+
+## The six rows
+
+### 1. A root script that bypasses the task runner
+
+```jsonc
+// root package.json — WRONG
+{ "scripts": { "build": "tsc -b packages/ui && vite build apps/web" } }
+```
+
+The runner exists to know the graph, cache the results, and parallelise. A root
+script that invokes the underlying tools directly gets none of that, and — worse
+— becomes a second, divergent definition of what "build" means. Route through
+the runner: `"build": "turbo run build"`.
+
+**In a diff:** a root `scripts` entry naming a compiler, bundler, or test runner
+directly instead of `turbo run` / `nx run-many`.
+
+### 2. `prebuild` that builds a sibling
+
+```jsonc
+// packages/ui/package.json — WRONG
+{ "scripts": { "prebuild": "cd ../tokens && npm run build" } }
+```
+
+npm lifecycle hooks are invisible to the task runner. The dependency is real but
+undeclared, so the runner may build the two in the wrong order, in parallel, or
+skip the sibling entirely on a cache hit. Express it as a dependency
+(`dependsOn: ["^build"]` plus a real `workspace:` dependency) so the graph
+carries it.
+
+**In a diff:** a `pre*` / `post*` script containing `cd ..`, a sibling path, or
+another workspace's name.
+
+### 3. `&&`-chained runner tasks
+
+```jsonc
+{ "scripts": { "ci": "turbo run lint && turbo run test && turbo run build" } }
+```
+
+Three sequential invocations, each with its own graph walk, forcing full
+serialisation and discarding the parallelism the runner would have found. It
+also makes the cache less effective, because each invocation is scoped to one
+task. Pass the tasks together: `turbo run lint test build`.
+
+**In a diff:** two or more `turbo run` / `nx run-many` invocations joined by
+`&&` in one script.
+
+### 4. Shared code inside `apps/`
+
+```
+apps/web/src/shared/format-currency.ts   ← imported by apps/admin
+```
+
+`apps/*` are leaves: deployable things nothing else depends on. The moment a
+second app imports from the first, the two are coupled with no declared edge,
+the affected-set calculation is wrong, and neither app can be built or released
+alone. Shared code belongs in a `packages/*` workspace with a real dependency
+declared ([`workspace-link`](../skills/workspace-link/SKILL.md)).
+
+**In a diff:** an import whose specifier reaches into `apps/<other>/`, or a new
+`shared/` `common/` `utils/` directory added under `apps/*`.
+
+### 5. `../` traversal in a task's `inputs`
+
+```jsonc
+// turbo.json — WRONG
+{ "tasks": { "build": { "inputs": ["src/**", "../tokens/src/**"] } } }
+```
+
+`inputs` are scoped to the workspace on purpose: they define that task's cache
+key. Reaching outside it makes the key depend on files the runner does not
+consider part of this task, which produces both false cache hits (the sibling
+changed in a way the key did not capture) and false misses. The sibling's output
+should be an input *because it is a declared dependency*, not because a glob
+walked up the tree.
+
+**In a diff:** a `../` segment inside `inputs`, `outputs`, or a task-scoped glob
+in `turbo.json`.
+
+### 6. A file-producing task with no `outputs`
+
+```jsonc
+{ "tasks": { "build": { "dependsOn": ["^build"] } } }   // writes dist/, declares nothing
+```
+
+With no `outputs`, the runner caches the task's *logs* and not its artefacts. A
+cache hit then restores nothing, so the next task in the chain runs against a
+missing or stale `dist/` — and the failure is intermittent, because it only
+appears on a hit. Declare what the task writes: `"outputs": ["dist/**"]`.
+
+**In a diff:** a task whose command runs a compiler or bundler while its config
+block carries no `outputs` key.
+
+## Not harvested
+
+The external reference this file was commissioned from carries a substantially
+longer anti-pattern list. The rows above are the ones whose violation is visible
+in a patch; the classes below were deliberately left out, each for a reason that
+is a property of the *check*, not of the advice:
+
+| Class not harvested | Why it cannot be a diff rule |
+|---|---|
+| Cache hit-rate and timing regressions | Needs two runs to compare; a diff has no runtime. |
+| Task-graph cycles | Requires resolving the whole graph, not reading one file. |
+| Over-broad `inputs` causing cache misses | "Too broad" is a judgement against observed hit rates. |
+| Remote-cache and CI configuration mistakes | Lives in CI/runner settings, not in the reviewed diff. |
+| Dependency-order races that only appear under `--parallel` | Needs a running build to observe. |
+| Environment-variable declarations missing from the cache key | Detectable only once a build produces a wrong artefact. |
+
+**Honest limit on this table:** it enumerates *classes* reasoned about from what
+such a list contains, not a row-by-row disposition of the source — which, per
+the note above, could not be opened here. So it does not establish that every
+source row is accounted for. Closing that needs the reference reachable in a
+checkout; until then this section states what was decided and on what basis,
+rather than implying a completeness it does not have.
+
+## See also
+
+- [`monorepo-workspace`](../skills/monorepo-workspace/SKILL.md) — read the graph and the task list before judging either.
+- [`workspace-link`](../skills/workspace-link/SKILL.md) — the `workspace:` declaration rows 2 and 4 both come back to.
+- [`blast-radius-analyzer`](../skills/blast-radius-analyzer/SKILL.md) — § Monorepo, for the affected set of an edit.
+- [`design-antipatterns.md`](design-antipatterns.md) — sibling diff-detectable catalog for a different surface.