@event4u/agent-config 9.7.0 → 9.9.0

package/docs/quality.md

@@ -1,98 +0,0 @@
-# Quality & CI
-
-## CI Pipeline
-
-Run all checks before pushing:
-
-```bash
-task ci
-```
-
-This runs, in order:
-
-1. **Sync check** — `dist/agent-src/` matches `src/` (non-`.md` files)
-2. **Condensation hashes** — Condensed `.md` hashes match source
-3. **Reference check** — No broken cross-references between files
-4. **Portability check** — No project-specific paths in shared files
-5. **Schema validation** — Frontmatter of every skill/rule/command/persona matches its JSON-Schema contract
-6. **Skill linter** — All skills, rules, commands pass structural validation
-7. **README linter** — README passes quality checks
-8. **Tests** — All bash + Python tests pass
-9. **Consistency** — No uncommitted changes from generated outputs
-
----
-
-## Skill Linter
-
-The linter (`scripts/skill_linter.py`) validates:
-
-- **Required structure** — YAML frontmatter, description, triggers
-- **Frontmatter schema** — Each artefact type has a JSON-Schema in `scripts/schemas/`; violations surface as `schema_<rule>` errors (see [frontmatter contract](../agents/reference/docs/frontmatter-contract.md))
-- **Anti-patterns** — Procedural rules in behavior rules, overlong skills, scope creep
-- **Condensation quality** — Key sections preserved after condensation
-
-Schema validation also runs standalone via `task validate-schema` — fast
-fail before the full linter.
-
-### Quality levels
-
-| Level | Meaning |
-|---|---|
-| **PASS** | Meets all requirements |
-| **WARN** | Advisory — may need attention but not blocking |
-| **FAIL** | Must be fixed before merge |
-
-### CI integration
-
-- GitHub Actions runs the linter on every PR
-- Results are posted as PR comments with quality counts
-- **0 FAIL required** — no merge with failures
-
----
-
-## Condensation System
-
-Content flows from verbose (`src/`) to condensed (`dist/agent-src/`),
-which is then projected into `.augment/` for Augment Code.
-
-### Rules
-
-- Source of truth is **always** `src/`
-- Never edit `dist/agent-src/` or `.augment/` directly
-- The `/condense` command produces token-efficient output
-- Condensation hashes track which files have been condensed
-
-### Verification
-
-```bash
-task sync-check          # Non-.md files in sync?
-task sync-check-hashes   # .md hashes current?
-task check-condensation   # Condensation quality OK?
-task lint-skills-pairs   # Source vs condensed comparison
-```
-
-### Fixing
-
-```bash
-task sync                # Copy non-.md files
-task sync-mark-all-done  # Mark all hashes as current (after manual condense)
-task consistency-fix     # Regenerate ALL derived outputs
-```
-
----
-
-## Runtime artifacts
-
-Skills dispatched via `scripts/runtime_dispatcher.py run --skill NAME --output FILE`
-write a typed `ExecutionResult` JSON (exit code, stdout, stderr, duration,
-artifacts) to the given path. In CI, the two pilot skills `lint-skills`
-and `check-refs` write to `agents/runtime/reports/runs/` and
-`scripts/ci_summary.py` renders them into the GitHub Step Summary so
-failures are visible on the PR page.
-
-No data is auto-injected into agent context and no persistent metrics,
-feedback, or audit logs are collected.
-
----
-
-← [Back to README](../README.md)

package/docs/readme-split-plan.md

@@ -1,102 +0,0 @@
-# README three-audience split — plan
-
-Annotated outline for `P2.2a` in
-[`road-to-proof-not-features.md`](../agents/roadmaps/road-to-proof-not-features.md).
-Decides the **information architecture**, not the prose. No content
-rewrite happens in this step; `P2.2b` applies the mapping.
-
-## Target headings (top of README, in order)
-
-1. **Use it in your project** — anchor `#use-it`
-2. **Prove it** — anchor `#prove-it`
-3. **Contribute** — anchor `#contribute`
-
-Each branch opens with one paragraph + one primary CTA. AI Council is
-not mentioned in any branch (verified by `P3.4`).
-
-### Anchor-stability promise
-
-`P2.2b` must keep these existing anchors intact so external inbound
-links survive:
-
-| Anchor today | Lives under (new) | Why |
-|---|---|---|
-| `#quickstart` | `#use-it` | npm/composer search results, social links |
-| `#supported-tools` | `#use-it` | most-cited section on the web |
-| `#what-your-agent-is-asked-to-do` | `#prove-it` | linked from blog posts |
-| `#documentation` | `#use-it` | docs portal entry |
-| `#development` | `#contribute` | contributor guides |
-
-Other section anchors may be renamed; `lint-readme` checks the table
-above and the three new audience anchors only.
-
-## Block-by-block mapping
-
-Every existing top-of-README block, in source order, mapped to
-exactly one branch. "Drop" = block is retired; "Move" = relocated as-
-is; "Reframe" = block stays but its lead-in / CTA changes (still no
-copy rewrite in this step — the reframe direction is decided here,
-applied in `P2.2b`).
-
-| # | Block (current heading) | Lines | Branch | Action | Notes |
-|---|---|---|---|---|---|
-| 1 | Title + tagline + stats badge | 1–13 | — | Keep above branches | Survives unchanged; counts updated by `update_readme_counts`. |
-| 2 | `## Start here` (three-paths table) | 15–25 | — | **Drop** | Replaced by the three branch sections themselves; rows map cleanly: `/onboard` → Use, `task ci` → Contribute, `task generate-tools` → Use. |
-| 3 | `## Quickstart` lead-in | 27–39 | Use it | Move | Becomes the opening paragraph under `#use-it`. |
-| 4 | `### For teams (recommended)` | 40–79 | Use it | Move | Primary CTA for `#use-it`. |
-| 5 | `### Pick specific AIs` | 81–101 | Use it | Move | Stays under Quickstart subtree. |
-| 6 | `#### Global install` | 103–124 | Use it | Move | Subsection of Pick specific AIs. |
-| 7 | `### For individual use (optional)` | 126–144 | Use it | Move | Alternate install path. |
-| 8 | `### Self-hosted MCP on Cloudflare` | 146–226 | Use it | Move | Operator install path; deep but consumer-facing. |
-| 9 | `#### Lock your Worker behind Bearer` | 196–213 | Use it | Move | Subsection of MCP block; stays nested. |
-| 10 | `### Optional: persistent agent memory` | 228–247 | Use it | Move | Companion package install. |
-| 11 | `## 2-minute demo: /implement-ticket` | 251–285 | Prove it | Move | Flagship evidence surface. Primary CTA for `#prove-it`. |
-| 12 | `### Sibling entrypoint: /work` | 287–316 | Prove it | Move | Same engine, second envelope. |
-| 13 | `### Product UI track` | 318–347 | Prove it | Move | Third evidence surface. |
-| 14 | `## What your agent is asked to do` | 351–365 | Prove it | Move | Intent table — proof of behaviour, not features. |
-| 15 | `## What this package is — and what it isn't` | 369–398 | Prove it | Move | Scope-honesty surface; loadbearing for the "proof" framing. |
-| 16 | `## You don't need everything` (cost profiles) | 402–423 | Prove it | Reframe | Currently sits as "feature" prose; the new framing is "proof that the package shrinks to fit". |
-| 17 | `## Who this is for` (stack coverage) | 427–439 | Prove it | Move | Honest depth claim — also evidence-side. |
-| 18 | `## Featured Skills` | 443–462 | Use it | Move | Catalog teaser → consumer surface. |
-| 19 | `## Featured Commands` | 466–481 | Use it | Move | Catalog teaser → consumer surface. |
-| 20 | `## Supported Tools / Project-installed` | 487–527 | Use it | Move | Per-tool install matrix. |
-| 21 | `## Supported Tools / Plugin-installed` | 529–541 | Use it | Move | Subsection. |
-| 22 | `## Supported Tools / Cloud / Hosted-agent` | 543–558 | Use it | Move | Subsection. |
-| 23 | `## Core Principles` | 562–570 | Prove it | Move | Behavioural floor — proof-side. |
-| 24 | `## Documentation` (index table) | 574–589 | Use it | Move | Doc portal entry. |
-| 25 | `### Maintainer telemetry (opt-in)` | 591–608 | Contribute | Move | Engagement measurement — maintainer / contributor surface. |
-| 26 | `### Context-aware command suggestion` | 610–629 | Use it | Move | Consumer-facing feature toggle. |
-| 27 | `## Development` | 633–642 | Contribute | Move | Primary CTA for `#contribute`. |
-| 28 | `## Requirements` | 644–649 | Use it | Move | Install gate — Use-side, not Contribute. |
-| 29 | `## License` | 651–653 | — | Keep at bottom | Footer; outside the three branches. |
-
-## Branch outlines (post-migration shape)
-
-### `## Use it in your project`
-
-Opening paragraph: one-line "Two minutes from npx to a better-behaved
-agent." Primary CTA: `npx @event4u/agent-config init`. Children:
-Quickstart subtree (#3–#7), MCP operator path (#8–#9), optional memory
-(#10), Featured Skills + Commands (#18–#19), Supported Tools (#20–#22),
-Documentation (#24), Command suggestion (#26), Requirements (#28).
-
-### `## Prove it`
-
-Opening paragraph: one-line "What the agent actually does, with
-evidence." Primary CTA: `/implement-ticket` demo (#11). Children:
-`/work` (#12), Product UI track (#13), Intent table (#14), Scope
-statement (#15), Cost profiles reframed (#16), Stack coverage (#17),
-Core Principles (#23).
-
-### `## Contribute`
-
-Opening paragraph: one-line "Editing rules, skills, commands — the
-contributor loop." Primary CTA: `task ci` (#27). Children: Maintainer
-telemetry (#25). External links: `CONTRIBUTING.md`, `AGENTS.md`,
-`docs/development.md`.
-
-## Verification (P2.2c preview)
-
-Grep-based test asserts `## Use it in your project`, `## Prove it`,
-`## Contribute` appear in that order. `lint-readme` keeps anchor
-stability for the rows in the Anchor-stability promise table.

package/docs/recruits/_template.md

@@ -1,81 +0,0 @@
-# Recruit — `<short-handle>`
-
-> **step-13 Phase 1 intake template.** One file per recruit. Filename:
-> `<YYYY-MM-DD>-<source>-<handle>.md` (e.g. `2026-05-20-indiehackers-jsmith.md`).
-> The maintainer fills this in **before** the recruit's first session; the
-> session-log section gets appended live during the walkthrough.
-
-## Identity & source
-
-- **Handle / display name:** `<as-they-want-to-be-credited>`
-- **Source channel:** (indie-hackers | r/ContentWritingJobs | product-hunt | direct-dm | other)
-- **First contact:** YYYY-MM-DD via `<thread-url-or-DM-context>`
-- **Role / self-description:** `<one-line, in their words>`
-- **User-type fit:** (consultant | creator | founder | finance | ops | gtm | other)
-- **Tool host they already use:** (claude-desktop | claude-code | cursor | windsurf | copilot | chatgpt-web | none)
-
-## Consent
-
-- **Attribution:** (full-name-OK | first-name-OK | role-only | fully-anonymous)
-- **Screenshot publication:** (yes | yes-with-redaction | no)
-- **Verbatim quote publication:** (yes | yes-with-review | no)
-- **Case-study publication if outcome lands:** (yes | maybe-revisit | no)
-- **Consent record:** `<link-to-dm-or-email-thread-or-signed-form>`
-
-> Consent gate per step-13 Phase 1 row 3 — a recruit without an explicit
-> consent record cannot anchor `agents/evidence/eval-findings/`. Anonymised
-> finding is acceptable; missing consent record is not.
-
-## Pre-session readiness
-
-- [ ] Recruit has Claude Desktop installed *(or equivalent MCP host)*
-- [ ] Recruit has a real task ready to bring to the session
-- [ ] Maintainer has [`docs/mcp-server.md`](../mcp-server.md) open in another tab
-- [ ] Maintainer has stopwatch / screen-recording ready for the install-time
-  measurement (Phase 1 row 2 — `< 10 minutes` gate)
-
-## Session log
-
-Append-only during the walkthrough. Timestamp every observation;
-"silent" minutes are also a signal.
-
-```
-HH:MM  start — recruit shares screen, opens Claude Desktop
-HH:MM  install step 1 (`task mcp:setup`): outcome / friction / quote
-HH:MM  install step 2 (Claude Desktop config paste): outcome / friction / quote
-HH:MM  first invocation attempt: prompt / which skill fired / verdict
-...
-HH:MM  end — total install time: __ min __ s
-```
-
-## Friction inventory
-
-At least **two** real friction points (per step-12 Phase 7 L130 spirit).
-Empty list = the session wasn't real.
-
-1. <where they stalled, in their words> → <what we fixed / parked>
-2. <...>
-
-## Outcome verdict
-
-- **MCP setup time:** `__ minutes __ seconds` (gate: `< 10 min`)
-- **First useful invocation reached without terminal?:** (yes | no | partial)
-- **Recruit would recommend to a peer?:** (yes | maybe | no | declined-to-answer)
-- **Eligible to anchor `agents/evidence/eval-findings/`?:** (yes | no — reason)
-
-## Cross-links
-
-- **Eval-finding file (if logged):** `agents/evidence/eval-findings/YYYY-MM-DD-<slug>.md`
-- **Case-study file (if subject opted in):** `docs/case-studies/YYYY-MM-DD-<type>-<slug>.md`
-- **Roadmap rows closed by this session:**
-  - step-13 P1 row 1 (recruit) — yes / no
-  - step-13 P1 row 2 (`< 10 min` gate) — yes / no
-  - step-13 P1 row 3 (consent record) — yes / no
-
-## Maintainer follow-up
-
-- [ ] Eval-finding committed
-- [ ] Recruit thanked + sent the published finding link
-- [ ] Skill-description deltas filed *(any friction that maps to a
-  skill description widening or a missing trigger phrase)*
-- [ ] Case-study slot offered *(if outcome was useful + consent allows)*

package/docs/release-runbook.md

@@ -1,141 +0,0 @@
-# Release runbook — cut a correct release from written steps alone
-
-> **Bus-factor doc (road-to-maintainer-bus-factor Phase 3).** The goal: a second
-> maintainer — or the current one after a long gap — can cut a correct release by
-> following THIS document, with no tribal knowledge. Every step maps to a real
-> gate or command in the repo; nothing here is aspirational. Companion:
-> [`succession.md`](succession.md) (secrets, operator-gated steps, "healthy main").
->
-> **Source of truth for the mechanism:** [`src/scripts/release.ts`](../src/scripts/release.ts)
-> (the shared pipeline) + [`.github/workflows/release.yml`](../.github/workflows/release.yml)
-> (the CI entry) + [`ADR-113`](decisions/ADR-113-ci-native-release-label-trigger.md).
-> If this runbook and those disagree, THEY win and this doc is stale — fix it.
-
-## 0. Mental model
-
-There is **one** release pipeline (`src/scripts/release.ts`) reached by **two**
-entry points that produce the identical result:
-
-| Entry point | How | When to use |
-|---|---|---|
-| **Local** | `task release` (interactive) | You want to watch it, or CI dispatch is unavailable. |
-| **CI-native** | merge a PR labeled `release` / `release:major` / `release:minor` / `release:patch` | The normal path — the merge triggers [`release.yml`](../.github/workflows/release.yml), which runs `release.ts --ci`. |
-
-`release` auto-detects the semver bump from Conventional Commits since the last
-tag; `release:major|minor|patch` forces it. A manual/recovery entry exists via
-the **workflow_dispatch** on `release.yml` (inputs: `bump`, `version`,
-`dry_run`, `resume`).
-
-## 1. Pre-flight (before you start)
-
-- [ ] `main` is green on the latest commit (all required checks — see
-      [`branch-protection-policy.md`](contracts/branch-protection-policy.md)).
-- [ ] Working tree clean, on `main`, `origin/main` in sync
-      (`release.ts` step 1 enforces this and aborts otherwise).
-- [ ] `gh` authenticated (`gh auth status`).
-- [ ] The target tag does **not** already exist (step 1 checks; use `--resume`
-      to recover a partial run — see § 5).
-- [ ] You have read [`succession.md`](succession.md) if any secret-gated
-      downstream (npm publish, cloud deploy) must succeed this release.
-- [ ] The release satisfies [`release-sizing.md`](contracts/release-sizing.md) —
-      one primary product goal, and a `Rollback:` line for every new /
-      substantially reworked subsystem (gate: `src/scripts/lint_changelog_rollback.ts`).
-
-## 2. The pipeline — what `release.ts` does (9 steps)
-
-Both entry points run these in order. Each step prints what it will do before
-doing it, so a crash localises to a step.
-
-1. **Preflight** — on `main`, clean tree, `origin` in sync, `gh` present, target
-   tag absent.
-2. **Plan** — compute the new version, parse Conventional Commits since the last
-   tag, render the CHANGELOG section.
-3. **Confirm** — show the preview and ask once. `--yes` skips; `--ci` always
-   requires `--yes` (no terminal in CI).
-4. **Branch + bump** — create `release/X.Y.Z`; update `package.json`,
-   `.claude-plugin/marketplace.json`, `CHANGELOG.md`; then run
-   `task release-prepare` so pack manifests + tool projections pick up the new
-   version (skip this and the PR's own consistency check fails — PR #226
-   post-mortem).
-5. **Commit + push** — commit `release: X.Y.Z`, push the branch, open the PR.
-6. **Wait for CI** — `gh pr checks --watch` (skippable with `--no-wait`).
-7. **Merge** — `gh pr merge --merge --delete-branch`.
-8. **Tag main** — fast-forward `main`, tag the merge commit, push the tag.
-9. **GitHub Release** — `gh release create X.Y.Z --notes <changelog>`. Under
-   `--ci`, also dispatches `release-guard.yml` + `publish-npm.yml` +
-   `cloud-release.yml` (a bot-pushed tag does not trigger them on its own —
-   GitHub's `GITHUB_TOKEN` recursion guard).
-
-## 3. The two ways to run it
-
-### A. CI-native (normal)
-
-1. Open your change PR as usual; get it green + merged into `main`.
-2. To release, add a **`release`** label (or `release:minor` etc.) to a PR and
-   merge it. `release.yml` fires on `pull_request: closed` (merged) and runs
-   `release.ts --ci`.
-3. **Manual checkpoint (only without `RELEASE_PR_TOKEN`):** GitHub's
-   bot-created-PR safeguard queues the release PR's required checks in an
-   approval-required state. Go to the release PR → **"Approve workflows to
-   run"** once. The job's `gh pr checks --watch` then proceeds. This is a
-   deliberate production-release checkpoint, not a bug (see
-   [`branch-protection-policy.md`](contracts/branch-protection-policy.md)).
-   Configuring `RELEASE_PR_TOKEN` removes it (see [`succession.md`](succession.md)).
-4. Watch the `release.yml` run to green. It merges the release PR, tags, cuts
-   the GitHub Release, and dispatches the downstream workflows.
-
-### B. Local (`task release`)
-
-1. `task release` — interactive; it runs the same 9 steps and asks once at
-   step 3. Use `--as minor` / `--version X.Y.Z` to override the bump; `--dry-run`
-   to preview with zero git/gh mutations.
-2. Watch it merge + tag. The tag push triggers `publish-npm.yml` directly (local
-   runs use your user token, so no recursion guard applies).
-
-## 4. Post-release verification
-
-- [ ] `git log --first-parent origin/main -1` shows the `release: X.Y.Z` merge.
-- [ ] `gh release view X.Y.Z` exists with the CHANGELOG notes.
-- [ ] `publish-npm.yml` succeeded (npm has the new version) — see
-      [`succession.md`](succession.md) for the token dependency.
-- [ ] Downstream deploys (`cloud-release.yml`, site) green if this release
-      touched them.
-- [ ] `main` is green post-merge (no drift gate red: `release-drift.yml`,
-      `release-guard.yml`).
-
-## 5. Recovery — a partial or failed release
-
-`release.ts` is **idempotent under `--resume`**: it probes existing state
-(branch, commit, PR, tag, GitHub Release) and skips completed steps.
-
-- Re-run `release.yml` via **workflow_dispatch** with `resume: true`, or locally
-  `task release -- --resume`.
-- Firing the `release` label path twice is a clean no-op (the `--ci`
-  nothing-to-release short-circuit).
-- If a downstream dispatch (npm/cloud) failed but the tag + Release exist, re-run
-  that specific workflow from the Actions tab — do **not** re-cut the release.
-
-## 6. What can go wrong (known checkpoints)
-
-- **Release PR checks stuck "expected"** → the approve-workflows checkpoint in
-  § 3.A step 3. Not a failure; click approve.
-- **Consistency check red on the release PR** → step 4's `task release-prepare`
-  did not run or pack manifests drifted; re-run it on the release branch.
-- **Tag exists but no npm version** → `publish-npm.yml` did not fire or failed;
-  re-run it (§ 5). Never delete + re-push the tag to "retry".
-- **`main`/`origin` diverged mid-release** → stop; resolve the divergence with
-  the `git-workflow` skill's Divergent-State Recovery procedure first, then
-  `--resume`.
-
-## 7. Verify this runbook is not stale
-
-```bash
-# every command / gate this runbook names still exists:
-test -f src/scripts/release.ts && test -f .github/workflows/release.yml
-grep -q "release-prepare" Taskfile.yml
-./scripts-run src/scripts/check_release_pr_shape --help >/dev/null 2>&1 || true
-```
-
-A written-steps-only **dry run** (cut a no-op release following ONLY this doc,
-no tribal knowledge) is the real freshness test — see the roadmap's Phase 3
-dry-run step (maintainer-run; every gap found is a fix to this file).

package/docs/role-experiences.md

@@ -1,19 +0,0 @@
-# Role experiences — taglines at a glance
-
-> **Generated** by `scripts/generate_role_experiences_catalog.py` from
-> `agents/roles/<role>/index.md` — do NOT hand-edit. Taglines are the
-> existing role-level strings (validated by `lint_role_experiences.py`,
-> rendered in the GUI workspace); this page surfaces them in a catalog.
-
-Each row links to the full role experience (persona · three first tasks ·
-packs). The catalog never duplicates the body — see
-[`docs/contracts/role-experience.md`](contracts/role-experience.md).
-
-| Role | Tagline | Status |
-|---|---|---|
-| [Consultant / advisor](../agents/roles/consultant/index.md) | Client briefs, investor memos, and deck outlines — refined before the meeting, not rewritten after. | `beta-internal` |
-| [Content creator](../agents/roles/content-creator/index.md) | From a one-line idea to a stitched short — voice-locked, character-locked, provider-agnostic. | `beta-internal` |
-| [Galabau owner](../agents/roles/galabau/index.md) | Drafting customer offers and project briefs without a project manager between you and the document. | `beta-internal` |
-| [Team leader](../agents/roles/leadership/index.md) | Summarise weekly status, write the risk memo, structure the decision before the meeting. | `beta-internal` |
-| [Sales rep](../agents/roles/sales/index.md) | Answer customer questions, draft offers, and prep discovery calls — voice-locked, structured, fast. | `beta-internal` |
-| [Support agent](../agents/roles/support/index.md) | Summarise the ticket, draft the reply, flag the escalation — without rewriting the customer's words. | `beta-internal` |

package/docs/safety.md

@@ -1,30 +0,0 @@
-# Data governance & domain safety
-
-`agent-config` ships **12 domain-safety rules** (`src/rules/domain-safety-*.md`) that act as a per-domain output floor — PII redaction, disclaimer requirements, and retention guidance. Rules fire automatically via the router when their triggers match.
-
-## Surface → rule(s) → floor
-
-| Surface | Rule(s) | Floor |
-|---|---|---|
-| Support / CRM drafts | `domain-safety-pii-support` · `domain-safety-retention-support` | Redact customer names, emails, phones, account IDs to placeholders before output |
-| Finance / invoicing | `domain-safety-pii-finance` · `domain-safety-retention-finance` | Redact counterparty PII and bank identifiers; flag retention under audit hold |
-| Recruiting | `domain-safety-pii-recruiting` | Redact candidate PII from notes, scorecards, rejection emails |
-| Marketing testimonials | `domain-safety-pii-marketing` | Require consent record before customer-identifying copy ships |
-| Legal · financial · medical · consulting drafts | `domain-safety-disclaimer-*` | "Not legal/financial/medical advice" disclaimers; refuse diagnostic / dosage / specific tax positions |
-| Logs · exports | `domain-safety-logging-pii-floor` · `domain-safety-export-redact` | No raw PII in logs or exports; allowlist-driven structured fields only |
-
-## How the floor is enforced
-
-- Each rule declares `applies_to_user_types:` in frontmatter — rules load only when the matching user-type is active (forward-compatible with the user-types axis shipping in `step-9-user-types-axis`).
-- Each rule routes to `skill:privacy-review` as the baseline deeper-regime check (GDPR · CCPA · HIPAA).
-- The set is opt-in by domain, never overrides higher Iron Laws (`non-destructive-by-default`, `commit-policy`, `scope-control`).
-
-## Related skills
-
-- [`privacy-review`](../src/skills/privacy-review/SKILL.md) — end-to-end data-flow review for a regulatory regime (GDPR / CCPA / HIPAA).
-- [`data-handling-judgment`](../src/skills/data-handling-judgment/SKILL.md) — classification, retention, cross-border transfer, DSR workflow.
-
-## See also
-
-- [`non-destructive-by-default`](../.augment/rules/non-destructive-by-default.md) — Hard Floor that overrides every domain-safety carve-out.
-- [`security-sensitive-stop`](../.augment/rules/security-sensitive-stop.md) — threat-model before touching auth / billing / tenant boundaries / uploads.

package/docs/second-brain-scope.md

@@ -1,116 +0,0 @@
-# Second-brain scope — what it is, what it is not, what is measured
-
-> The agent-config "second-brain" substrate is **agent-facing memory**, not a
-> human personal-knowledge-management (PKM) tool. This page states the boundary
-> honestly and binds every capability word to evidence. It follows the
-> `docs/proof.md` § 4 discipline: the category column describes human-PKM only
-> by what is publicly observable, never as a counter-claim to a named project.
->
-> Roadmap: `road-to-second-brain-delta-proof`. Verdict of record:
-> `agents/settings/contexts/second-brain-delta-verdict.md` (council 2026-07-07).
-
-## The honest status (2026-07-09 — measured PASS, bounded)
-
-The substrate is **built** (typed knowledge dirs, INDEX generator, retrieval
-protocol, `hot_context_hook` working-memory continuity across compaction,
-`fold_intake`, contradiction surfacing), and the cross-session recall *delta*
-is now **measured** — a real, placebo-controlled lift, honestly scoped.
-
-- **The measurement rig** — a deterministic multi-session recall corpus
-  (`internal/bench/second-brain/corpus/`) + a scorer
-  (`src/scripts/second_brain_score.ts`) with no model-in-the-loop grading.
-- **The paired run (Phase 2)** — `memory-on` / `memory-off` / `placebo` on a
-  fixed host (claude-haiku-4-5), 9 tasks × 3 seeds (81 calls). Result:
-  memory-on **27/27**, no-memory **10/27**, equal-byte placebo **9/27**;
-  memory-on beats BOTH, sign test **p = 0.031** for each pairing → **PASS**.
-  Full report: `internal/bench/reports/second-brain-delta.json`
-  (claim `second-brain-recall-lift`).
-- **Where the lift lives** — it concentrates on the retrieval-accuracy tasks
-  where the prior fact is available ONLY from memory (memory-on 3/3, baseline
-  0/3). It **ties** on the three tasks whose k+1 prompt already self-contains
-  the signal (a correction stated in-prompt, or a contradiction the prompt
-  names) — exactly where memory is not the only source. memory-on never loses.
-
-### The scoping caveat (stated, not buried)
-
-The Phase-2 delta is the **context-value upper bound**: the corpus is
-one-fact-per-task, so memory-on injects the exact fact (perfect retrieval). It
-shows that **the right prior fact, surfaced, lets the model answer — and that
-this beats both no memory and equal-byte noise** (the placebo isolates mechanism
-from mere extra context).
-
-**The retrieval-precision follow-up removed the perfect-retrieval assumption**
-(2026-07-09, claim `second-brain-retrieval-precision`,
-`internal/bench/reports/second-brain-retrieval.json`). Against a populated store
-whose distractors deliberately share query keywords with the needed decision,
-the REAL `memory_lookup` retrieval recalls the needed decision into the top-5 in
-**9/9** cases, and the model disambiguates it from the co-injected confusers —
-**retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27**
-(sign test p=0.008 both). **Named limit (honest):** the keyword scorer
-**recalls but does not rank** — mean tie-set 3.3 entries share the top score,
-ties broken by store order, not relevance. So recall into the top-k holds *at
-this scale*; once more than k entries share a keyword it would degrade — which
-is exactly the discrimination gap the SQLite-FTS5 activation path (ADR-116)
-exists to close. The public claims are scoped to exactly this.
-
-**Second named limit (separator recall, found 2026-07-10 in a labelled replay
-of real maintainer queries):** `_score()` matches raw substrings, so a query
-key whose token separator differs from the stored field misses entirely —
-`ai_council`, `roadmap-progress`, `force-push` score 0 against space-normalized
-`key` fields that spaced variants (`ai council`) hit at 0.8. The precision
-measurement above did not probe this class (its confusers share exact
-keywords), so it is scoped OUT of the precision claim. Deliberately not
-hot-fixed: naive scoring is locked until the scale tripwire (the archived
-retrieval-economy roadmap's D5), and the FTS5 unicode61 tokenizer splits on
-separators, closing this structurally at activation time. Reproduce:
-`memory_lookup --types product-rules --key "ai_council"` vs `--key "ai council"`
-against any populated store.
-
-## What it IS (measured lift, bounded as above)
-
-| Capability | What it does | Evidence status |
-|---|---|---|
-| Working-memory continuity | `hot_context_hook` re-injects a bounded, deterministic cache across session boundaries and Claude Code compaction | mechanism shipped; recall lift **measured (bounded PASS)** |
-| Promotable knowledge cards/pages | typed dirs + INDEX + retrieval protocol, with redaction + team-share gate | mechanism shipped; recall lift **measured (bounded PASS)** |
-| Contradiction surfacing | a session that contradicts a prior decision is flagged on promote | mechanism shipped; ties in-prompt, lift where memory is the only source |
-
-## What it is NOT
-
-- **Not a human-browsable knowledge graph.** There is no `.obsidian/` config,
-  no enforced `[[wikilink]]` convention, no link-density value thesis. An
-  editable vault view was evaluated and **rejected** (the dual-write hazard:
-  an external edit that never commits silently diverges the INDEX and
-  recurrence counters). Browsability, if demanded, is a read-only static
-  render — not an editable vault.
-- **Not an Obsidian (or any named PKM) replacement.** The category — a
-  human Markdown graph browsed in an editor, value proportional to
-  link-density, hybrid human-facing retrieval — is a *different product* for a
-  *different consumer* (a person, not an agent). This package writes
-  agent-facing memory; it does not serve a human graph browser.
-- **Not an unbounded accuracy multiplier** — the recall lift is measured but
-  scoped to the context-value upper bound (see honest status), not proven
-  retrieval precision under a large store.
-
-## Interop, not competition (export declined, on the record)
-
-The Phase-2 paired run did show a real (bounded) lift, which unlocks the
-optional one-way export (promoted cards → Obsidian-compatible Markdown). It is
-**deliberately not built**: the delta-verdict of record
-(`agents/settings/contexts/second-brain-delta-verdict.md`, council 2026-07-07)
-**rejected** Obsidian compatibility — the dual-write hazard (an external edit
-that never commits silently diverges the INDEX + recurrence counters) outweighs
-the browsing convenience, and the measured lift is a bounded context-value
-result, not a retrieval-precision proof that would justify a new external
-surface. If a human-PKM bridge is ever wanted, the sanctioned path is a
-read-only static render, not an editable vault. Positioning stays: agent-config
-writes agent-facing memory; it does not replace a human PKM.
-
-## Verify
-
-```bash
-./scripts-run src/scripts/second_brain_score            # corpus summary
-./scripts-run src/scripts/second_brain_score --dry-run  # scorer correct + discriminating, no spend
-```
-
-The paired-run delta, when authorized, pins to
-`internal/bench/reports/` and updates `docs/CLAIMS.md` + `docs/benchmark.md`.

package/docs/self-review-gate.md

@@ -1,65 +0,0 @@
-# Self-review gate (dogfooded PR review)
-
-The package reviews its own PRs with the exact machinery it ships —
-[`adversarial-review`](../src/skills/adversarial-review/SKILL.md) +
-[`agent-security-review`](../src/skills/agent-security-review/SKILL.md) — via
-[`.github/workflows/self-review-gate.yml`](../.github/workflows/self-review-gate.yml)
-and [`src/scripts/self_review_gate.ts`](../src/scripts/self_review_gate.ts).
-
-`road-to-maintainer-bus-factor` Phase 1.
-
-## Current status — ADVISORY, inert without a secret
-
-This is an **honest floor, not independent human review**, and today it is
-**advisory + inert-without-secret**. Do not read it as "every PR is
-AI-reviewed" — that is only true once the maintainer arms it (below).
-
-| Job | Runs | Spend | Blocks merge |
-|---|---|---|---|
-| `gate-dry-run` | every PR | none (no API) | never — prints the review plan only |
-| `live-advisory` | every PR **iff** `ANTHROPIC_API_KEY` is set | one review call | never — posts findings, records what *would* block |
-
-Without the `ANTHROPIC_API_KEY` repo secret, `live-advisory` is a **logged
-no-op** (never a failing check) — exactly the `cross-model-canary.yml` pattern.
-
-## The teeth (defined + wired, not yet armed)
-
-`self_review_gate.ts` exposes pure, unit-tested:
-
-- `classifyBlocking(finding)` — a finding is merge-blocking **iff**
-  `kind ∈ {security, claim}` **and** `severity ∈ {critical, high}`. Style and
-  correctness findings, and low/medium security findings, advise only. (Council
-  2026-07-08, claude-sonnet-4-5 + gpt-4o: a 100 %-blocking gate at
-  solo-maintainer token cost gets ignored or gamed — block only on the narrow
-  security/claim × high+ intersection.)
-- `gateVerdict(findings, {enforce})` — mirrors
-  `check_quality_regression.gateVerdict`: `0` pass / `2` block. Shipped
-  `enforce: false` (advisory always returns `0` and reports the would-block
-  set).
-
-## Escalation on large / claim-affecting diffs
-
-The two in-session lenses are a floor. A **large** diff (≥ 400 changed lines
-across reviewable files) or one that touches a **claim-affecting surface**
-(`docs/CLAIMS.md`, `docs/proof.md`, `docs/comparison.yaml`, or `README.md`)
-warrants the full `ai-council` advisor panel — a spend-bearing multi-model run.
-
-Per blocker `self-review-gate-cost`, the paid council stays governed by the
-standing spend-authorization discipline **at run time**. So the gate does not
-fire council calls itself: `escalationReasons(files, changedLines)` (pure,
-unit-tested) DETECTS the condition, the dry-run plan prints it, and the posted
-review RECOMMENDS a maintainer `/council:pr` run. Detection is deterministic
-and zero-spend; the multi-model run is the maintainer's run-time act.
-
-## Arming it (maintainer, one flip)
-
-1. Add the `ANTHROPIC_API_KEY` repo secret (per-PR budget sign-off) — turns
-   `live-advisory` from no-op into a real dogfooded review.
-2. Pass `--enforce` in the live job to arm the teeth (block on
-   security/claim × high+).
-3. Require the `Self-review gate` check in branch protection
-   (`road-to-maintainer-bus-factor` Phase 2) so even solo merges pass the gate.
-4. Record the floor CLAIM on the proof page **once it is live** — not before
-   (an inert gate is not a passed gate).
-
-Blocker `self-review-gate-cost` (maintainer-owned) gates steps 1–2.