@event4u/agent-config 8.1.0 → 8.3.0

package/docs/decisions/ADR-113-ci-native-release-label-trigger.md

@@ -0,0 +1,201 @@
+---
+adr: 113
+status: accepted
+date: 2026-07-08
+decision: ci-native-release-label-trigger
+supersedes: —
+superseded_by: —
+phase: road-to-ci-native-release · Phase 1
+---
+
+# ADR-113 — CI-native release path, triggered by a `release` label on a merged PR
+
+## Status
+
+**Accepted** · 2026-07-08.
+
+## Context
+
+`task release` (`src/scripts/release.ts`) is a fully interactive, local
+9-step pipeline: preflight → plan → confirm → branch+bump → commit/push+PR →
+wait for CI → merge → tag → GitHub Release. The back half is already CI
+(`publish-npm.yml`, `cloud-release.yml`, `release-guard.yml` all trigger on
+the pushed numeric tag), but a maintainer must run the front half from a
+terminal. This ADR adds an unattended, CI-native entry point alongside
+`task release` — not a replacement.
+
+## Decision
+
+1. **Trigger: a `release` / `release:major` / `release:minor` /
+   `release:patch` label on a PR, checked at merge time**
+   (`pull_request: types: [closed]`, job-guarded on `merged == true` +
+   an exact label match). `release` auto-detects the bump from
+   Conventional Commits since the last tag (same logic `task release`
+   uses); the `release:*` variants force the bump. `workflow_dispatch`
+   (with `bump` / `version` / `dry_run` / `resume` inputs) is the
+   manual/recovery entry for a release not tied to a PR merge.
+
+2. **The numeric `X.Y.Z` tag stays the pipeline's *output*, never its
+   input.** `publish-npm.yml`, `cloud-release.yml`, and
+   `release-guard.yml` all trigger on `push: tags:
+   [0-9]+.[0-9]+.[0-9]+` and assume the tagged commit already carries
+   the bumped `package.json` / `marketplace.json` / regenerated
+   projections. A tag-shaped trigger (hand-pushed numeric tag, or a
+   `cut-*` intent tag) was considered and rejected — see Alternatives.
+
+3. **One orchestration workflow (`release.yml`), not a prepare/finalize
+   split.** GitHub's `GITHUB_TOKEN` recursion guard means events caused
+   by the default token do not start new workflow runs (with narrow,
+   documented exceptions — see the bot-PR finding below). A
+   bot-auto-merged release PR would never trigger a separate
+   merge-listening "finalize" workflow. `release.yml` instead runs the
+   whole chain synchronously in one job, calling
+   `src/scripts/release.ts --ci` end-to-end — the exact same pipeline
+   `task release` runs locally, just non-interactively.
+
+4. **`release.ts` gains a `--ci` mode, not a rewrite.** `--ci` changes
+   exactly three things relative to the existing interactive path:
+   - the `gh`-auth preflight probe (`gh api repos/{slug} --jq .id`
+     instead of `gh api user --jq .login` — the default `GITHUB_TOKEN`
+     is an installation token and `gh api user` returns 403 for it even
+     when perfectly valid);
+   - a `nothing_to_release_ci` short-circuit (empty commits + no
+     explicit bump/version override → exit 0) so firing the label path
+     twice in a row is a clean no-op, not a spurious empty release;
+   - explicit post-release dispatch of `release-guard.yml`,
+     `publish-npm.yml`, and `cloud-release.yml` via their `tag` input,
+     because a `GITHUB_TOKEN`-pushed tag does not fire their
+     `push: tags:` trigger either.
+
+   Every other code path (bump inference, changelog-era rendering, the
+   10-step `execute()` sequence, all idempotent-resume probes) is
+   shared, unmodified, between `task release` and `release.yml`.
+
+5. **Token: `secrets.RELEASE_PR_TOKEN` with a `GITHUB_TOKEN` fallback.**
+   `release.yml` uses `${{ secrets.RELEASE_PR_TOKEN || secrets.GITHUB_TOKEN
+   }}` for checkout, git push, and `gh` auth. See the bot-PR-approval
+   finding below for why this matters and why the fallback is safe to
+   ship without the secret configured.
+
+## Finding — bot-created PRs need a manual "Approve workflows to run" click (no PAT)
+
+Verified against GitHub's own changelog and community docs (2026-06-11,
+["Bot-created pull requests can run workflows if
+approved"](https://github.blog/changelog/2026-06-11-bot-created-pull-requests-can-run-workflows-if-approved/)):
+when a workflow uses the default `GITHUB_TOKEN` to open or update a PR,
+the resulting `pull_request` events (`opened` / `synchronize` /
+`reopened`) DO create workflow runs for other `pull_request`-triggered
+workflows — but those runs sit in an **approval-required** state until a
+repo collaborator with write access clicks **Approve workflows to run**
+in the PR's merge box. This is a deliberate GitHub security control
+(distinct from, but related to, the fork-first-time-contributor approval
+gate), not a bug in this design.
+
+This repo's branch-protection ruleset (verified live via `gh api
+repos/event4u-app/agent-config/rulesets/17749383`) requires
+**zero** approving reviews (`required_approving_review_count: 0`) and
+exactly **one** required status check, `Sync + Generate Tools
+Consistency` (from `consistency.yml`, `pull_request`-triggered). That
+check does not run automatically on a `GITHUB_TOKEN`-opened release PR
+without the one-time approval click — so without `RELEASE_PR_TOKEN`, a
+release via the label path pauses at "waiting for checks" until a
+maintainer approves the run once per release.
+
+**Accepted as the default**, not worked around, because:
+
+- It requires zero new secrets and zero change to repo-wide security
+  settings (disabling the org-wide first-time-contributor approval
+  setting would lower security posture for every fork/bot PR, not just
+  release PRs — out of proportion to this problem).
+- A release is a production action; per this repo's own engineering
+  safety floor (`engineering-safety-floor` rule) and Hard-Floor stance
+  on deploys, a single human checkpoint before a release's own CI even
+  runs is arguably a feature, not friction.
+- `RELEASE_PR_TOKEN` (a fine-grained PAT or GitHub App installation
+  token with `contents: write` + `pull-requests: write` on this repo)
+  removes the approval requirement entirely — documented as the
+  zero-friction upgrade path in `release.yml`'s header comment. Adding
+  it is a maintainer action, not part of this ADR.
+
+## Verified facts (not assumed)
+
+- Branch protection ruleset `main protection` (id `17749383`):
+  `required_approving_review_count: 0`; required check =
+  `Sync + Generate Tools Consistency`; `bypass_actors` includes a
+  repository-role bypass. No human-review gate blocks a bot merge once
+  checks are green.
+- `consistency.yml` triggers on `pull_request` with path filters that
+  match every file a release PR touches (`package.json`,
+  `.claude-plugin/marketplace.json`, `CHANGELOG.md`, `dist/agent-src/**`,
+  `.augment/**`) — the required check fires (subject to the approval
+  gate above), it is not silently skipped.
+- No `RELEASE_PR_TOKEN`-shaped secret exists in the repo today (`gh
+  secret list`) — the fallback path is the one that ships by default.
+- `softprops/action-gh-release@v2`'s `overwrite_files` input defaults to
+  `true` — re-attaching the same-named cloud-release assets on a
+  dispatch-chain re-run is idempotent by construction, no extra guard
+  needed.
+- `npm publish` hard-rejects re-publishing an existing version — added a
+  `npm view @event4u/agent-config@<tag> version` pre-check to
+  `publish-npm.yml` so a double-dispatch (native tag-push trigger racing
+  the explicit dispatch, when `RELEASE_PR_TOKEN` IS configured) is a
+  clean skip, not a red run.
+
+## Consequences
+
+- Releasing needs exactly one human action: label a PR `release` (or a
+  `release:*` variant) and merge it. Without `RELEASE_PR_TOKEN`, one
+  additional "Approve workflows to run" click is needed once per
+  release on the auto-created release PR.
+- `task release` is unaffected — same script, same flags, same tests.
+  It remains the interactive/local path and the documented fallback if
+  the CI path misbehaves.
+- Three existing workflows (`release-guard.yml`, `publish-npm.yml`)
+  gained a `workflow_dispatch` input / idempotency guard respectively;
+  `cloud-release.yml` needed no change (already idempotent).
+- A future maintainer who configures `RELEASE_PR_TOKEN` gets a fully
+  unattended release with zero code changes required — the fallback
+  expression already prefers it.
+
+## Alternatives considered
+
+- **Hand-pushed numeric tag as the trigger.** Rejected: the tag-triggered
+  workflows require the tagged commit to already carry the bump: a
+  hand-pushed `X.Y.Z` on plain main fires them against the *un-bumped*
+  tree (red `release-guard`, wrong npm tarball), and the tag would then
+  have to be deleted and re-pushed onto the eventual bump-PR merge
+  commit — mutable tags are an anti-pattern (stale fetches, npm
+  provenance binds to the tag commit).
+- **A `cut-*` intent tag** (`cut-X.Y.Z` / `cut-auto` / `cut-major` / …)
+  in a separate namespace from the numeric tags. Functionally workable
+  (does not collide with the publish/guard tag patterns), but the
+  release label keeps the intent visible on the PR itself — reviewable,
+  revocable pre-merge, no second git-tag vocabulary to teach.
+- **`workflow_dispatch` as the sole/primary trigger**, no label. Loses
+  the "the intent to release lives on the PR, and is revocable until
+  merge" property that the label gives for free; kept as the
+  manual/recovery entry, not the primary path.
+- **Prepare + finalize workflow split** (one workflow opens the release
+  PR, a second listens for its merge and finalizes). Needs a
+  `RELEASE_PR_TOKEN`-class token as a *hard* requirement — under plain
+  `GITHUB_TOKEN`, the bot-merged PR's `pull_request: closed` event is
+  the SAME kind of GITHUB_TOKEN-caused event subject to the same
+  approval/recursion nuance, and splitting the pipeline across two
+  workflow boundaries adds a second place idempotency can drift. The
+  single-workflow design collapses this into one synchronous run using
+  the already-battle-tested `execute()` sequence.
+- **Disable the org-wide "require approval for first-time contributors"
+  setting** to remove the bot-PR approval gate without a PAT. Rejected:
+  it is an org-wide security posture change affecting every fork/bot PR
+  in the organization, not scoped to releases — disproportionate to
+  this problem; `RELEASE_PR_TOKEN` is the properly-scoped fix.
+
+## References
+
+- `.github/workflows/release.yml` — the orchestration workflow.
+- `src/scripts/release.ts` — the shared pipeline (`--ci` mode).
+- `docs/contracts/release-pr-gating.md`,
+  `docs/contracts/branch-protection-policy.md` — release-PR shape and
+  required-check contracts this design must keep satisfying.
+- [GitHub Changelog — Bot-created pull requests can run workflows if
+  approved (2026-06-11)](https://github.blog/changelog/2026-06-11-bot-created-pull-requests-can-run-workflows-if-approved/)

package/docs/decisions/INDEX.md

@@ -114,6 +114,9 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-108](ADR-108-open-source-forever-no-commercial-tier.md) | Open Source Forever No Commercial Tier | accepted | 2026-06-24 | — |
 | [ADR-109](ADR-109-subagent-v1-contract.md) | Subagent V1 Contract | accepted | 2026-07-04 | — |
 | [ADR-110](ADR-110-discipline-profile-resolution-locus.md) | Discipline Profile Resolution Locus | accepted | 2026-07-07 | — |
+| [ADR-111](ADR-111-canonical-glama-listing.md) | Canonical Glama Listing | accepted | 2026-07-07 | — |
+| [ADR-112](ADR-112-stdio-lite-stays-read-only.md) | Stdio Lite Stays Read Only | accepted | 2026-07-07 | — |
+| [ADR-113](ADR-113-ci-native-release-label-trigger.md) | Ci Native Release Label Trigger | accepted | 2026-07-08 | — |
 | [ADR-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)

package/docs/distribution/registry-submissions.md

@@ -34,7 +34,7 @@ the submission shape evolves; this file accumulates history.
 
 | # | Registry | Submission shape | Status | PR / form URL | Date | Maintainer notes |
 |---|---|---|---|---|---|---|
-| 1 | `punkpeye/awesome-mcp-servers` | One-line entry under agent-tooling section; PR via `scripts/mcp_registry_submit.sh` | `pending` | — | — | Scaffold ready. Run `bash scripts/mcp_registry_submit.sh --dry-run` once before live; the live path needs the maintainer's GitHub identity. |
+| 1 | `punkpeye/awesome-mcp-servers` | One-line entry under agent-tooling section; PR via `scripts/mcp_registry_submit.sh` | `submitted` | <https://github.com/punkpeye/awesome-mcp-servers/pull/9607> | 2026-07-07 | PR opened via the submit script (two script bugs fixed on the way: idempotent upstream remote, `--head OWNER:branch` format). Awaiting upstream review. |
 | 2 | `mcp.so` | Directory form submission (web form, no programmatic API) | `pending` | — | — | Form URL: <https://mcp.so/>. Submission shape: same one-line entry, paste into the form's `description` field. |
 | 3 | `mcpservers.org` | Directory form submission (web form, verify URL at submission time) | `pending` | — | — | Form URL: <https://mcpservers.org/>. Submission shape: one-line entry; check the site is live before posting. |
 

package/docs/getting-started.md

@@ -37,16 +37,18 @@ The suite is global-only (ADR-020) — refresh the global install and every
 project sees the new skills, rules, and hooks at once, no per-repo bump:
 
 ```bash
-agent-config upgrade            # fetch + install the latest globally (binary + plugin)
-agent-config refresh --global   # idempotent re-install, same version (root + plugin)
+agent-config upgrade            # fetch + install the latest globally (content + hooks)
+agent-config refresh --global   # idempotent re-install, same version
 agent-config refresh --project  # refresh a project's minimal surface — bridge
                                 # marker, agents/overrides/, .gitignore (no wizard)
-agent-config doctor             # PATH, binary↔plugin version drift, bridge presence
+agent-config doctor             # PATH, hook wiring, duplicate surfaces, bridge presence
 ```
 
-The Claude marketplace plugin updates on Claude Code's own cadence,
-independent of npm; `doctor` surfaces binary↔plugin drift so you know when to
-update the plugin from the marketplace.
+Claude Code is single-surface: the file projection carries content AND the
+managed hooks in `~/.claude/settings.json` — there is no marketplace plugin
+to keep in sync anymore. A leftover plugin from an older install is flagged
+by `doctor` as `claude-plugin: duplicate surface` (fix:
+`claude plugin uninstall agent-config@event4u-agent-config`).
 
 ## Project CLI — `./agent-config`
 

package/docs/guidelines/agent-infra/corpus-grounding-authoring.md

@@ -59,7 +59,7 @@ src/skills/<domain-skill>/data/
 | Named owner + cadence | `manifest.json` keys — schema-validator-enforced |
 | Staleness visibility | `upstream.last_checked` bumped on every refresh; quarterly default |
 | Link integrity | `Docs URL` / source columns are plain URLs; `check-refs` + the quarterly refresh catch 404s |
-| Eval lock | one `tests/test_<domain>_corpus.py` with representative queries |
+| Eval lock | one `tests/scripts/<domain>_corpus.test.ts` with representative queries |
 | License | source obligations recorded in the owning skill (ATTRIBUTION pattern) |
 
 ## 4. Rejected domains — recorded, do not relitigate (Step 9.7)
@@ -73,7 +73,7 @@ split), the following are **rejected as corpora**:
 | GTM playbooks | Same volatility; context dominates selection | Framework skills + discovery interviews |
 | Founder-strategy verdicts | Verdicts are human decisions (strategy-safety-floor); no auditable selection rule | Framework skills + safety floors |
 | Formula/spec lookup (WACC, WCAG criterion text, API param lists) | Mid-action **reference**, not pre-action grounding | `references/` docs / RAG |
-| Lint-able conventions (no hardcoded hex, commit format) | Post-action **validation** | Rules / linters (`tokens.py validate`, commit lints) |
+| Lint-able conventions (no hardcoded hex, commit format) | Post-action **validation** | Rules / linters (`tokens.ts validate`, commit lints) |
 | Anything ≤5 always-on lines | Grounding theater | A rule |
 
 Conditional (deferred, evidence-gated — NOT rejected): finance *method

package/docs/guidelines/agent-infra/engineering-memory-data-format.md

@@ -25,7 +25,7 @@ that prefer one file per type.
 | Incident learnings | `agents/memory/incident-learnings.yml` | `agents/memory/incident-learnings/<hash>.yml` |
 | Product rules | `agents/memory/product-rules.yml` | `agents/memory/product-rules/<hash>.yml` |
 
-Choose one layout per type and stick with it. `scripts/check_memory.py`
+Choose one layout per type and stick with it. `scripts/check_memory.ts`
 warns if both exist for the same type.
 
 ## Shared frontmatter fields
@@ -59,7 +59,7 @@ for why a fourth `high` tier was rejected.
 | `low` | Background — only surface on explicit full load | Skipped by query-matched retrieval; visible only via `/memory:load --type` full sweep |
 
 **Tier-0 governance.**
-`scripts/check_memory.py` enforces two soft guards on `critical` entries:
+`scripts/check_memory.ts` enforces two soft guards on `critical` entries:
 
 - **Critical-stale warning** — a `priority: critical` entry whose
   `last_validated` is older than 90 days emits a `critical-stale` warning
@@ -119,7 +119,7 @@ templates for the full shape:
 
 ## Redaction rules (hard)
 
-Enforced by `scripts/check_memory.py`. Reject on match:
+Enforced by `scripts/check_memory.ts`. Reject on match:
 
 - **No secrets.** API keys, tokens, credentials, private URLs with
   credentials, internal hostnames that expose infrastructure.
@@ -139,7 +139,7 @@ path if the guardrail is absent.
 
 ## Staleness
 
-`check_memory.py` runs weekly (not per-PR). It reports entries where
+`check_memory.ts` runs weekly (not per-PR). It reports entries where
 `(today - last_validated) > review_after_days`. Stale entries stay
 active — the report is informational, not a gate.
 

package/docs/guidelines/agent-infra/installed-tools-manifest.md

@@ -17,7 +17,7 @@ machine-managed, and orthogonal to `.agent-project-settings.yml`
 schema_version: 1
 agent_config_version: "2.x.y"          # last package version that wrote the file
 tools:
-  - name: claude-code                  # must match _VALID_TOOLS in scripts/install.py
+  - name: claude-code                  # must match _VALID_TOOLS in scripts/install.ts
     scope: global                      # one of: global, project
     bridge_marker: ~/.claude/          # validate checks this path exists
     installed_at: "2026-05-12"
@@ -32,7 +32,7 @@ tools:
 | `schema_version` | machine | bumps on breaking schema changes |
 | `agent_config_version` | machine | last writer's package version; `validate` flags drift |
 | `tools[]` | machine | append-on-init order preserved (not alphabetised) |
-| `tools[].name` | machine | one of the 17 valid IDs in `scripts/install.py` |
+| `tools[].name` | machine | one of the 17 valid IDs in `scripts/install.ts` |
 | `tools[].scope` | machine | `global` (user-home) or `project` (workspace bridge) |
 | `tools[].bridge_marker` | machine | absolute / `~`-prefixed for global, repo-relative for project |
 | `tools[].installed_at` | machine | ISO date; informational only |
@@ -51,7 +51,7 @@ npx @event4u/agent-config sync
 ```
 
 `sync` reads `agents/installed-tools.lock`, checks every listed tool's
-bridge marker, and replays `install.py --tools=<id>` for each missing
+bridge marker, and replays `install.ts --tools=<id>` for each missing
 one. Tools whose marker is already present are skipped — `sync` is
 idempotent and safe to re-run.
 

package/docs/guidelines/agent-infra/language-and-tone-examples.md

@@ -116,7 +116,7 @@ block (the only allowed German location).
 ## Generated `.md` — fix the generator, never the page
 
 When a `.md` page is produced by a generator (e.g. `docs/value.md` from
-`scripts/render_value_md.py`, the catalogs from the index/catalog
+`scripts/render_value_md.ts`, the catalogs from the index/catalog
 generators), German lives in the **generator's source strings** or the
 data it reads — fix it there so the page regenerates English. Hand-edits
 to a generated page are overwritten on the next regen. If a generated
@@ -138,4 +138,4 @@ Two — and only two — escapes are allowed when a line must carry German:
 
 The marker is line-scoped and auditable. Never scatter it through a
 generated file to silence the linter — fix the generator instead. Both
-escapes are recognized by `scripts/check_md_language.py`.
+escapes are recognized by `scripts/check_md_language.ts`.

package/docs/guidelines/agent-infra/layered-settings.md

@@ -9,7 +9,7 @@ project-local choices always win.
 Referenced by `road-to-project-memory.md` Phase 0 and
 `road-to-portable-dev-preferences.md`. Consumed by the centralized
 settings loader at
-[`scripts/_lib/agent_settings.py`](../../../src/scripts/_lib/agent_settings.py),
+[`scripts/_lib/agent_settings.ts`](../../../src/scripts/_lib/agent_settings.ts),
 the `/onboard` command, and any agent that edits `.agent-settings.yml`
 on user request.
 
@@ -32,7 +32,7 @@ All three are YAML. Schemas:
 - Developer (project-local): [`agent-settings.md`](../../templates/agent-settings.md).
 - Team: [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml).
 - User-global: six exact dotted paths — whitelist in
-  [`scripts/_lib/agent_settings.py`](../../../src/scripts/_lib/agent_settings.py).
+  [`scripts/_lib/agent_settings.ts`](../../../src/scripts/_lib/agent_settings.ts).
 
 ## Merge order
 
@@ -248,13 +248,13 @@ Any agent that writes `.agent-settings.yml` or
 `.agent-project-settings.yml` on the user's behalf (including
 `/onboard`, `/set-cost-profile`, and ad-hoc "change value X" requests)
 MUST follow these rules. Initial file creation and legacy migration
-are owned by `scripts/install.py`; these rules govern every edit
+are owned by `scripts/install.ts`; these rules govern every edit
 after that.
 
 The contract is **additive merge with user-line preservation** —
 the user's file is the ground truth, the template only contributes
 keys the user is missing. Round-trip parser and merger live in
-[`scripts/sync_yaml_rt.py`](../../src/scripts/sync_yaml_rt.py); the
+[`scripts/sync_yaml_rt.ts`](../../src/scripts/sync_yaml_rt.ts); the
 supported YAML subset (block-mappings, scalars, lists, comments,
 CRLF/LF) is documented in its module docstring. The stdlib-only
 choice (vs. `ruamel.yaml`) and its revisit triggers are recorded in

package/docs/guidelines/agent-infra/memory-access.md

@@ -4,21 +4,22 @@ How a skill or command reads engineering memory. Memory is entirely
 **file-backed** (`agents/memory/`); there is no external backend.
 
 Single entry point: the shared `retrieve(types, keys, limit)`
-abstraction backed by `scripts/memory_lookup.py`. It reads curated YAML
-under `agents/memory/<type>/` and the agent-written `agents/memory/intake/
-*.jsonl` signal log.
+abstraction backed by `scripts/memory_lookup.ts` (TypeScript, run via
+tsx). It reads curated YAML under `agents/memory/<type>/` and the
+agent-written `agents/memory/intake/*.jsonl` signal log.
 
 ## The contract
 
-```python
-from scripts.memory_status import status
-from scripts.memory_lookup import retrieve as retrieve_file
+Consumers reach it via the CLI (`agent-config memory:lookup`) or the
+MCP `memory_lookup` tool — never by ad-hoc file reads:
 
-hits = retrieve_file(
-    types=["ownership", "historical-patterns"],
-    keys=["app/Http/Controllers/Billing/Checkout.php"],
-    limit=3,
-)
+```bash
+agent-config memory:lookup \
+  --types ownership,historical-patterns \
+  --key "app/Http/Controllers/Billing/Checkout.php" \
+  --limit 3
+# --key is repeatable; add --format json for the raw hits,
+# --envelope v1 for the retrieval-contract envelope.
 ```
 
 Every backend MUST return a list of `Hit` with:
@@ -43,14 +44,14 @@ intake (low-confidence tier); it just never reaches the team repo unpromoted.
 
 ## The status helper
 
-`scripts/memory_status.py` reports the (constant) file backend so
-consumers — including the MCP `memory_status` tool and the v1 health
-envelope — read a stable shape:
+`scripts/memory_status.ts` exports `status()`, reporting the (constant)
+file backend so consumers — including the MCP `memory_status` tool and
+the v1 health envelope — read a stable shape:
 
-```python
-from scripts.memory_status import status
-r = status()          # constant; file-backed, never raises
-assert r.status == "file" and r.backend == "file"
+```ts
+import { status } from './memory_status.js';
+const r = status(); // constant; file-backed, never raises
+// r.status === 'file' && r.backend === 'file'
 ```
 
 Contract guarantees:

package/docs/guidelines/agent-infra/naming.md

@@ -64,6 +64,6 @@ source: package
 
 ## Linter enforcement
 
-The skill linter (`scripts/skill_linter.py`) warns on:
+The skill linter (`scripts/skill_linter.ts`) warns on:
 - **Bare-noun names** — single word without qualifier (e.g., `jira` instead of `jira-integration`)
 - **Layer collisions** — same name used for both a rule and a skill

package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -10,7 +10,7 @@ _Origin: migrated from `.agent-src.uncondensed/rules/roadmap-progress-sync.md` p
 # Roadmap Progress Sync
 
 > **Enforced by (defence in depth):**
-> 1. [`scripts/roadmap_progress_hook.py`](../../src/scripts/roadmap_progress_hook.py)
+> 1. [`scripts/roadmap_progress_hook.ts`](../../src/scripts/roadmap_progress_hook.ts)
 >    on Augment + Claude Code (`PostToolUse`) — auto-regen on write.
 > 2. `.git/hooks/pre-commit` (installed by `scripts/install-hooks.sh`) —
 >    blocks any commit whose staged set touches `agents/roadmaps/` or
@@ -44,7 +44,7 @@ without regenerating? The dashboard claims it does not exist. Marked
 EVERY ACTIVE ROADMAP MUST CONTAIN AT LEAST ONE TRACKABLE CHECKBOX
 (`- [ ]`) PER NON-INTRO PHASE. ROADMAPS WITHOUT EXECUTABLE STEPS
 EITHER GET A CHECKLIST OR THE `status: draft` FLAG.
-CI-ENFORCED: `scripts/check_roadmap_trackable.py` (CANNOT BE DEFERRED).
+CI-ENFORCED: `scripts/check_roadmap_trackable.ts` (CANNOT BE DEFERRED).
 ```
 
 **Active roadmap =** any file in `agents/roadmaps/` (root, not
@@ -61,7 +61,7 @@ Headings such as `## Phase steps`, `### Sequencing — Phase 1 …`,
 `### P0 #1 — …`, or `## Block A` do **not** count — only the
 canonical `Phase <id>` form parsed by the dashboard.
 
-**CI backstop.** `scripts/check_roadmap_trackable.py` (package-shipped,
+**CI backstop.** `scripts/check_roadmap_trackable.ts` (package-shipped,
 wire into the consumer's pre-commit / pre-push / Actions gate) fails
 when an active roadmap has zero canonical `Phase` headings or when
 any parsed phase has zero checkboxes. Last line of defence — real-time
@@ -103,7 +103,7 @@ skipped decision table.
 
 ```
 A FILE THE AGENT DROPS INTO agents/roadmaps/ MUST EITHER
-(a) PASS check_roadmap_trackable.py AND LAND IN THE DASHBOARD, OR
+(a) PASS check_roadmap_trackable.ts AND LAND IN THE DASHBOARD, OR
 (b) NOT BE IN agents/roadmaps/ AT ALL.
 NO "DECISION MATRIX" / "DESIGN NOTE" SHORTCUT.
 ```
@@ -173,7 +173,7 @@ surface; the mechanics file is the lookup material.
 ## Copilot fallback
 
 GitHub Copilot has no `PostToolUse` hook surface, so
-`scripts/roadmap_progress_hook.py` cannot detect roadmap-file writes
+`scripts/roadmap_progress_hook.ts` cannot detect roadmap-file writes
 structurally. The dashboard at `agents/roadmaps-progress.md` will
 not regenerate on its own.
 

package/docs/guidelines/agent-infra/role-contracts.md

@@ -75,7 +75,7 @@ Referenced by `road-to-role-modes.md` Phase 1. Each contract is a
 
 **Memory-write is the final field, not a nice-to-have.** Before the
 mode exits, the agent MUST either emit an intake signal via
-[`memory-access`](memory-access.md) (`scripts/memory_signal.py`
+[`memory-access`](memory-access.md) (`scripts/memory_signal.ts`
 append — one line, fire-and-forget) or draft a curated entry with
 [`/memory-add incident-learnings`](../../commands/memory-add.md).
 Pattern + consequence + guardrail, redacted. Skipping this field

package/docs/guidelines/agent-infra/security-lint-containment.md

@@ -3,7 +3,7 @@
 How the agent-security self-audit linters
 (`lint_hidden_unicode`, `lint_instruction_smuggling`,
 `lint_mcp_config_security`, `lint_skill_frontmatter_safety` — shared lib
-`src/scripts/_lib/security_lint.py`) avoid drowning in false positives **without**
+`src/scripts/_lib/security_lint.ts`) avoid drowning in false positives **without**
 a global allowlist.
 
 ## Why this exists
@@ -76,6 +76,6 @@ inside a `security-example` fence, and not covered by a matching pragma.
 
 ## See also
 
-- `src/scripts/_lib/security_lint.py` — the shared implementation.
+- `src/scripts/_lib/security_lint.ts` — the shared implementation.
 - `road-to-security-pillar` P1.5 (archived roadmap) — the council-locked decision behind this convention.
 - [`autonomous-execution`](../../../src/rules/autonomous-execution.md) — the allowlist-growth antipattern this convention avoids.

package/docs/guidelines/agent-infra/self-improvement-pipeline.md

@@ -63,7 +63,7 @@ blocks — it does not hand a half-filled doc to the next stage.
 ### Stage 4 — Gate
 
 - **Trigger:** proposal doc committed or staged.
-- **Executor:** `scripts/check_proposal.py`.
+- **Executor:** `scripts/check_proposal.ts`.
 - **Input:** proposal doc from Stage 3.
 - **Output:** verdict recorded in the proposal doc section 9
   (`pass | request changes | block`). Frontmatter `stage: gated`

package/docs/guidelines/agent-infra/size-and-scope.md

@@ -113,7 +113,7 @@ evidence-disciplined context type:
 
 - Hard bound: **≤ 150 lines** — a card is a thin distillation, never a mirror.
 - **Mandatory** `links.authoritative` pointer (path or URL).
-- Enforced by `check_knowledge_cards.py` (pointer-resolution CI + size +
+- Enforced by `check_knowledge_cards.ts` (pointer-resolution CI + size +
   trust-tag + multi-evidence git-ancestry consistency; `--strict` adds a
   content-compare). Durable content = negative facts + pointers; positive
   structure is a per-line, last-verified hypothesis.

package/docs/guidelines/agent-infra/skill-quality-checklist.md

@@ -24,7 +24,7 @@ Every skill MUST have: `When to use`, `Procedure`, `Gotcha`, `Output format`, `D
 ## Frontmatter Contract
 
 Every skill's YAML frontmatter MUST validate against `scripts/schemas/skill.schema.json`.
-Violations are reported by `scripts/skill_linter.py` as `schema_<rule>` errors
+Violations are reported by `scripts/skill_linter.ts` as `schema_<rule>` errors
 and fail `./scripts-run src/scripts/validate_frontmatter` and the full CI pipeline.
 
 ### Omit fields equal to their schema default
@@ -39,7 +39,7 @@ A field that carries the schema `default` (e.g. `trust.level: core`,
 `command.disable-model-invocation: true`) is redundant:
 `validate_frontmatter.apply_schema_defaults` injects it transparently for
 every consumer (validator, discovery manifest, drift checksum). Writing it
-anyway is boilerplate that `scripts/lint_frontmatter_boilerplate.py` rejects
+anyway is boilerplate that `scripts/lint_frontmatter_boilerplate.ts` rejects
 (wired into `task ci-fast`). To strip it across the tree, run
 `./scripts-run src/scripts/migrate_frontmatter_defaults`. Background:
 `road-to-abstraction-reduction.md` +
@@ -49,7 +49,7 @@ anyway is boilerplate that `scripts/lint_frontmatter_boilerplate.py` rejects
 > contract: artefacts that omit the field inherit whatever the default *is at
 > read time*. Flipping a default value (e.g. `lifecycle: active → deprecated`)
 > silently re-defaults every artefact that omits the field — so a default
-> change must pair with a re-run of `migrate_frontmatter_defaults.py` and an
+> change must pair with a re-run of `migrate_frontmatter_defaults.ts` and an
 > explicit review of the affected artefacts.
 
 ## Description Triggering
@@ -106,7 +106,7 @@ blocks beyond the standard required sections:
 | 3 | Proactive Triggers | `## When the agent should load this` | 3–5 concrete user-prompt patterns (paraphrases users actually type), not abstract categories. |
 | 4 | Output Artifacts | `## Output` | 1–4 named artifacts with shape (file path, table, markdown structure) — orchestrator-citable identifier each. |
 
-**Forward-only.** `scripts/skill_linter.py` enforces these blocks for
+**Forward-only.** `scripts/skill_linter.ts` enforces these blocks for
 `tier: senior` skills only; mid-tier and untiered skills skip the
 check. No retrofit pass on existing Wing-1 skills.
 
@@ -117,7 +117,7 @@ bad pattern pairs, and the WHEN-NOT routing peer rules live in
 
 ## Structural Malice Floor
 
-`scripts/skill_linter.py` runs five regex patterns against every
+`scripts/skill_linter.ts` runs five regex patterns against every
 skill / rule / command body — credential exfiltration, remote
 execution, force-push to a protected ref, world-readable secret
 files, and shell-injection in subprocess calls. A match emits

package/docs/guidelines/augment-portability-patterns.md

@@ -61,7 +61,7 @@ invocation.
 
 ## Enforcement
 
-`scripts/check_portability.py` scans `.augment/`, `.agent-src.uncondensed/`,
+`scripts/check_portability.ts` scans `.augment/`, `.agent-src.uncondensed/`,
 and the package repo's root `AGENTS.md` + `.github/copilot-instructions.md`
 for forbidden identifiers, for any `task <name>` invocation inside
 artefact files, and for direct script invocations that bypass the

package/docs/installation.md

@@ -413,25 +413,24 @@ This is additional to project-installed mode, not a replacement.
 auggie plugin install agent-config@event4u-agent-config
 ```
 
-### Claude Code
+### Claude Code — plugin deprecated (single-surface model)
 
-Two equivalent paths — pick whichever surface you're already in:
+**Do not install the marketplace plugin for Claude Code.** The npx/npm
+global install (`npx -y @event4u/agent-config init`) is the single supported
+surface: it deploys skills/commands/rules to `~/.claude/` **and** registers
+the deterministic hooks in a managed `~/.claude/settings.json` block. The
+plugin would only duplicate every skill/command listing while its git-SHA
+snapshot silently lags each release.
 
-```bash
-# From your shell (CLI)
-claude plugin install agent-config@event4u-agent-config
-```
+Already have the plugin from an earlier install?
 
-```text
-# From inside Claude Code (slash command)
-/plugin marketplace add event4u-app/agent-config
-/plugin install agent-config@event4u-agent-config
+```bash
+claude plugin uninstall agent-config@event4u-agent-config
 ```
 
-The slash-command path is the canonical Claude Code Plugin Marketplace
-flow ([reference](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)).
-It pulls the repo via git-clone and reads the skills directly from
-`.claude/skills/` — no separate ZIP download.
+Hooks keep firing after removal (they live in `settings.json`, not the
+plugin); `agent-config doctor` verifies via the `hook-wiring` check and
+flags a leftover plugin as `claude-plugin: duplicate surface`.
 
 ### Copilot CLI