@event4u/agent-config 3.0.0 → 3.1.1

package/.agent-src/rules/strategy-safety-floor.md

@@ -0,0 +1,114 @@
+---
+type: "auto"
+tier: "2a"
+description: "Founder-strategy output (vision, positioning, competitive moats, market entry, OKR trees, build-vs-buy) — never issue final strategic call; surface trade-offs; human owns the decision"
+source: package
+triggers:
+  - keyword: "vision"
+  - keyword: "positioning"
+  - keyword: "moat"
+  - keyword: "competitive"
+  - keyword: "market entry"
+  - keyword: "OKR"
+  - keyword: "build vs buy"
+  - keyword: "buy vs partner"
+  - keyword: "beachhead"
+  - keyword: "GTM"
+  - keyword: "category"
+  - keyword: "where to play"
+  - keyword: "where not to play"
+  - phrase: "what's our strategy"
+  - phrase: "should we enter"
+  - phrase: "what's our moat"
+  - phrase: "where should we focus"
+  - phrase: "should we reorg"
+routes_to:
+  - "skill:vision-articulation"
+  - "skill:positioning-strategy"
+  - "skill:competitive-moat-analysis"
+  - "skill:market-entry-analysis"
+  - "skill:build-buy-partner"
+  - "skill:okr-tree-modeling"
+workspaces:
+  - founder
+packs:
+  - founder-strategy
+lifecycle: active
+trust:
+  level: advisory
+  confidence: high
+  human_review_required: true
+install:
+  default: true
+  removable: false
+---
+<!-- agent-config:human-review-banner -->
+> HUMAN REVIEW REQUIRED · trust: advisory · owner: founder
+
+# Strategy Safety Floor
+
+Domain safety floor for founder-strategy artefacts (vision, positioning, competitive moats, market entry, OKR trees, build-vs-buy). Auto-activates when `pack-founder-strategy` is installed.
+
+## Iron Law — strategy is a frame, not a verdict
+
+```
+THE AGENT NEVER ISSUES A FINAL "ENTER MARKET X" / "BUILD" / "BUY" / "REORG" CALL.
+FRAME THE TRADE-OFF. SURFACE THE COST OF EACH PATH. THE FOUNDER DECIDES.
+```
+
+Strategy output is a structured argument — it sharpens the question, surfaces the trade-offs, names the bet being made. It does **not** make the bet. Holds for every founder-strategy skill (`vision-articulation`, `positioning-strategy`, `competitive-moat-analysis`, `market-entry-analysis`, `build-buy-partner`, `okr-tree-modeling`, `org-design`, `fundraising-narrative`).
+
+## Mandatory disclosure footer
+
+Every strategy deliverable (positioning brief, market-entry memo, build-vs-buy analysis, OKR tree, moat map) ends with:
+
+```
+> **Not a strategic decision.** This is a framing of the trade-off, not the
+> verdict. The named bet, residual risk, and counter-case are surfaced
+> above. Founder review required before commitment to a path.
+```
+
+The footer is non-optional. Drop it → safety violation.
+
+## Required structural elements
+
+Each strategy deliverable surfaces, in this order:
+
+1. **The bet** — one sentence naming what is being chosen and what is being given up.
+2. **Why now / why us** — the timing and capability claim, with at least one piece of evidence per claim.
+3. **Counter-case** — one paragraph on the strongest argument against this path (not a strawman).
+4. **Residual risk** — what stays unresolved after this decision; what would invalidate it.
+5. **Decision owner** — named human who owns the call (default: founder / CEO / leadership team).
+
+## Human review escalation
+
+| Trigger | Action |
+|---|---|
+| Board-bound positioning or strategy memo | Surface `HUMAN REVIEW REQUIRED` banner; do not commit without explicit user confirmation. |
+| Reorg, layoff, or org-design recommendation | Refuse to finalize; output `DRAFT` watermark and route to the user for the people-impact review. |
+| Market entry into a regulated domain (legal, medical, financial) | Refuse; route to `domain-safety-disclaimer` and defer to domain counsel. |
+| Public-facing positioning (PR, fundraise narrative) | Mandatory counter-case + named decision owner. |
+
+## Forbidden moves
+
+- "You should enter market X" without surfacing the cost of not entering Y
+- Positioning verdict without an opposable axis (per `positioning-strategy`)
+- Build-vs-buy recommendation without integration-cost and optionality analysis
+- OKR tree without measurability + laddering check
+- Moat claim without a competitor delta (named, with evidence)
+- Strategic call that fails the inversion test (per `competitive-moat-analysis`)
+- Vision statement without a stated counter-case
+
+## When this rule applies
+
+Active whenever any of these are in the request, the open file, or the loaded skill set:
+- A founder-strategy skill name (`vision-articulation`, `positioning-strategy`, `competitive-moat-analysis`, `market-entry-analysis`, `build-buy-partner`, `okr-tree-modeling`, `org-design`, `fundraising-narrative`)
+- Keywords: vision, positioning, moat, competitive, market entry, OKR, build vs buy, beachhead, GTM, category, where to play
+- Phrases: "what's our strategy", "should we enter", "what's our moat", "where should we focus", "should we reorg"
+
+## See also
+
+- `domain-safety-disclaimer` — generic advisory-content floor (core pack)
+- `finance-safety-floor` — finance-pack floor, often paired with strategy work (pack-finance-basic)
+- [`positioning-strategy`](../skills/positioning-strategy/SKILL.md) — opposable-axis discipline
+- [`competitive-moat-analysis`](../skills/competitive-moat-analysis/SKILL.md) — inversion test

package/.agent-src/skills/agents-md-thin-root/SKILL.md

@@ -21,13 +21,15 @@ install:
   removable: false
 ---
 
+<!-- cloud_safe: noop -->
+
 # agents-md-thin-root
 
 ## When to use
 
 Use when:
 - Editing `AGENTS.md` at the package root.
-- Editing `.agent-src.uncompressed/templates/AGENTS.md` (consumer-shipped template).
+- Editing `packages/core/.agent-src.uncompressed/templates/AGENTS.md` (consumer-shipped template).
 - Reviewing a PR that changes either file.
 - Running `/optimize/agents`.
 - A budget meter (`scripts/measure_augment_budget.py`) flags the package-root AGENTS.md as the dominant cost.
@@ -35,7 +37,7 @@ Use when:
 ## Do NOT
 
 - Edit `.github/copilot-instructions.md` with this skill (use `copilot-agents-optimization` instead).
-- Edit other `.md` files under `.augment/`, `.agent-src.uncompressed/`, or `agents/` with this skill.
+- Edit other `.md` files under `.augment/`, `packages/*/.agent-src.uncompressed/`, or `agents/` with this skill.
 - Add a section to AGENTS.md without first checking whether an outboard target already exists in `agents/settings/contexts/` or `docs/contracts/`.
 - Replace prose with a bare link `[label](path)` — every pointer needs a *why*-clause ≥ 60 chars or it does not count toward the 40 % ratio.
 - Reuse the package-root anatomy in the consumer template — caps and target paths differ.
@@ -53,7 +55,7 @@ Every entry describes **what** the project does or **where** to learn more — n
 | File | FAIL above | WARN above | Target |
 |---|---|---|---|
 | `AGENTS.md` (package root) | 3,000 chars | 2,800 chars | ≤ 2,800 |
-| `.agent-src.uncompressed/templates/AGENTS.md` (consumer) | 2,500 chars | 2,300 chars | ≤ 2,300 |
+| `packages/core/.agent-src.uncompressed/templates/AGENTS.md` (consumer) | 2,500 chars | 2,300 chars | ≤ 2,300 |
 
 Char-count is raw file size (`wc -c`), frontmatter included. Enforcement: `scripts/lint_agents_md.py` (Phase 7), wired into the package's CI pipeline via the `lint-agents-md` task. WARN is a soft signal in CI; FAIL blocks merge.
 
@@ -91,7 +93,7 @@ Every substantive pointer specifies, on the same line or the immediately followi
 
 ## The contract — emergency-triage block
 
-Every Thin-Root AGENTS.md MUST contain an **Emergency Triage** section verbatim from `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` (Phase 6.4 will create that file as the canonical source). The block lists the five questions a host agent answers from the root file alone when network / tool access is degraded:
+Every Thin-Root AGENTS.md MUST contain an **Emergency Triage** section verbatim from `packages/core/.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` (Phase 6.4 will create that file as the canonical source). The block lists the five questions a host agent answers from the root file alone when network / tool access is degraded:
 
 1. What is this repository?
 2. What language(s) does this repository accept?
@@ -105,22 +107,22 @@ Each answer must fit on one line. The block exists so the root never silently de
 
 1. **Measure baseline.** `wc -c AGENTS.md` and `python3 scripts/measure_augment_budget.py`. Record current char-count and the gap to 2,200 / 2,500.
 2. **Inventory sections.** List every `## ` heading and its char-count. Mark each as `keep-inline` (Iron-Law-adjacent, ≤ 200 chars, no good outboard target) or `outboard-candidate` (longer-form prose, table-only sections, narrative).
-3. **Identify outboard targets.** For each `outboard-candidate`, name the destination — `.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, an existing skill body. Never invent a new top-level directory.
+3. **Identify outboard targets.** For each `outboard-candidate`, name the destination — `packages/core/.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, an existing skill body. Never invent a new top-level directory.
 4. **Move content; insert pointer.** Cut the section into the target file. Replace it in AGENTS.md with a single substantive pointer per anatomy above. Verify the *why*-clause length.
 5. **Re-measure.** `wc -c AGENTS.md` again. If above 2,200, repeat steps 2–4 on the next-largest section. Above 2,500 = must outboard further before commit.
 6. **Validate pointer ratio.** Count non-blank lines and substantive-pointer lines. Ratio < 0.40 = collapse decorative or boilerplate lines into a single pointer or remove.
-7. **Verify emergency-triage block.** Diff the in-file block against `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md`. Drift = revert to canonical.
+7. **Verify emergency-triage block.** Diff the in-file block against `packages/core/.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md`. Drift = revert to canonical.
 8. **Run lints.** `task lint-agents-md && task check-refs && task lint-skills`. All green before commit.
 
 ## Procedure — apply Thin-Root to consumer template
 
-Same procedure, applied to `.agent-src.uncompressed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/settings/contexts/`, ...), not this package's authoring tree.
+Same procedure, applied to `packages/core/.agent-src.uncompressed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/settings/contexts/`, ...), not this package's authoring tree.
 
 ## Gotchas
 
-- **Outboarding to a new top-level dir.** Inventing `agents/explainers/` or `docs/notes/` for the moved content silently widens the contract surface. Outboard only into `.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, or an existing skill body.
+- **Outboarding to a new top-level dir.** Inventing `agents/explainers/` or `docs/notes/` for the moved content silently widens the contract surface. Outboard only into `packages/core/.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, or an existing skill body.
 - **Pointer-ratio inflation by decoration.** Adding boilerplate "Browse all skills" / "See also" links to lift the ratio above 40 % defeats the purpose. The lint counts only substantive pointers (with a *why*-clause ≥ 60 chars); decorative links get filtered out and the ratio drops back below threshold.
-- **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync.
+- **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `packages/core/.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync.
 - **Cap inversion under WARN.** A 2,250-char AGENTS.md (above 2,200 WARN, below 2,500 FAIL) is a yellow signal not a green one — every additional sentence raises the probability of the next FAIL. Treat WARN as the spend boundary, not a buffer.
 - **Char-count includes frontmatter.** `wc -c` counts every byte including the YAML preamble, blank lines, and the trailing newline. Stripping a section to "look smaller" without re-running `wc -c` understates the true budget impact.
 - **Path enumeration.** A run of three or more bare `` `path/to/dir/` `` bullets without *why*-clauses is the classic re-bloat pattern. The lint emits a WARN at ≥ 3 such lines. Collapse them into one capability-style pointer — see the recipe in [`agents-md-anatomy § Iron Law`](../../contexts/contracts/agents-md-anatomy.md#iron-law--capabilities-over-structure).
@@ -136,6 +138,10 @@ When invoked as a planning step, produce:
 4. Specific outboarding edits as a numbered diff plan.
 5. The four lint commands the agent must run before claiming completion.
 
+## Cloud Behavior
+
+Inert on cloud surfaces. The skill governs the package-root `AGENTS.md` and the consumer-shipped template — both authoring artifacts inside this repository. Cloud agents working on consumer projects never edit those files directly; their copy is delivered by the package install pipeline and refreshed by the package sync pipeline. The Thin-Root contract therefore has no cloud-side procedure to execute, which is why this skill is marked `cloud_safe: noop`.
+
 ## See also
 
 - [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md) — Capabilities-over-Structure Iron Law, multi-tool symlink strategy, monorepo per-package layout, refactor recipe, full gotcha catalog.

package/.agent-src/skills/async-python-patterns/SKILL.md

@@ -10,7 +10,7 @@ workspaces:
   - engineering
 packs:
   - python
-lifecycle: active
+lifecycle: experimental
 trust:
   level: professional
   confidence: high

package/.agent-src/skills/project-analysis-node-express/SKILL.md

@@ -7,7 +7,7 @@ workspaces:
   - engineering
 packs:
   - typescript
-lifecycle: active
+lifecycle: experimental
 trust:
   level: professional
   confidence: high

package/.agent-src/skills/readme-reviewer/SKILL.md

@@ -67,7 +67,7 @@ Inspect truth-defining files:
 - Config files, tests, existing docs
 
 Verify: install steps exist, commands work, features are implemented,
-deps are real.
+dependencies are real.
 
 ### 3. Validate installation and setup
 
@@ -153,8 +153,54 @@ Structure checks:
 → See `docs/guidelines/docs/readme-size-and-splitting.md` for full thresholds,
 splitting strategies, and anti-patterns.
 
+### 9. Validate every link and detect orphans — MANDATORY
+
+For every internal link in the README:
+
+1. Resolve the path. `test -f` files, `test -d` directories. Strip
+   `#anchor` and `?query` before the check.
+2. For every anchor link (`file.md#section`), grep the target file for
+   the heading slug. Missing slug = broken anchor.
+3. Group findings:
+   - **broken** — target does not exist (❌ Critical)
+   - **anchor-broken** — file exists, anchor does not (⚠️ Major)
+   - **path-drift** — target moved but a valid path exists elsewhere
+     (⚠️ Major, propose the corrected path)
+
+For every documentation file referenced by the README, check whether
+it has any **other** references in the repo (`grep -r` over
+`AGENTS.md`, `docs/`, `.agent-src*/`, `.augment/`, `packages/`).
+Files referenced only by this README are **single-use** — note them
+so they can be moved or inlined later.
+
+For every doc under `/docs/` that the README **does not** link, check
+whether anything else in the repo links it. Files with zero inbound
+references are **orphan-candidates** — surface them, never delete
+silently.
+
+### 10. Currency check — drift detection
+
+The README may have been correct at write-time but drifted since.
+Compare the README's claims to the live repository:
+
+- **Counts** (badges like "Skills: 218") — recount from the source tree
+  and flag any drift > 0
+- **Commands** — every documented `task`, `npm run`, `npx`, or `bash`
+  call must exist in `Taskfile.yml`, `package.json scripts`, or the
+  named script file at its claimed path
+- **Profiles / user-types / packs** — list members against the live
+  directory listing
+- **Version pins** — runtime, framework, peer-dep versions stated in
+  README vs. the manifest's `engines` / `require` / `dependencies`
+- **Visual identity** — banner / hero image references resolve to real
+  files (not 404s in GitHub rendering)
+
 ## Output format
 
+1. Produce three subsections in order: Summary, Findings, Confidence; no prose outside them.
+2. Findings table must use the severity vocabulary (❌ Critical / ⚠️ Major / ℹ️ Minor) and cite the exact section name.
+3. Close the report with a *Confidence* block that separates confirmed-correct, needs-verification, and unclear-due-to-missing-context.
+
 ### 1. Summary
 
 | Field | Value |
@@ -168,8 +214,11 @@ splitting strategies, and anti-patterns.
 | # | Severity | Section | Issue | Fix |
 |---|---|---|---|---|
 | 1 | ❌ Critical | Install | Command `X` does not exist | Replace with `Y` |
-| 2 | ⚠️ Major | Usage | Example uses deprecated API | Update to current API |
-| 3 | ℹ️ Minor | Structure | Requirements buried below usage | Move above install |
+| 2 | ❌ Critical | Profile grid | Link `.agent-src.uncompressed/profiles/` 404s | Repoint to `packages/core/.agent-src.uncompressed/profiles/` |
+| 3 | ⚠️ Major | Badges | "Skills: 218" — live count is 207 | Update badge or note drift |
+| 4 | ⚠️ Major | Usage | Example uses deprecated API | Update to current API |
+| 5 | ℹ️ Minor | Structure | Requirements buried below usage | Move above install |
+| 6 | ℹ️ Minor | Docs | `docs/foo.md` only linked by README | Either inline or keep as standalone |
 
 Severity levels:
 

package/.agent-src/skills/readme-writing/SKILL.md

@@ -49,9 +49,34 @@ the intended audience. Reflects the real repository — not assumptions.
 - **Strong quickstart over exhaustive noise** — a reader should get started in 30 seconds
 - **Right scope** — high-level overview in README, deep content in dedicated docs
 - **Match the repo type** — a package README differs from an app, CLI tool, or framework
+- **Re-analyze every time** — never trust cached knowledge of the repo; the README that drifted yesterday is the README the model wrote from memory
+- **Preserve existing visual identity** — banner, badges, profile/role grids, official logo lockups stay byte-identical unless the user explicitly asks to change them
 
 ## Procedure
 
+### 0. Re-analysis gate — MANDATORY before any writing
+
+Before drafting a single line, run a fresh repository inspection in **this**
+session. Do not rely on prior knowledge, prior turns, or the existing README
+prose. Produce an explicit evidence ledger:
+
+```
+ledger:
+  package:      <name + version from manifest>
+  description:  <verbatim from manifest>
+  cli_entry:    <bin / entry from manifest, if any>
+  commands:     <list of real commands from Taskfile / Makefile / package.json scripts>
+  install:      <verified install path(s) from scripts/install.* or docs>
+  doc_targets:  <list of /docs files actually linked from the new draft>
+  counts:       <skills / rules / commands / personas / advisors — if surfaced as badges>
+  visual_keep:  <line range of existing README header, banner, badge block to preserve>
+```
+
+If any cell is unknown, run `ls`, `grep`, `find`, or read the file before
+writing — never invent. If the user asks to "use the existing banner",
+locate the exact source lines and reproduce them byte-for-byte, including
+the surrounding HTML.
+
 ### 1. Identify README type and audience
 
 Determine repository type:
@@ -139,26 +164,49 @@ for install, first example, or requirements).
 splitting strategies (reference-split, deep-link tables, collapsibles),
 multi-audience handling, and anti-patterns.
 
-### 7. Validate
+### 7. Validate links and detect orphans — MANDATORY
+
+For every internal link in the new draft:
+
+1. Resolve the path. If it points to a file, `test -f` the path. If a
+   directory, `test -d`. Strip `#anchor` and `?query` before the check.
+2. For every anchor link (`file.md#section`), grep the target file for
+   the heading slug. Missing anchor = broken link.
+3. Build the **link-delta** between the old README and the new one:
+   - **kept**: linked in both
+   - **added**: only linked by the new README
+   - **dropped**: only linked by the old README
+
+For every `dropped` target, search the rest of the repository
+(`grep -r "<path>"` over `AGENTS.md`, `docs/`, `.agent-src*/`,
+`.augment/`, `packages/`). If no other file references it, mark
+**orphan-candidate**. Surface the list to the user — do not delete
+silently.
+
+### 8. Validate
 
 After writing, verify:
 
 - [ ] Every documented command exists in the repo (`Taskfile.yml`, `Makefile`, `package.json scripts`, etc.)
 - [ ] Setup steps are reproducible (no missing prerequisites)
 - [ ] No features or capabilities are invented
-- [ ] First screen answers: what, why, how-to-start
+- [ ] **First screen contract** — within the first ~40 lines: project name, one-sentence pitch, install command (or pointer), and the primary CTA
+- [ ] Banner, badges, and any explicit "preserve" block from Step 0 are byte-identical to source
 - [ ] No dead sections (heading with 1-2 trivial sentences)
 - [ ] Scope is right — deep content moved to dedicated docs, not crammed in
 - [ ] Size below the "overloaded" threshold, or splitting is in place (see size guideline)
 - [ ] ToC present if README > 150 lines or > 6 top-level sections
 - [ ] Matches existing tonality if repo has established voice
-- [ ] All file paths and references are valid
+- [ ] Every internal link resolved per Step 7 — zero broken file or anchor links
+- [ ] Orphan-candidate list produced even if empty
 
 ## Output format
 
 1. Full README draft
 2. Short note: detected repo type + audience
-3. Any uncertainties or assumptions that need confirmation
+3. **Link delta** — `kept` / `added` / `dropped` with orphan-candidates flagged
+4. Evidence ledger (Step 0) so the user can audit assumptions
+5. Any uncertainties or assumptions that need confirmation
 
 ## Gotcha
 

package/.agent-src/skills/readme-writing-package/SKILL.md

@@ -48,9 +48,33 @@ what it does, whether it fits their stack, how to install it, and how to use it.
 - **Compatibility must be explicit** — don't imply broad support without evidence
 - **First code example must be real, minimal, and verified** — no pseudo-code
 - **README = onboarding, /docs = reference** — keep README focused
+- **Re-analyze every time** — never write from cached knowledge; verify the manifest, source, and CI matrix in this session
+- **Preserve existing visual identity** — banner, badges, hero images, and logo lockups stay byte-identical unless the user explicitly asks to change them
 
 ## Procedure
 
+### 0. Re-analysis gate — MANDATORY before any writing
+
+Before drafting, produce an evidence ledger from a fresh inspection of
+the package — manifest, source, CI, examples. Do not rely on prior turns
+or the existing README prose.
+
+```
+ledger:
+  package:       <name + version from manifest>
+  description:   <verbatim from manifest>
+  install_cmd:   <verified against the manifest's package manager>
+  requirements:  <language version, framework version, ext-*, services>
+  public_api:    <entry classes / functions / exports from source>
+  test_command:  <real command from manifest scripts / Taskfile>
+  doc_targets:   <list of /docs files actually linked from the new draft>
+  visual_keep:   <line range of existing README header / banner / badges to preserve>
+```
+
+If any cell is unknown, run `ls`, `grep`, `find`, or read the file before
+writing — never invent. When the user asks to keep the existing banner
+or badge row, reproduce it byte-for-byte from the source.
+
 ### 1. Identify package type and audience
 
 | Type | Audience | README focus |
@@ -63,7 +87,7 @@ what it does, whether it fits their stack, how to install it, and how to use it.
 
 ### 2. Inspect package truth sources
 
-Read files that define actual package behavior:
+Read and **verify** files that define actual package behavior (confirm each claim against the source — never paraphrase from memory):
 
 - Manifest: `composer.json`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, or `*.gemspec` — name, description, requirements, scripts
 - Source entrypoints — public API surface, main classes/functions
@@ -255,7 +279,21 @@ capability comparison. They serve different jobs — install vs. coverage.
 
 README = enough to adopt. Docs = enough to master.
 
-### 8. Validate
+### 8. Validate links and detect orphans — MANDATORY
+
+For every internal link in the new draft:
+
+1. Resolve the path. `test -f` files, `test -d` directories. Strip
+   `#anchor` and `?query` before the check.
+2. For every anchor link, grep the target for the heading slug.
+3. Build the **link-delta** vs. the old README — `kept` / `added` /
+   `dropped`. For every `dropped` target, search the rest of the repo
+   (`grep -r` over `AGENTS.md`, `docs/`, `.agent-src*/`, `packages/`).
+   No other reference → mark **orphan-candidate**.
+
+Surface the orphan-candidate list to the user — never delete silently.
+
+### 9. Validate
 
 - [ ] Install command is correct and complete
 - [ ] Compatibility/requirements match the manifest (`composer.json`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.gemspec`) and the CI matrix
@@ -266,15 +304,20 @@ README = enough to adopt. Docs = enough to master.
 - [ ] Deep content is in docs, not README (see size guideline)
 - [ ] Multi-platform install uses a table, not stacked blocks
 - [ ] No duplication between README and `/docs/`
-- [ ] First screen shows: what, install, requirements
+- [ ] **First screen contract** — within ~40 lines: name, one-sentence pitch, install command, requirements (or pointer)
+- [ ] Banner / badges / hero from Step 0 visual_keep are byte-identical to source
+- [ ] Every internal link resolved per Step 8 — zero broken file or anchor links
+- [ ] Orphan-candidate list produced even if empty
 
 ## Output format
 
 1. Full README draft
 2. Detected package type + audience
 3. Compatibility summary
-4. Uncertainties needing confirmation
-5. Suggested follow-up docs if README would become too large
+4. **Link delta** — `kept` / `added` / `dropped` with orphan-candidates flagged
+5. Evidence ledger (Step 0) so the user can audit assumptions
+6. Uncertainties needing confirmation
+7. Suggested follow-up docs if README would become too large
 
 ## Gotcha
 

package/.agent-src/skills/systematic-debugging/SKILL.md

@@ -170,6 +170,40 @@ If you have tried **three** fixes and the bug is still present:
   design that keeps producing this class of bug?
 * Surface the question to the user. Do not attempt fix #4 silently.
 
+## Debug micro-loop — one test, one fix, one re-run
+
+Tactical complement to the 6-phase loop, for failing test suites,
+broken builds, and regressions. Each lap completes in **one turn**.
+Pairs with [`context-hygiene § Read-Loop Detection`](../../rules/context-hygiene.md#read-loop-detection--the-15--25-rule)
+— if you catch yourself reading-without-acting, run this loop.
+
+1. **Pick ONE failing test.** Run it isolated:
+   `npx vitest run path/to/single.test.ts`,
+   `pytest tests/x.py::test_y`, `phpunit --filter test_y`. Full suite
+   between laps is forbidden — it drowns the signal.
+2. **Read the assertion, not the file.** `expected X to be Y` names
+   the gap. Hypothesis comes from the error, not a hunch.
+3. **Source first, test second.** Shape mismatch → read the producer
+   (route, function, component) **once**, then align the test (or fix
+   the producer if it's the regression — Phase 2 decides which).
+4. **Use git as a diagnostic.** Regression in code that worked →
+   `git log --oneline -- <file>` → `git show <sha> -- <file>`. The
+   before/after diff names the dropped logic faster than re-reading.
+5. **One edit, then re-run the same single test.** Green → next
+   failing test. Red → step 2 with the new assertion. **Never** edit
+   two unrelated things before re-running.
+6. **Full suite at the end, not between laps.** It is the gate, not
+   the feedback loop.
+
+**Anti-patterns this loop prevents:**
+
+* Editing source to make tests pass when the test was wrong (or
+  vice versa) — step 3 forces "read producer first".
+* Drowning in full-suite output every lap — step 1 pins one file.
+* Three reads in a row without a fix — step 5 forces an edit per lap.
+* Guessing at mock / payload shape — step 3 forces reading the route
+  handler or component the mock substitutes for.
+
 ## Gathering evidence — cheap tools first
 
 | What you need | Tool |
@@ -252,6 +286,13 @@ When reporting debug findings to the user:
 * A green test run after changes, without having first seen it red
 * "This looks similar to bug X, so it's the same fix"
 * Suppressing a log, warning, or exception instead of tracing its source
+* **Three consecutive read-only turns** (only `view` / `grep` /
+  `git log` / `codebase-retrieval`, no edits, no test runs) — trips the
+  Read-Loop Detection 15-minute warning. See
+  [`context-hygiene § Read-Loop Detection`](../../rules/context-hygiene.md#read-loop-detection--the-15--25-rule)
+  and run the Debug micro-loop instead: one failing test → read the
+  assertion → read the producer once → one edit → re-run that single
+  test.
 
 ## Do NOT
 

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "2.26.0"
+agent_config_version: "3.0.0"
 
 # --- Project identity ---
 project:

package/.agent-src/templates/hooks/pre-commit-frontmatter

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Pre-commit hook: artefact frontmatter lint (event4u/agent-config, ADR-013)
+#
+# Aborts the commit when any staged .md file under
+# `.agent-src.uncompressed/` violates the per-artefact frontmatter
+# contract (workspaces / packs / lifecycle / trust / install). Exits
+# silently when no such files are staged — zero overhead on unrelated
+# commits.
+#
+# To run manually:
+#   ./agent-config hooks:install-frontmatter
+#   python3 scripts/lint_artefact_frontmatter.py
+#
+# To uninstall:
+#   rm .git/hooks/pre-commit
+set -e
+
+# Only act on commits that touch the source-of-truth artefact tree
+# (or the linter / vocabulary that govern it).
+staged="$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)"
+case "$staged" in
+  *.agent-src.uncompressed/*.md*|*config/discovery/*.yml*|*scripts/lint_artefact_frontmatter.py*)
+    : ;;
+  *)
+    exit 0 ;;
+esac
+
+# Resolve the linter — prefer the consumer-shipped path, fall back to
+# the source-of-truth copy when run from inside the package itself.
+script=""
+for cand in \
+  ".augment/scripts/lint_artefact_frontmatter.py" \
+  ".agent-src/scripts/lint_artefact_frontmatter.py" \
+  "scripts/lint_artefact_frontmatter.py"; do
+  if [ -f "$cand" ]; then
+    script="$cand"
+    break
+  fi
+done
+
+if [ -z "$script" ]; then
+  echo "⚠️  pre-commit-frontmatter: lint_artefact_frontmatter.py not found." >&2
+  echo "    Run \`task install\` (or \`./agent-config install\`) and retry." >&2
+  echo "    Skipping check — letting commit through." >&2
+  exit 0
+fi
+
+if ! python3 "$script" --quiet >/dev/null 2>&1; then
+  echo "❌  Artefact frontmatter lint failed (ADR-013 contract violation)." >&2
+  echo "" >&2
+  echo "    Re-run for details:" >&2
+  echo "      python3 $script" >&2
+  echo "      task lint-artefact-frontmatter" >&2
+  echo "" >&2
+  echo "    Common fixes:" >&2
+  echo "      • Add missing workspaces/packs/lifecycle/trust/install keys." >&2
+  echo "      • Pick values from config/discovery/{workspaces,packs}.yml." >&2
+  echo "      • For scaffolds, add the path to" >&2
+  echo "        config/discovery/unassigned-artefacts.yml with a reason." >&2
+  echo "" >&2
+  echo "    To bypass once (NOT recommended):" >&2
+  echo "      git commit --no-verify" >&2
+  exit 1
+fi
+
+exit 0