@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/existence-question-verdicts.md

@@ -0,0 +1,80 @@
+# The existence question — its verdict set, its cost, and why it is not TDD
+
+Depth for [`improve-before-implement`](../../rules/improve-before-implement.md)
+§ The solution-size ladder, migrated out of
+[`agent-interaction-and-decision-quality`](agent-interaction-and-decision-quality.md)
+§ 8b.
+
+**Why it moved.** That guideline crossed `check_depth_budget`'s 16,000-character
+ceiling when this depth landed in it, becoming a fifth over-ceiling file against
+a baseline of four. The ratchet turns one way, so the fix is extraction rather
+than a raised baseline — and these three sections are the natural unit: they
+answer what the ladder RETURNS, what it costs, and which cluster it does not
+belong to, none of which the surrounding interaction guideline needs in order to
+be read.
+
+The ladder itself — the rungs, the shape axis and their precedence — stays at
+§ 8b-ladder / 8b-shape / 8b-precedence, because the rule routes there.
+
+#### 8b-verdict. The verdict set, and what `new` owes
+
+The ladder's answer is a **named verdict, never a yes/no**:
+
+| verdict | meaning |
+|---|---|
+| `reuse` | the existing thing carries the requirement as-is |
+| `extract` | it carries it once a shared part is pulled out |
+| `refactor` | it carries it once reshaped, same responsibility |
+| `extend` | it carries it with an added, non-distorting case |
+| `migrate` | it should carry it, and the move is the work |
+| `new` | nothing carries it, and the search that establishes that is the evidence |
+
+**`new` owes negative evidence** — the closest existing candidate **by name and
+path**, and why it does not carry the requirement. *"Nothing similar exists"*
+naming no candidate is an unrun search, not an answer, and it is the shape this
+verdict set exists to make visible.
+
+Two clauses hold the set honest, and both cut against reading it as a ranking:
+
+- **The order is a thinking preference, not a ranking.** A `new` after a real
+  search beats an `extend` that bends a helper out of shape. Preferring reuse is
+  not preferring reuse *at any cost*.
+- **Textual similarity alone is never grounds for an abstraction.** Two blocks
+  that read alike and change for different reasons are two blocks — the
+  per-class bars are in [`abstraction-thresholds`](../abstraction-thresholds.md).
+
+**Reach the verdict with the engine, not a fresh grep protocol.** `agent-config
+code-graph query` and `code-graph affected`;
+[`external-code-graph-interop`](../../rules/external-code-graph-interop.md)
+already mandates query-before-grep and names grep the fallback, so a second
+search specification here would contradict it rather than add to it.
+
+#### 8b-cheap. Why the exclusions buy the checks and never the question
+
+The rule excludes bug fixes, config changes, user-fenced tasks and trivial
+changes from the **three heavy checks**. The one cheap question — *does this
+already exist in the tree* — fires on all four rows anyway.
+
+The reason is empirical rather than tidy: **bug fixes and renames re-add an
+existing helper more often than features do**, because the author is inside one
+file and reaching for something small. Switching the reuse rung off there
+switches it off where it pays most.
+
+Cheap means cheap, on the [`ui-audit-gate`](../../rules/ui-audit-gate.md)
+precedent: one `code-graph query`, one named verdict, no interview.
+
+**The skip is decidable from the diff alone** — ≤ 1 file, ≤ 5 changed lines, no
+new symbol, no new dependency. A typo satisfies all four with no state to
+consult; an added symbol never does.
+
+#### 8b-routing. Why this is not routed through the TDD cluster
+
+Two source proposals put the existence question in `/tdd`'s design mode, as the
+one point every behaviour passes through. **It cannot live there, and the reason
+is delivery rather than design:**
+`src/domains/engineering-base/tdd/command.md` carries `visibility: internal` and
+`disable-model-invocation: true`, so **a consumer cannot reach it.** The routing
+is undeliverable, not merely unwanted.
+
+Recorded here so the next author does not re-derive the proposal and re-propose
+it.

package/dist/agent-src/guidelines/agent-infra/failure-signatures.md

@@ -0,0 +1,70 @@
+# Failure signatures — symptom → likely cause → first check
+
+A file-first lookup the [`systematic-debugging`](../../skills/systematic-debugging/SKILL.md)
+skill reads when a failure shows a recognisable signature. It does **not**
+replace the 6-phase loop — it shortcuts **Phase 2 (Isolate)** by pointing at the
+*first* check for a known shape, so you stop guessing and start with the highest-
+probability cause.
+
+> File-first by design (council 2026-06-15): kept as a reference table the skill
+> reads, **not** hardcoded into the skill body — so it grows without bloating the
+> always-loaded skill and stays one edit away from current.
+
+## Lookup
+
+| ID | Signature (what you see) | Likely cause | First check |
+|---|---|---|---|
+| `tool-loop` | **Tool/agent loop** — same tool called >2× with near-identical args, no progress | Missing stop condition; reading without acting; ambiguous state | Stop. State the hypothesis in one line. Act or ask — do not re-read. (`context-hygiene` 15/25 rule) |
+| `rate-limited` | **HTTP 429 / "rate limit" / "quota"** | Too-frequent calls; shared quota; missing backoff | Inspect response headers (`Retry-After`, `X-RateLimit-*`); add exponential backoff; check if a loop is firing the calls |
+| `connection-refused` | **`ECONNREFUSED` / connection refused** | Service not up; wrong host/port; container not started | Is the service running? (`docker compose ps`, health endpoint); is the port right? (`lsof -i :PORT`); is it bound to `127.0.0.1` vs `0.0.0.0`? |
+| `path-not-found` | **`ENOENT` / "no such file or directory"** | Wrong cwd; path relative vs absolute; file not generated yet | Print the *resolved absolute* path; check cwd; confirm a prior step actually wrote the file |
+| `hang` | **Timeout / hang** | Blocking I/O; deadlock; awaiting a condition that never holds | What is it waiting on? Add a log right before the blocking call; bound the wait; check for a missing `await`/`return` |
+| `out-of-memory` | **`OOM` / killed (137) / heap out of memory** | Unbounded collection; loading all rows; leak in a loop | What grows per iteration? Stream/paginate instead of loading all; check `--max-old-space-size` only after finding the growth |
+| `permission-denied` | **`EACCES` / permission denied** | Wrong file mode; running as wrong user; read-only mount | `ls -l` the target; check the process user; is the path a read-only volume? |
+| `order-dependent-test` | **Flaky test (passes alone, fails in suite)** | Shared state; order dependence; real clock/random; unawaited async | Run the test in isolation vs in suite; look for shared fixtures, global state, `Date.now()`/random, missing `await` |
+| `local-ci-drift` | **Works locally, fails in CI** | Env/config drift; missing service; absent secret; path/case sensitivity | Diff env (`printenv`); is the service/secret present in CI? Linux is case-sensitive — check filename casing |
+| `race` | **Intermittent / "sometimes"** | Race; timing; network; non-deterministic order | Reproduce with condition-based waiting, not fixed sleeps (`systematic-debugging` § Condition-based waiting); log timestamps |
+| `stale-capability-claim` | **Budget exhausted plus repeated attempts at a tool that is not available** | A capability the session claimed for itself instead of resolving — the council, a hook slot, a subagent primitive, an MCP server assumed present | Ask the live verb, not the tree: `agent-config hooks:status` for slot bindings, `agent-config routing:doctor` for per-field capability **provenance** (`registry` / `live-probe` / `default`), `agent-config council:status` for council availability. A `false` from `default` records that nobody answered, not that the host cannot |
+
+### Naming convention for IDs
+
+An id is a short kebab handle so a signature can be **cited by name** — the
+first column was prose, so nothing could reference a row.
+
+One rule governs new ids: **where a row's signature is a stable string the
+tooling already prints, the id is that string verbatim** rather than a kebab
+synonym. `skill_linter.ts` emits a closed set of `Issue` codes —
+`missing_section`, `missing_conditional_section`, `invalid_execution_handler` —
+and a row about one of those is looked up by the code the reader just saw in the
+output. No current row is of that class; the convention is stated for the next
+one, so the table does not accumulate two names for the same failure.
+
+## Discrimination drills
+
+A row's "first check" is only worth following if the documented signature is what
+actually appears. Each drill breaks the named layer and asserts the documented
+symptom — run it once when you doubt a row, or when adding one. They are text a
+human runs; nothing here is a CI gate.
+
+| ID | Drill — break this, expect that |
+|---|---|
+| `tool-loop` | Ask for a fact that is genuinely absent from the tree (a config key nothing defines). Expect repeated searches with shrinking variation and no edit — that shape, not an error message, is the signature. |
+| `rate-limited` | Fire the provider's own rate limit with a tight loop against a cheap endpoint. Expect `429` **plus** `Retry-After`; a `429` with no such header is a different failure (a gateway, not the API). |
+| `connection-refused` | Stop the service and call it (`docker compose stop <svc>`). Expect `ECONNREFUSED` immediately. If it hangs instead, the host resolves but nothing listens — that is `hang`, not this row. |
+| `path-not-found` | Run a path-taking script from a different cwd. Expect `ENOENT` naming a path that is *almost* right — the near-miss is the tell that the path is relative, not missing. |
+| `hang` | `await` a promise nothing resolves. Expect no output and no exit, distinguishable from `race` by being 100% reproducible. |
+| `out-of-memory` | Accumulate rows in an array inside a loop over a large fixture. Expect the heap message and exit 137 — and note that the reported line is where allocation failed, not where the growth is. |
+| `permission-denied` | `chmod 000` a fixture and read it. Expect `EACCES`, not `ENOENT` — confusing the two sends you looking for a missing file that is right there. |
+| `order-dependent-test` | Add a module-level mutable to two tests in one file. Expect green alone, red in suite. Reversing the file order should move the failure — if it does not, the cause is shared *external* state, not order. |
+| `local-ci-drift` | Rename a fixture's casing (`Foo.ts` → `foo.ts`) and import the old name. Expect green on macOS, red on Linux CI. The generalisation: anything the local filesystem is lenient about. |
+| `race` | Replace a condition-based wait with a fixed `sleep` shorter than the operation. Expect intermittent failure whose rate moves with machine load — load-sensitivity is what separates this from `order-dependent-test`. |
+| `stale-capability-claim` | Assert a capability without asking for it, then compare against the live verb. `agent-config routing:doctor` prints provenance per field; a field whose provenance is `default` was never established by anything — which is exactly the state a confident self-claim is indistinguishable from. |
+
+## How to use
+
+1. Match the symptom to a signature above.
+2. Run the **first check** — it is the highest-probability isolation step, not a fix.
+3. If it confirms the cause → fix + add a regression test. If not → fall back to
+   the full `systematic-debugging` loop from Phase 1.
+
+No signature matches → this table earned nothing; debug from first principles.

package/dist/agent-src/guidelines/agent-infra/false-green.md

@@ -0,0 +1,233 @@
+# False Green — the ways a passing result can be wrong here
+
+> Eleven failure modes, each with the detection command that distinguishes "found nothing" from "looked at nothing". Every one is drawn from this repository's own history, not from a generic checklist.
+
+_Origin: `road-to-skill-ecosystem-gate-integrity` Phase 3. The recurring shape is not that a gate reports a wrong finding — it is that a gate reports **no** finding for a reason unrelated to the property it guards, and no output distinguishes the two cases._
+
+## The catalogue
+
+### 1. Dead scan root
+
+The gate walks a directory that moved or was deleted. Zero units, zero findings,
+exit 0, green checkmark. Fourteen gates in this tree were in this state
+simultaneously after a container move; their own output said `0 file(s) scanned`
+and nothing asserted on the number.
+
+```bash
+./scripts-run src/scripts/<gate> | grep -E '^scanned: '   # 0, or absent entirely
+./scripts-run src/scripts/sweep_dead_scan_roots
+```
+
+**Structural fix:** `assertScanned` from `_lib/scan_scope.ts`. A gate that read
+nothing has not passed.
+
+### 2. Planned-but-never-judged targets
+
+The root is alive and the corpus is real, but the loop `continue`s past most of
+it on unwritten conditions. The published count says "enumerated", the reader
+hears "checked". `lint_framework_leakage` published 438 while judging 368.
+
+```bash
+./scripts-run src/scripts/<gate> | grep 'ledger:'   # scanned=N planned=M — compare N and M
+```
+
+**Structural fix:** `_lib/gate_ledger.ts`. Every planned target reaches exactly
+one terminal outcome, and the skip codes are counted per reason.
+
+### 3. Allowlist growth
+
+The gate is honest, the corpus is real, and the finding was suppressed. Count-
+based ratchets cannot see swap-one-out-add-one-in: remove a real entry, add a
+fresh suppression, the number is identical and the estate moved backwards.
+
+```bash
+./scripts-run src/scripts/check_suppression_hygiene     # entry SETS vs the base ref
+git diff origin/main -- 'src/scripts/*allowlist*.json' 'src/config/*baselines*.json'
+```
+
+**Structural fix:** `_lib/ratchet_base_ref.ts` — compare entry sets against
+`git show <baseRef>:<path>`, the one reading of the baseline the change under
+review cannot rewrite.
+
+### 4. Ratchet-entry deletion
+
+Subtler than growth: deleting a baseline entry whose `count` is 0 is **weaker**
+than leaving it, because the absence of an entry means "unbaselined" and an
+unbaselined gate's `ok` flips to `actual === 0` with no recorded intent. Harden
+first, then delete, and pin the absence.
+
+```bash
+git diff origin/main -- src/config/gate-violation-baselines.json | grep '^-'
+```
+
+### 5. Threshold re-anchoring
+
+The gate still runs, the corpus is real, and the bar moved. A lowered floor and
+a genuine improvement look identical in the exit code.
+
+```bash
+git diff origin/main -- src/config/gate-coverage.yml | grep -E '^[-+].*min_scanned'
+git diff origin/main -- 'src/config/*budget*.json'
+```
+
+**Discriminator:** a legitimate ratchet lowers *severity* while keeping *reach*;
+threshold-lowering reduces reach. Ask which one the diff does.
+
+### 6. Suppression sweep
+
+Not one entry — twenty. Allowlist growth past ~20 entries in a session is the
+signal that the linter (or the content) is wrong, not that the list is short by
+twenty. The tool-call guard blocks past that count; the honest response is to
+fix the gate's shape.
+
+```bash
+./scripts-run src/scripts/check_suppression_hygiene | grep 'entry(ies)'
+```
+
+### 7. Crashed gate read as passing gate
+
+A gate that throws is not a gate that passed, but an aggregator that only
+inspects exit codes cannot tell an exception from a clean run when the harness
+swallows it. Three of this repository's recorded traps are estate invalidation
+misreported as a per-gate red, or the reverse.
+
+```bash
+./scripts-run src/scripts/<gate>; echo "EXIT=$?"     # capture BEFORE any $( )
+```
+
+**Structural fix:** capture `EXIT=$?` on the line immediately after the command,
+never after a command substitution; and fail closed when a registered gate
+reports a null or missing verdict.
+
+### 8. A derived page reporting an unmeasured dimension
+
+The generator has no data for a category and renders a `0`, or worse a computed
+share, which reads as a measurement. The always-budget report printed `60.1%`
+for a dimension it counted **zero** artefacts in.
+
+```bash
+./scripts-run src/scripts/check_derived_page_truthfulness   # where present
+grep -rn '0%\|0 of 0' docs/*.md
+```
+
+**Structural fix:** an unmeasured category renders as absent or explicitly
+"not measured" — never as a zero and never as a share.
+
+### 9. Equality without validity
+
+Two things are compared and found equal — because neither exists. `diff a b`
+over two absent files returns equal; two empty lists both serialize to `[]`; an
+empty rendered template equals an absent target file. The gate reports
+"in sync" having compared nothing.
+
+```bash
+./scripts-run src/scripts/<gate>            # then delete ONE side and re-run
+```
+
+**Structural fix:** assert both sides exist and are well-formed BEFORE
+comparing. Two absences are the absence of a comparison, not the presence of a
+match. The estate-wide audit is below.
+
+### 10. Hook-bypass override
+
+The gate never ran because the hook that runs it was disabled for that
+invocation. `git commit --no-verify` (and its short `-n` form) skips every
+pre-commit hook; `core.hooksPath` repointed at an empty directory skips them
+permanently and silently. Both produce a commit that looks exactly like a
+commit whose hooks passed. The same shape reaches the runtime hook layer: a
+concern bound in the manifest is still inert on a host that does not honour a
+deny, so "the guard is registered" is not "the guard fired".
+
+<!-- example-fence-allow: git-no-verify -- the fence teaches how to DETECT the core.hooksPath bypass; the forbidden form has to appear for the diagnostic to be readable, and every line here is a read-only query -->
+```bash
+git config --get core.hooksPath                       # empty = repo default, good
+./scripts-run src/scripts/hooks/block_no_verify --help # the tool-call guard
+agent-config hooks:status                             # per-host bindings, not the manifest
+```
+
+**Structural fix:** the bypass is blocked at tool-call time by
+`block-no-verify` on the one host that honours a deny, and the authoritative
+gate is remote CI, which no local override can skip. Never read a local green
+as evidence when the hook path was overridden — re-run in CI, or run the gate
+directly rather than through the hook.
+
+### 11. Cached-green reuse
+
+The green belongs to a different input than the one being judged. Three real
+shapes here. A gate that reads `dist/agent-src/` passes against a **stale
+projection** while the `src/` change it was meant to judge is not in the tree it
+scanned — the recorded trap is a worktree whose stale `dist` faked generator
+drift, and its mirror, a golden capture reading `dist` where the assertion was
+about `src`. A count ratchet sits inside its limit for so long that "within
+budget" stops meaning anything, which is why a baseline carries an expiry at
+all. And the conversational form: trusting a verification run earlier in the
+same session, after the tree has moved underneath it.
+
+```bash
+bash src/scripts/condense.sh --changed        # dist != rewrite(src) => the scan root is stale
+./scripts-run src/scripts/check_condensation --summary   # byte-exactness dist vs rewrite(src)
+```
+
+**Structural fix:** regenerate before judging — this repository's `sync` task
+then its `generate-tools` task, in that order — and treat a baseline unchanged past
+`STALE_AFTER_DAYS` (56, `_lib/gate_baseline.ts:39`) as suppression rather than
+as headroom. A completion claim rests on a run made **after** the last edit, not
+on the freshest run you happen to remember.
+
+## The audited sync/parity gates
+
+Comparison-shaped gates carry entry #9's failure mode by default: `diff a b`
+where neither side exists returns **equal**. Audited 2026-08-05 across
+`src/scripts/` — **27 comparison gates, 19 guarded, 8 vulnerable, 0 undecided.**
+
+A gate is GUARDED when it asserts both sides exist and are well-formed *before*
+comparing — in this tree, almost always via `assertScanned` /
+`assertWatchlistResolves` from `_lib/scan_scope.ts`.
+
+### Guarded (19)
+
+`check_release_surface_equality` · `check_trunk_drift` · `lint_glama_drift` ·
+`check_ci_strict_superset` · `check_condensation` · `check_artefact_checksums` ·
+`check_bridge_derivation` · `check_discovery_determinism` ·
+`check_cli_registry_budget_sync` · `check_template_pin_drift` ·
+`check_gitignore_freshness` · `check_token_optimizer_freshness` ·
+`lint_eval_freshness` · `lint_behavioural_eval_freshness` ·
+`check_release_trunk_sync` · `sync_gitattributes` · `sync_gitignore` ·
+`iron_law_sha` · `check_test_coverage_diff`
+
+Two carry caveats worth knowing: `check_template_pin_drift` has an
+`--allow-empty` opt-in that is a deliberate empty-side pass, and
+`check_test_coverage_diff` is guarded but warn-only, so its guard is currently
+inert.
+
+### Vulnerable (8) — shrink-only from here
+
+| Gate | The both-absent / both-empty path |
+|---|---|
+| ~~`verify_physical_move`~~ | **FIXED in this change.** `_diff_manifest(null, null)` returned `[]`, and an empty issue list means clean. |
+| `check_ci_local_parity` | a missing workflow dir reads as `''` and a missing taskfile is skipped; two empty corpora ⇒ no delta ⇒ exit 0 |
+| `mcp_parity_smoke` | two empty lists both serialize to `[]`; prints "0 entries match" and returns 0 |
+| `probe_projection_fidelity` | a fixture that loses its `entries:` key yields 0 checks and `fail=0` |
+| `sync_agent_settings` | empty template + absent target ⇒ `'' === ''` ⇒ "already in sync" under `--check` |
+| `sync_github_metadata` | two empty topic lists ⇒ no drift ⇒ exit 0 **even under `--strict`** |
+| `check_kernel_prefix_stability` | deleting the committed snapshot returns `'warmup'` ⇒ exit 0 |
+| `bench_drift_check` | fewer than 2 reports ⇒ "no drift gate yet" ⇒ exit 0 |
+
+The seven open rows are recorded rather than swept: fixing release, sync, and
+bench gates in one change would be a large diff across surfaces this change does
+not otherwise touch, which is the unreviewable-batch failure the authoring
+guideline warns about. The fixed row shows the pattern — assert both sides
+exist, and treat two absences as the absence of a comparison.
+
+## The ease tripwire
+
+A verification that was **far easier than expected** is a signal to check the
+path, not a signal of success. Every entry above felt like a pass at the moment
+it happened. When a gate you expected to fight goes green on the first run, run
+one of the detection commands before believing it.
+
+## See also
+
+- [`gate-authoring.md`](gate-authoring.md) — the authoring path that prevents these at the source.
+- `docs/contracts/ci-green-floor.md` § CI delta — what a local pass does and does not cover.
+- `src/scripts/_lib/gate_ledger.ts`, `_lib/scan_scope.ts`, `_lib/ratchet_base_ref.ts` — the three structural fixes above.

package/dist/agent-src/guidelines/agent-infra/first-principles.md

@@ -0,0 +1,192 @@
+# First-Principles Thinking
+
+Reference guideline for Wing-1 deep-thinking work — strip away
+assumptions and conventions to reach fundamental truths, then rebuild
+understanding from the ground up. Distinct from `inversion-thinking`
+(which negates the goal) — first principles **dissolve** the goal into
+verified primitives and reconstruct it without inherited convention.
+Adopted under the **Reference-Guideline Sunset Policy** and
+cross-referenced from:
+
+- [`deep-reading-analyst`](../../skills/deep-reading-analyst/SKILL.md)
+  — L3 Deep analysis depth.
+- [`mental-models`](mental-models.md) — Munger's lattice; first
+  principles is the foundational physics-style lens.
+- [`improve-before-implement`](../../rules/improve-before-implement.md)
+  — challenge the framing of a request before coding it.
+- [`inversion-thinking`](inversion-thinking.md) — pair: first
+  principles rebuilds; inversion stress-tests the rebuild.
+
+> **Core principle:** "What is definitely, provably true?" — strip
+> the inherited and rebuild from primitives.
+
+## Three-Step Process
+
+### Step 1: Identify assumptions
+
+**Ask:** *"What do we assume to be true about this?"*
+
+List all implicit and explicit assumptions in the content:
+
+- Unstated premises.
+- Inherited wisdom (*"everyone knows…"*).
+- Industry conventions.
+- Historical precedents treated as universal laws.
+
+**Example from business:**
+
+- Assumption: *"We need a physical store to sell products."*
+- Question: is this fundamentally true or historically convenient?
+
+### Step 2: Break down to fundamentals
+
+**Ask:** *"What is definitely, provably true?"*
+
+Reduce to indisputable facts:
+
+- Physical laws (if applicable).
+- Mathematical truths.
+- Core human needs / behaviors.
+- Cause-effect relationships you can verify.
+
+**Sorting Framework:**
+
+```
+Claim → Ask: "How do I know this is true?"
+    ↓
+├─ "It just is"                       → Probably an assumption, dig deeper
+├─ "That's how it's always done"      → Convention, not fundamental
+├─ "X happens, then Y happens"        → Potential fundamental (verify causation)
+└─ "Mathematically/physically must be true" → Fundamental
+```
+
+### Step 3: Rebuild from scratch
+
+**Ask:** *"Starting from fundamentals only, what logically follows?"*
+
+Reconstruct without importing old assumptions:
+
+1. Begin with verified fundamentals.
+2. Each step must logically follow from previous.
+3. Note where you make new assumptions (be explicit).
+4. Compare new construction to original concept.
+
+## Application Template
+
+```markdown
+## Original Concept / Argument
+[What the author claims]
+
+## Hidden Assumptions
+- Assumption 1: [Something taken as given]
+- Assumption 2: [...]
+
+## Verified Fundamentals
+- Fundamental 1: [Provably true core fact]
+- Fundamental 2: [...]
+
+## Rebuilt Understanding
+Starting from fundamentals only:
+Step 1: [First logical derivation]
+Step 2: [Second logical derivation]
+...
+Conclusion: [What actually follows]
+
+## Comparison
+Original vs. rebuilt:
+- What survived: [Fundamentally sound ideas]
+- What doesn't hold: [Based on questionable assumptions]
+- New insights: [What rebuilding revealed]
+```
+
+
+## Common First Principles by Domain
+
+### Business / economics
+
+- People act in self-interest (with caveats).
+- Supply and demand affect price.
+- Value = willingness to pay.
+- Scarcity creates value.
+
+### Psychology / human behavior
+
+- Humans seek pleasure, avoid pain.
+- Social status matters to humans.
+- Cognitive biases exist (not "people are rational").
+- Habits form through repetition.
+
+### Technology
+
+- Information can be copied at near-zero cost.
+- Network effects: value ∝ n² (Metcalfe's law).
+- Moore's law (transistor density doubles ~every 2 years).
+- Computation has energy cost.
+
+### Physics / reality
+
+- Energy is conserved.
+- Entropy increases.
+- Speed of light is constant.
+- Cause precedes effect.
+
+## Red Flags: Pseudo-First-Principles
+
+Watch for claims disguised as fundamentals:
+
+- *"People always prefer X"* (overgeneralization).
+- *"This is just human nature"* (often cultural).
+- *"Economics proves…"* (many schools of economics).
+- *"Science says…"* (which study? replicated?).
+
+**Test:** can you point to specific evidence / mechanism, or is it
+folk wisdom?
+
+## Powerful Questions
+
+- *"Why is this true?"* (repeat 5 times — "5 Whys").
+- *"What must be true for this to work?"*
+- *"If I couldn't do it this way, what's another path?"*
+- *"What would an alien with no context think?"*
+- *"What if the opposite were true?"*
+
+## Worked Example — *"Need for College Education"*
+
+**Assumptions:**
+
+- Need degree to get good job.
+- Learning requires formal institution.
+- 18–22 is the right age.
+- Four years is optimal duration.
+
+**Fundamentals:**
+
+- Employers want skilled workers.
+- Skills can be demonstrated.
+- Learning requires time + practice.
+- Knowledge can be transmitted.
+
+**Rebuilt:**
+
+- → Employers want proof of skill.
+- → Proof can be: degree OR portfolio OR test OR track record.
+- → Therefore, degree is one option, not necessity.
+- → Insight: focus on skill + proof, not credential alone.
+
+## Practical Use in Reading
+
+When analyzing content:
+
+1. **Identify claims** that seem absolute.
+2. **Challenge foundations:** *"Does this HAVE to be true?"*
+3. **Verify causation:** *"Does A truly cause B, or just correlate?"*
+4. **Rebuild the argument** from indisputable facts only.
+5. **Compare** what survives vs. what was assumption.
+
+This exposes weak arguments and strengthens valid ones.
+
+---
+
+## ADOPT citation
+
+Adapted from an external reference.

package/dist/agent-src/guidelines/agent-infra/framework-neutrality-patterns.md

@@ -0,0 +1,66 @@
+# Framework Neutrality — Patterns
+
+> Forbidden-pattern table, cross-stack documentation allowance, and carve-out pointer shape for the `framework-neutrality-in-generic-skills` rule
+
+_Origin: migrated from `src/rules/framework-neutrality-in-generic-skills.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, scope, and exemption list stay in the rule; this file carries the pattern reference._
+
+## Forbidden patterns in generic artifacts
+
+| Pattern | Why it leaks | Fix |
+|---|---|---|
+| `FormRequest` as a mandate | Laravel-only validation class | Say "request-validation primitive (FormRequest in Laravel, zod in Next.js, pydantic in FastAPI)" or move to `laravel-validation` carve-out |
+| `php artisan …` as a canonical command | Laravel CLI | Generalize to "the framework's CLI" or move to `artisan-commands` carve-out |
+| `PHPStan` as the only example | PHP-only static analyser | List peers (`mypy` for Python, `tsc` for TypeScript) or move to `quality-tools` carve-out |
+| `composer.json` mentioned alone | PHP package manifest | Add `package.json` / `pyproject.toml` peers, or move to a PHP-scoped carve-out |
+| `Eloquent` / `Model::…` | Laravel ORM | Generalize to "the project's ORM/data layer" or move to `eloquent` carve-out |
+| `Pest` as the only test runner | PHP/Laravel test framework | List peers (`pytest`, `vitest`, `jest`) or move to `pest-testing` carve-out |
+| `Blade` / `Livewire` / `Flux` as default UI | Laravel view stack | Generalize to "the project's UI layer" or move to `blade-ui` / `livewire` / `flux` carve-outs |
+| `vendor/bin/<tool>` as a canonical path | PHP/Composer-specific binary path | Say "the project's quality CLI" or carve-out it |
+| `Rector` as the only refactor tool | PHP-only refactorer | List peers (`ts-morph`, `libcst`) or carve-out it |
+| "every controller" / "all controllers" | Assumes MVC PHP framework | Generalize to "every request handler" / "every endpoint" |
+
+## Allowed: cross-stack documentation
+
+Multi-stack tables or detection maps with **at least two ecosystems
+side-by-side** are documentation, not leakage. The linter's
+auto-detect heuristic skips a hit when its ±2-line window contains
+patterns from a different ecosystem family (`php_family` vs
+`js_family` vs `python_family`).
+
+Example (allowed):
+
+```
+- PHP/Composer project → `composer.json` present
+- Node project        → `package.json` present
+- Python project      → `pyproject.toml` present
+```
+
+## Allowed: carve-out pointers
+
+A generic artifact may end a section with a one-line handoff to its
+framework-specific peers. Canonical shape:
+
+```
+→ Laravel-specific: see [laravel-validation](../../skills/laravel-validation/SKILL.md)
+→ Next.js-specific: see [nextjs-patterns](../../skills/nextjs-patterns/SKILL.md)
+```
+
+The pointer is a link, not a procedure — the generic artifact never
+inlines stack-specific code.
+
+## Enforcement
+
+`scripts/lint_framework_leakage.ts` runs in the package CI pipeline.
+Exit codes:
+
+- `0` — no hits, or every hit is auto-detected as cross-stack, or
+  every hit is allowlisted in
+  `scripts/lint_framework_leakage_allowlist.json` with a `reason`.
+- `1` — at least one hit in a generic artifact (non-carve-out) that
+  is neither cross-stack nor allowlisted.
+
+## See also
+
+- `framework-neutrality-in-generic-skills` (rule) — Iron Law, scope, exemption list.
+- `roadmap-ci-steps-policy` — sibling Tier-2a rule that drove this pattern.
+- `skill-quality` — every skill must remain executable; carve-outs must still pass skill-quality.