@event4u/agent-config 1.16.0 → 1.18.0

package/.agent-src/skills/finishing-a-development-branch/SKILL.md

@@ -9,15 +9,17 @@ source: package
 ## When to use
 
 * Implementation of a feature or bug fix is complete on a development branch
-* All planned commits are in, user is ready to hand off
+* All planned commits are in, the user is ready to hand off
 * You are about to say "done" and suggest the next action
-* Branch has been idle and the user wants to decide its fate
+* The branch has been idle and the user wants to decide its fate
 
 Do NOT use when:
 
 * Still implementing — use targeted verification, not the ship gate
-* A PR already exists and is mid-review — use [`receiving-code-review`](../receiving-code-review/SKILL.md)
-* Only documentation changed — simplify to commit + PR without full gate
+* A PR already exists and is mid-review — use
+  [`receiving-code-review`](../receiving-code-review/SKILL.md)
+* Only documentation changed and no tests apply — simplify to
+  commit + PR without the full gate
 
 ## Goal
 
@@ -37,29 +39,33 @@ how work gets lost.
 
 ## Procedure
 
-### 1. Inspect branch state
+### 1. Inspect the current branch state
 
-Before presenting options, check:
+Before presenting any options, gather context. Do not assume — check:
 
-* `git status` — clean or dirty?
-* `git log --oneline <base>..HEAD` — what commits are actually on this branch
-* `git branch --show-current` — branch name to operate on
+* `git status` — clean, or still dirty?
+* `git log --oneline <base>..HEAD` — what commits are actually on this
+  branch?
+* `git branch --show-current` — the branch name you will be operating on
 * Remote state — is the branch pushed? Is there an open PR already?
 
-PR already exists → **stop**, route to [`receiving-code-review`](../receiving-code-review/SKILL.md)
-or [`fix-pr-comments`](../../commands/fix-pr-comments.md).
+If a PR already exists for this branch, **stop** — this is not a
+finishing step, route to [`receiving-code-review`](../receiving-code-review/SKILL.md)
+or [`fix-pr-comments`](../../commands/fix-pr-comments.md) instead.
 
 ### 2. Verify readiness
 
-Run the full end-of-work gate — see [`verify-before-complete`](../verify-before-complete/SKILL.md):
+Run the full end-of-work gate before presenting any options — see
+[`verify-before-complete`](../verify-before-complete/SKILL.md):
 
 1. Targeted tests green
 2. Full test suite green
 3. Quality pipeline (PHPStan → Rector dry-run → ECS → PHPStan) green
-4. `git status` clean — no unstaged files, no stray files
-5. Branch pushed or explicitly marked local-only
+4. `git status` clean — nothing unstaged, no stray files
+5. Branch is pushed or explicitly marked local-only
 
-Any step fails → **stop**. Report failure, do not present ship options.
+If any step fails → **stop**. Report the failure, do not present ship
+options. Fixing the failure comes first.
 
 ### 3. Determine the base branch
 
@@ -71,9 +77,12 @@ BASE=main
 BASE=$(git config branch.$(git branch --show-current).merge | sed 's|refs/heads/||')
 ```
 
-Ambiguous → ask: *"This branch splits from `<guess>` — correct?"*.
+If ambiguous, ask: *"This branch splits from `<guess>` — correct?"*
+before presenting options.
 
-### 4. Present four options — numbered, no narration
+### 4. Present the four options — numbered, no narration
+
+Ask the user exactly one question:
 
 ```
 Implementation is verified. What now?
@@ -84,21 +93,25 @@ Implementation is verified. What now?
 4. Discard all work on this branch
 ```
 
-No recommendations unless the user asks.
+Do not add recommendations unless the user asks. Each option leads to
+a different sub-procedure (steps 5a–5d).
 
 ### 5a. Option 1 — Open a PR
 
-1. Update branch → [`prepare-for-review`](../../commands/prepare-for-review.md)
-2. Self-review → [`review-changes`](../../commands/review-changes.md)
-3. Write description → [`create-pr-description`](../../commands/create-pr-description.md)
-4. Open PR → [`create-pr`](../../commands/create-pr.md)
-5. Confirm PR opened green, not red
+1. Ensure the branch is up to date with the base →
+   [`prepare-for-review`](../../commands/prepare-for-review.md)
+2. Self-review the full diff → [`review-changes`](../../commands/review-changes.md)
+3. Write the PR description → [`create-pr-description`](../../commands/create-pr-description.md)
+4. Open the PR → [`create-pr`](../../commands/create-pr.md)
+5. Confirm the PR opened green, not red
 
-Surrounding discipline → [`requesting-code-review`](../requesting-code-review/SKILL.md).
+See [`requesting-code-review`](../requesting-code-review/SKILL.md) for
+the surrounding discipline.
 
 ### 5b. Option 2 — Merge locally
 
-Use only for no-PR projects (solo, spike, private tooling).
+Use only when the project policy is "no PR required" (solo repos,
+spike branches, private tooling). For team repos, default to Option 1.
 
 ```bash
 git checkout <base-branch>
@@ -110,17 +123,18 @@ git merge --no-ff <feature-branch>
 git branch -d <feature-branch>
 ```
 
-Post-merge test fails → `git reset --hard ORIG_HEAD`, fix on feature branch, restart.
+If the post-merge test run fails → `git reset --hard ORIG_HEAD`, fix
+on the feature branch, restart from Option 1/2.
 
 ### 5c. Option 3 — Keep as-is
 
-* Push to origin if not already pushed
-* Report branch name and last commit SHA
+* Push the branch to origin if not already pushed (safeguards the work)
+* Report the branch name and the last commit SHA back to the user
 * Do not delete the worktree, do not force-push
 
 ### 5d. Option 4 — Discard
 
-**Confirmation gate** — typed answer, not "y":
+**Confirmation gate** — require a typed answer, not "y":
 
 ```
 This will permanently remove:
@@ -140,65 +154,87 @@ git branch -D <feature-branch>
 git push origin --delete <feature-branch>
 ```
 
-Log discarded SHAs so work can be recovered via `git reflog`.
+Log the discarded SHAs so the work can be recovered via `git reflog`
+within the reflog TTL if needed.
 
 ### 6. Clean up worktrees
 
-Branch in a `git worktree`:
+If the branch lives in a `git worktree`:
 
-* Options 1, 2, 4 → `git worktree remove <path>` after terminal state
+* Options 1, 2, 4 → `git worktree remove <path>` after the branch
+  terminal state
 * Option 3 → keep the worktree
 
 ## Output format
 
-After chosen option completes:
+After the chosen option completes, report:
 
-1. **What happened** — one sentence ("PR #123 opened", "Merged as `abcdef`", "Discarded")
+1. **What happened** — single sentence ("PR #123 opened", "Merged
+   into main as `abcdef`", "Branch discarded")
 2. **Evidence** — exit codes / PR URL / commit SHA
-3. **Cleanup state** — worktree removed/kept, branch deleted/retained
-4. **Next step** — "Awaiting review", "Main is one commit ahead", etc.
+3. **Cleanup state** — worktree removed / kept, branch deleted /
+   retained
+4. **Next step** — e.g. "Awaiting review" / "Main is one commit ahead"
 
 ## Gotchas
 
-* Option 1 on red CI — PR opens but not reviewable; check CI status
-* Option 2 with ff-only on diverged base silently aborts — check exit code
-* Option 4 on a branch that is upstream of another local branch — orphans the dependent
-* Force-push after PR open can lose reviewer line-comments
-* `-d` refuses unmerged; `-D` forces — only use `-D` inside confirmed discard
-* Stacked PRs base ≠ `main` — opening PR to `main` invalidates the stack
+* Option 1 (PR) on a red CI — the PR opens but is not actually
+  reviewable; check the CI status before reporting success
+* Option 2 (local merge) with fast-forward only on a diverged base
+  silently fails — the merge command aborts but the report can look
+  successful if the exit code is not checked
+* Option 4 (discard) on a branch that is already the upstream of
+  another local branch — the dependent branch is orphaned
+* Force-pushing after a PR is opened can lose the reviewer's
+  line-comments — prefer additional commits during review
+* `git branch -d` vs `-D` — lowercase `-d` refuses unmerged branches,
+  uppercase `-D` forces; only use `-D` inside the confirmed discard
+  flow
+* On stacked PRs, the base is **not** `main` — opening a PR to `main`
+  invalidates the stack
 
 ## Do NOT
 
-* Do NOT present ship options while tests or quality are red
-* Do NOT add rationale to the four options — user decides
-* Do NOT discard without typed confirmation including branch name
-* Do NOT force-delete remote without user confirmation
-* Do NOT silently change the base between verification and ship
-* Do NOT mix other cleanup into the discard step
+* Do NOT present ship options while tests or quality checks are red
+* Do NOT add rationale or recommendations to the four numbered options
+  — the user decides
+* Do NOT discard a branch without a typed confirmation including the
+  branch name
+* Do NOT force-delete a remote branch without user confirmation
+* Do NOT silently change the base branch between verification and ship
+* Do NOT mix any other cleanup into the discard step
 
 ## Anti-patterns
 
-* Three options + "or discard" — buries destructive option
-* Running the full gate here *and* at start of `create-pr` — duplicate
-* Merge local + open PR at the same time
-* Asking "ready to ship?" without the four numbered options
+* Presenting three options and phrasing the fourth as "or we can
+  discard if you want" — buries the destructive option
+* Running the full gate inside this skill *and* at the start of
+  `create-pr` — duplicates work. Trust the gate result if nothing
+  changed in between
+* Merging local + opening PR at the same time — pick one
+* Asking "ready to ship?" without listing the four concrete options
 
 ## When to hand over to another skill / command
 
-* Pre-merge verification → [`verify-before-complete`](../verify-before-complete/SKILL.md)
-* Rebasing stack → [`prepare-for-review`](../../commands/prepare-for-review.md)
-* Last-minute commits → [`commit`](../../commands/commit.md), [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md)
-* Self-review → [`review-changes`](../../commands/review-changes.md)
-* Creating PR → [`create-pr`](../../commands/create-pr.md)
-* Review comments → [`receiving-code-review`](../receiving-code-review/SKILL.md)
+* Final pre-merge verification → [`verify-before-complete`](../verify-before-complete/SKILL.md)
+* Rebasing the stack before PR → [`prepare-for-review`](../../commands/prepare-for-review.md)
+* Writing the commit for any last-minute tweaks →
+  [`commit`](../../commands/commit.md),
+  [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md)
+* Self-review walkthrough → [`review-changes`](../../commands/review-changes.md)
+* Creating the PR → [`create-pr`](../../commands/create-pr.md)
+* Processing review comments after the PR is open →
+  [`receiving-code-review`](../receiving-code-review/SKILL.md)
 
 ## Validation checklist
 
-* [ ] Full gate verified green in this turn
-* [ ] Base branch determined and confirmed when ambiguous
-* [ ] Exactly four numbered options presented, no narration
+Before reporting "done" after this skill runs:
+
+* [ ] Full gate (tests + quality pipeline) verified green in this turn
+* [ ] Base branch determined and confirmed with the user when ambiguous
+* [ ] Exactly four numbered options were presented, no narration added
 * [ ] User's choice recorded literally, not reinterpreted
-* [ ] Sub-procedure for chosen option completed end-to-end
-* [ ] Worktree handled per option
-* [ ] Destructive actions had typed confirmation with branch name
-* [ ] Final report includes evidence (PR URL, SHA, exit code)
+* [ ] Sub-procedure for the chosen option completed end-to-end
+* [ ] Worktree state handled per option (remove for 1/2/4, keep for 3)
+* [ ] Destructive actions had typed confirmation including branch name
+* [ ] Final report includes evidence (PR URL, SHA, or exit code)

package/.agent-src/skills/flux/SKILL.md

@@ -8,7 +8,12 @@ source: package
 
 ## Positioning — dispatched, not standalone
 
-`flux` is the **primitive-library executor** for projects on the Livewire + Flux stack. Invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) once the design brief is locked, and revisited by `review.py` / `polish.py` during the design-review loop. Does **not** own the flow, drive the audit, or lock the design.
+`flux` is the **primitive-library executor** for projects on the
+Livewire + Flux stack. It is invoked by
+[`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
+once the design brief is locked, and revisited by `review.py` /
+`polish.py` during the design-review loop. It does **not** own the
+flow, does **not** drive the audit, and does **not** lock the design.
 
 | Concern | Owner |
 |---|---|
@@ -22,8 +27,8 @@ source: package
 
 Cite this skill when:
 
-- Project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
-- Building forms, modals, dropdowns, toasts, or other standard UI elements Flux already provides
+- The project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
+- Building forms, modals, dropdowns, toasts, or other standard UI elements that Flux already provides
 
 Do NOT use when:
 
@@ -64,16 +69,31 @@ Do NOT use when:
 
 ### Review pass — a11y findings + preview envelope
 
-When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
-
-- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
-- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
-
-Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
+  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
+  pre-existing entries on replay. Omit the envelope on apply passes; the
+  engine's `_apply_a11y_gate` only fires when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
 
 ## Gotcha
 
-- Model tends to use old Flux API syntax — always check latest docs.
+- The model tends to use old Flux API syntax — always check latest docs.
 - Flux has built-in validation display — don't add manual error rendering alongside it.
 - Don't mix Flux with raw HTML form elements in the same form.
 

package/.agent-src/skills/github-ci/SKILL.md

@@ -14,7 +14,7 @@ Use this skill when working with GitHub Actions workflows, CI pipeline configura
 
 1. Read `.github/workflows/` to understand the full pipeline.
 2. Check `AGENTS.md` for quality tool commands and testing setup.
-3. Read `.augment/commands/fix-ci.md` for CI failure debugging workflow.
+3. Read `commands/fix/ci.md` for CI failure debugging workflow.
 
 ## Workflow overview
 
@@ -91,7 +91,7 @@ Check `.github/workflows/` for the runner types used. Common patterns:
 3. Get logs: `GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs`
 4. Fix locally, verify in container, then push.
 
-See `.augment/commands/fix-ci.md` for the full debugging workflow.
+See `commands/fix/ci.md` for the full debugging workflow.
 
 
 ## Output format

package/.agent-src/skills/judge-code-quality/SKILL.md

@@ -112,8 +112,8 @@ Required fields (ordered):
    a codebase convention; omit only when verdict is `apply`
 
 If a finding needs runtime confirmation (running a formatter, linter,
-or static analyzer), note it as a follow-up for the implementer — the
-judge does not execute tools.
+or static analyzer to see the actual report), note it as a follow-up
+for the implementer — the judge does not execute tools.
 
 ## Gotcha
 
@@ -140,16 +140,15 @@ judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Code-review rubric** — Google Engineering Practices, "The Standard
   of Code Review" and "What to look for in a code review",
   [google.github.io/eng-practices/review/reviewer](https://google.github.io/eng-practices/review/reviewer/).
   The lenses (design, functionality, complexity, tests, naming, comments,
-  style, consistency) the judge applies — codebase conventions over
-  external style preferences.
+  style, consistency) the judge applies — prioritizing codebase conventions
+  over external style preferences.
 - [`subagent-orchestration`](../subagent-orchestration/SKILL.md) —
   model-pairing rules (`subagents.judge_model` one tier above implementer).
 - Sibling judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),

package/.agent-src/skills/judge-security-auditor/SKILL.md

@@ -150,13 +150,12 @@ Runtime boundary: the judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Security rubric** — OWASP Application Security Verification Standard
   (ASVS), [owasp.org/www-project-application-security-verification-standard](https://owasp.org/www-project-application-security-verification-standard/).
-  Finding categories (authentication, access control, validation,
+  The finding categories (authentication, access control, validation,
   cryptography, error handling) the judge walks on every diff.
 - [`subagent-orchestration`](../subagent-orchestration/SKILL.md) —
   model-pairing rules (`subagents.judge_model` one tier above implementer).

package/.agent-src/skills/judge-test-coverage/SKILL.md

@@ -134,10 +134,9 @@ as a follow-up for the implementer — the judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Test-value rubric** — Martin Fowler, "Test Pyramid",
   [martinfowler.com/bliki/TestPyramid.html](https://martinfowler.com/bliki/TestPyramid.html),
   and Kent Beck, "Test Desiderata",

package/.agent-src/skills/lint-skills/SKILL.md

@@ -17,56 +17,74 @@ execution:
 
 ## When to use
 
-- Validate shape of every skill/rule in `.agent-src.uncompressed/`
-- Verify `execution:` metadata is well-formed
-- Pre-PR local check before CI skill-lint job
-- Investigate reported linter failure
+Use this skill when:
 
-NOT: single file (call `skill_linter.py <path>`), cross-refs (use `check-refs`),
-compression freshness (use `bash scripts/compress.sh --check`).
+- Validating the shape of every skill and rule in `.agent-src.uncompressed/`
+- Verifying execution metadata (`execution.type`, `handler`, `command`) is well-formed
+- Checking locally before opening a PR that CI's skill-lint job will pass
+- Investigating a reported linter failure on a specific skill or rule
+
+Do NOT use when:
+
+- Linting only one file — call `python3 scripts/skill_linter.py <path>` directly
+- Checking cross-references between files — use `check-refs` instead
+- Checking compression freshness — use `bash scripts/compress.sh --check` instead
 
 ## Procedure
 
-1. **Inspect env** — `python3` on PATH, cwd = agent-config repo root (linter
-   resolves `.agent-src.uncompressed/skills/` relative to cwd).
-2. **Dispatch via runtime** —
+### 1. Inspect the environment
 
-   ```bash
-   python3 scripts/runtime_dispatcher.py run --skill lint-skills
-   ```
+Confirm `python3` is available and the working directory is the agent-config
+repository root — the linter expects to find `.agent-src.uncompressed/skills/`
+and related directories relative to `cwd`.
 
-   Handler runs `python3 scripts/skill_linter.py --all`, captures stdout/stderr,
-   returns typed `ExecutionResult`.
-3. **Verify result** —
-   - `status: success` + `exit_code: 0` → all clean
-   - `exit_code: 1` → warnings only — review stdout
-   - `exit_code: 2` → errors — fix flagged files
-   - `status: timeout` → investigate slowdown, do not just raise timeout
-   - `status: error` → interpreter missing or wrong cwd
+### 2. Dispatch via the runtime layer
 
-## Output
+Invoke the skill through the runtime dispatcher so the `execution:` block in
+this skill's frontmatter governs the call:
 
-1. One-line summary: status, exit code, duration (ms)
-2. Count of skills/rules inspected if known
-3. First 10 errored files: code + message
-4. Next action: fix, re-run, or surface raw stdout
+```bash
+python3 scripts/runtime_dispatcher.py run --skill lint-skills
+```
 
-## Gotcha
+The dispatcher resolves the request, the shell handler runs
+`python3 scripts/skill_linter.py --all`, captures stdout/stderr, and returns
+a typed `ExecutionResult`.
 
-- `--all` walks full tree — several seconds; bump `timeout_seconds` if repo grew
-- Running outside repo root → zero skills inspected, looks green but is a no-op
-- `exit_code: 1` (warnings) does not fail CI — not the same as "clean"
+### 3. Verify the result
 
-## Do NOT
+Check the returned `ExecutionResult`:
+
+- `status: success` and `exit_code: 0` → all skills and rules are clean
+- `exit_code: 1` → warnings only — review `stdout` for the listed warnings
+- `exit_code: 2` → errors present — fix the flagged files before continuing
+- `status: timeout` → the linter exceeded `timeout_seconds` — investigate
+- `status: error` → the interpreter could not launch — check that `python3`
+  is on `PATH` and the repository root is the current working directory
 
-- Do NOT call `skill_linter.py` directly when the intent is to exercise the
-  runtime path — go through the dispatcher
-- Do NOT raise `timeout_seconds` to mask slowdowns
-- Do NOT add pipes/redirection — handler uses `shell=False`, argv form only
+## Output format
 
-## References
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of skills and rules the linter inspected, if known
+3. List of files with errors (first 10), each with code and message
+4. Next action: fix errors, re-run, or surface the raw `stdout` for review
+
+## Gotchas
+
+- The command uses `--all`, which walks the full tree — expect several seconds
+  of runtime on a warm repo; bump `timeout_seconds` if the repo has grown
+- Running outside the agent-config repo root will make the linter report zero
+  skills, which looks like a pass but is actually a no-op
+- Warnings (`exit_code: 1`) do not fail CI by default; do not dismiss them as
+  "green" when the task is to get to zero warnings
+
+## Do NOT
 
-- Skill: `check-refs` — sibling pilot that runs the cross-ref checker
-- Rule: `runtime-safety` — execution metadata constraints
-- Script: `scripts/skill_linter.py`, `scripts/runtime_dispatcher.py`,
-  `scripts/runtime_handler.py`
+- Do NOT invoke `scripts/skill_linter.py` directly when the intent is to test
+  the runtime path — use the dispatcher so the handler and result object are
+  exercised
+- Do NOT raise `timeout_seconds` to hide a genuinely slow linter pass —
+  investigate the slowdown first
+- Do NOT add shell redirection or pipes to `command` — the handler runs
+  `subprocess.run` with `shell=False`; only argv form is supported