@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/rules/commit-policy.md

@@ -0,0 +1,59 @@
+---
+type: "always"
+tier: "safety-floor"
+description: "Commit policy — never commit and never ask about committing unless the user said so this turn, the roadmap authorizes it, or a commit command is invoked"
+alwaysApply: true
+load_context:
+  - ../contexts/authority/commit-mechanics.md
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# Commit Policy
+
+## The Iron Law
+
+```
+NEVER COMMIT. NEVER ASK ABOUT COMMITTING.
+EXCEPTIONS ARE EXPLICIT, NOT INFERRED.
+```
+
+Applies regardless of `personal.autonomy`, conversation momentum, or "clean stopping point". Default: **no commit, no question**.
+
+## Exceptions — when committing IS allowed
+
+Exactly four:
+
+1. **User says so this turn** — "commit this now", "go ahead and commit". This commit only, not standing.
+2. **Standing instruction not yet revoked** — "commit after every phase" earlier in the conversation; cache and honor.
+3. **Commit command invoked** — `/commit` (with confirmation) or `/commit:in-chunks` (auto-split, no confirmation).
+4. **Roadmap authorization** — roadmap file lists explicit commit steps and the user invoked roadmap execution.
+
+Anything else → no commit. Hard Floor (bulk deletions, infra changes) still fires on top of any exception — see [`commit-mechanics`](../contexts/authority/commit-mechanics.md) for diff triggers and roadmap-authorized commit flow.
+
+## NEVER ask about committing
+
+"Should I commit this?" / "do we want to commit?" — **forbidden**. The user invokes a command or says so explicitly. Don't surface a commit option in numbered-options blocks unless the rest of the message would be incomplete without it.
+
+Quoted commit phrases (chat-log paste, log excerpt, roadmap snippet) are **not** permission — see [`commit-mechanics`](../contexts/authority/commit-mechanics.md).
+
+## Always split into logical chunks — never ask how
+
+```
+COMMIT AUTHORIZED → SPLIT INTO LOGICAL CHUNKS BY DEFAULT.
+NEVER ASK "ONE COMMIT OR MULTIPLE?", "HOW SHOULD I SPLIT?",
+"WHICH CHUNK FIRST?". THE AGENT PICKS THE SPLIT.
+```
+
+One chunk per concern, foundation-first; generated files ride with their source. Full mechanics + carve-outs: [`commit-mechanics`](../contexts/authority/commit-mechanics.md).
+
+## NEVER write commit steps into roadmaps unsolicited
+
+Roadmaps plan **work**, not commits — when creating a roadmap, never add commit steps unless the user explicitly asked. Detail: [`commit-mechanics`](../contexts/authority/commit-mechanics.md).
+
+## See also
+
+- [`scope-control`](scope-control.md) — git-ops permission gate (push, merge, branch, PR, tag).
+- [`no-cheap-questions`](no-cheap-questions.md) — canonical Iron Law. · [`autonomous-execution`](autonomous-execution.md) · [`/commit`](../commands/commit.md) · [`/commit:in-chunks`](../commands/commit/in-chunks.md).

package/dist/agent-src/rules/direct-answers.md

@@ -0,0 +1,64 @@
+---
+type: "always"
+tier: "3"
+description: "Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default."
+alwaysApply: true
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Direct Answers
+
+Three Iron Laws govern every reply.
+
+## Iron Law 1 — No Flattery
+
+```
+NEVER OPEN WITH "GREAT QUESTION", "FASCINATING", OR PRAISE TO PLEASE THE USER.
+ANSWER THE SUBSTANCE. SHIP THE TRUTH.
+```
+
+- No subjective judgment on user code unless evaluation was asked.
+- "Good catch" / "you're right" only when literally true.
+- Mistakes — one-sentence acknowledge, switch behavior, no apology theatre.
+
+## Iron Law 2 — No Invented Facts (severity-tiered)
+
+```
+DO NOT CLAIM WHAT YOU HAVEN'T VERIFIED.
+THE MORE LOAD-BEARING THE CLAIM, THE HARDER YOU VERIFY.
+WHEN VERIFICATION IS NOT WORTH THE COST → ASK.
+```
+
+Severity tiers (High = load-bearing · Medium = project-shape · Low = idioms), per-tier verification actions, and "just guess" override: [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md).
+
+## Iron Law 3 — Brevity by Default
+
+```
+THE SHORTEST REPLY THAT FULLY ANSWERS THE QUESTION IS THE RIGHT REPLY.
+LONG ANSWERS ARE A FAILURE MODE, NOT A SIGN OF EFFORT.
+```
+
+- Skip restating the question; skip "Let me…" intent announcements.
+- Skip explaining tool use — the call result speaks.
+- Skip post-hoc summary unless rechecking a decision.
+- Multi-step → bullets. One-true-answer → one sentence.
+
+Never overrides `user-interaction` (numbered options stay) or command-mandated steps.
+
+**Narration carve-out:** restore narration only when both `personal.play_by_play` AND `verbosity.intent_announcements` are `true` in `.agent-settings.yml`.
+
+## Emoji Scope — functional markers only
+
+**Whitelist:** mode markers (`role-mode-adherence`); CLI status `❌` / `✅` / `⚠️`; roadmap checkboxes `[x]` / `[~]` / `[-]`.
+**Blacklist:** opening flair (✨, 🚀, 🎉, 💡, 🔥, 👍); empathy (❤️, 🤗, 😊); section dividers; reaction emojis. Unsure → blacklist.
+
+## Failure modes & examples
+
+Trigger phrases + correction pattern: [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md).
+Pattern Memory (wrong / right / why): [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md).
+Outcome baseline: [`tests/golden/outcomes/direct_answers.json`](../../tests/golden/outcomes/direct_answers.json).
+
+Cross-rule index: [`frugality-charter`](../contexts/contracts/frugality-charter.md).

package/dist/agent-src/rules/domain-adoption-policy.md

@@ -0,0 +1,160 @@
+---
+type: "auto"
+tier: "2b"
+alwaysApply: false
+description: "Adopting a new domain track (mobile, ML, blockchain, IoT) — gates import on demand, ownership, CI fit, Sunset compat BEFORE harvest"
+triggers:
+  - intent: "adopt new domain"
+  - intent: "harvest new domain track"
+  - intent: "open a domain plate"
+  - keyword: "mobile track"
+  - keyword: "ml track"
+  - keyword: "blockchain track"
+  - path_prefix: ".agent-src.uncondensed/skills/"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncondensed/"
+    reason: "Rule names the authoring tree as the gated-entry location for new domain plates."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Domain Adoption Policy
+
+A "domain" is a coherent vertical the suite has not yet entered — mobile, ML,
+blockchain, scientific computing, IoT, gaming, embedded, robotics. Adopting
+one is a structural decision: every new domain plate doubles the surface a
+single maintainer keeps current, and most upstream skill-suites in adjacent
+domains rot within 6-12 months as their underlying SDK churns.
+
+This rule gates that decision. It does **not** gate per-skill adoptions inside
+a domain that is already opened — those run under the regular harvest plate
+process. It gates **opening** the domain in the first place.
+
+## The Iron Law
+
+```
+NEVER OPEN A NEW DOMAIN TRACK WITHOUT THE THREE GATES.
+DEMAND-SIGNAL · NAMED MAINTENANCE OWNER · CI-TOOLING DECISION.
+ALL THREE PASS, OR THE ROADMAP MARKS THE DOMAIN GATED.
+```
+
+The three gates fire before any skill, guideline, command, or rule from the
+domain enters `.agent-src.uncondensed/`. A council session may inform the
+decision but cannot replace the gate evidence.
+
+## Gate 1 — Demand signal
+
+At least one of the following must be **true and citeable** in the roadmap:
+
+- **≥ 2 consumer projects** in the domain. Cite repository names or
+  `agents/settings/contexts/` notes — not "I think there might be".
+- **Named user direction with target.** A specific user ask plus a target
+  project / use case — e.g. "harvest the mobile skills for project X, due
+  next quarter". Vague *"this might be useful"* does not count.
+- **Public-incident pull.** A reproducible incident on a consumer project
+  the domain would have prevented, captured in `agents/settings/contexts/` with
+  the missing surface area named.
+
+If none of the three is citeable, **defer**. Open a watch-only context note
+under `agents/settings/contexts/domain-watch/<domain>.md` listing the missing signal
+so the next harvest can re-evaluate without re-relitigating the case.
+
+## Gate 2 — Named maintenance owner
+
+Domain plates rot. Pick the owner before the import, not after.
+
+- The roadmap names a **single maintainer** (not "the team", not "TBD")
+  responsible for the domain quarterly review.
+- The owner commits to the **refresh cadence** — quarterly review at
+  minimum, faster if the domain is volatile (mobile RN/Expo SDK,
+  ML model APIs).
+- Each adopted artefact carries an **inline upstream-source line** with
+  SHA + last-checked timestamp so refresh is mechanical, not archaeological.
+
+If no owner is named or no cadence is set, **defer**. An unowned domain
+plate becomes broken authoritative-links and stale skills inside two cycles.
+
+## Gate 3 — CI-tooling decision
+
+Either the domain's verification tooling is validated in CI, or the suite
+explicitly accepts platform-bound reference-only status.
+
+- **Validated.** The CI pipeline runs the relevant linters/tests/integration
+  checks for the domain (e.g. `mobile-e2e` runners, ML model validation,
+  contract conformance) on every PR. Cost noted in the roadmap risk
+  register.
+- **Out-of-scope (reference-only).** The domain is a platform fact the
+  suite cannot validate (iOS Simulator on non-macOS runners, GPU-bound
+  ML, hardware-bound IoT). The roadmap states this explicitly; affected
+  artefacts carry a "reference-only on \<unsupported platforms\>" header
+  so consumers do not file false-positive bugs.
+
+If neither line is drawn, **defer**. Half-validated CI silently rots the
+domain — green builds while the underlying tooling drifts.
+
+## Sunset Policy stacks on top
+
+Every domain track inherits the authoritative-link Sunset path documented
+in any plate that imports volatile upstream content:
+
+- Volatile content (SDK-pinned, API-pinned, tool-version-pinned) lives as
+  guideline body + SHA-pinned upstream link, not as forked scripts.
+- Refresh trigger: quarterly cadence or earlier if a SHA-pinned link
+  404s in CI.
+- The `check-refs` and `check-portability` linters apply unchanged.
+
+Adopting a domain does not exempt it from any other suite-wide rule —
+`augment-edit-discipline`, `skill-quality`, `size-enforcement`,
+`rule-type-governance`. Every domain artefact passes the same gates as a
+core artefact.
+
+## Failure modes
+
+- *"It's just one skill, not a domain."* — Audit the skill's prerequisites.
+  If it pulls in a new toolchain, simulator, language runtime, or
+  platform-specific build system, it **is** a domain entry. Run the gates.
+- *"The upstream is well-maintained, we can just track it."* — Tracking
+  upstream means owning the diff, the breaking changes, and the migrations.
+  Tracking is maintenance work; budget for it under Gate 2 or skip the
+  adoption.
+- *"We'll add CI later."* — Later does not arrive. Either CI is wired in
+  the same plate, or the artefacts ship with explicit reference-only
+  headers so users do not assume validated coverage.
+- *"Council convergence is enough."* — Council informs the gates; it does
+  not replace them. A council session may surface that all three gates
+  pass; the roadmap still cites the evidence.
+- *"Demand-signal is the user asking once."* — Single-shot interest is a
+  watch trigger, not an open trigger. Either name the target use case
+  with project + timeline, or open a watch note and wait.
+
+## What to do when the gates fail
+
+1. Mark the domain plate `[-] gated — <gate name> not met` in the relevant
+   roadmap. Do **not** silently shrink scope to dodge the gate.
+2. Open a watch-only context note under `agents/settings/contexts/domain-watch/`
+   capturing what's missing — citations, owner candidates, CI feasibility.
+3. Re-evaluate at the next harvest cycle. The note is the evidence trail
+   so the same questions are not relitigated.
+
+## Allowed without gates
+
+- Adding **a single skill** to an **already-opened** domain follows the
+  regular harvest plate; the gates do not re-fire per skill.
+- Authoring a **guideline** that documents a domain the suite already
+  ships in — the domain is open, the guideline is a within-domain artefact.
+- A **rule** that constrains an already-opened domain — within-domain.
+
+## See also
+
+- [`augment-edit-discipline`](augment-edit-discipline.md) —
+  `dist/agent-src/` must stay project-agnostic and cross-references must stay
+  in sync; domain plates inherit both floors
+- [`size-enforcement`](size-enforcement.md) — size budgets apply per
+  artefact regardless of domain
+- [`rule-type-governance`](rule-type-governance.md) — within-domain rules
+  still pick `always` vs `auto` per the governance table
+- [`skill-quality`](skill-quality.md) — every domain skill passes the
+  same linter floor as a core skill

package/dist/agent-src/rules/external-reference-deep-dive.md

@@ -0,0 +1,72 @@
+---
+type: "auto"
+tier: "2b"
+description: "User names external repo/file/URL/artifact as reference — fetch the actual tree and inspect, never summarize from README or metadata"
+alwaysApply: false
+triggers:
+  - intent: "look at how X does it"
+  - intent: "compare with reference repo"
+  - intent: "use as template / vorlage"
+  - intent: "wie macht es X"
+  - intent: "vergleiche mit Y"
+  - intent: "schau dir Z an"
+  - intent: "study this competitor"
+  - keyword: "github.com/"
+  - keyword: "source of truth"
+  - phrase: "reference repo"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# external-reference-deep-dive
+
+## The Iron Law
+
+```
+EXTERNAL REFERENCE NAMED → DEEP-DIVE FIRST.
+NO README-ONLY SUMMARIES. NO METADATA GUESSES.
+INSPECT THE TREE, THE FRONTMATTER, THE CONFIGS, THE CODE.
+ABSENCE-OF-EVIDENCE IS NOT EVIDENCE — FETCH BEFORE CLAIMING.
+```
+
+Triggered when the user points to an external artifact (repo URL, `owner/repo`, file path, website, archive) **and** asks to analyze, compare, mirror, use as template, or "see how they do it". The user invested in naming the source — answer from the source, not from the cover.
+
+## Mandatory before drawing any conclusion
+
+1. **Use `/analyze-reference-repo`** (the canonical flow) when the artifact is a repo. Its Steps 2–5 are not optional shortcuts — they are the deep-dive contract: fetch listings (not just README), inspect key directories (`skills/`, `rules/`, `commands/`, `scripts/`, `.github/workflows/`, install configs, frontmatter samples), classify each axis adopt/adapt/reject/already.
+2. **For single files / websites** — fetch the actual content, not a summary. PDFs/DOCX/XLSX → `markitdown` first.
+3. **Cite verbatim** — every finding lands with a file path, line range, or URL fragment. "The README says X" is **not** a finding about implementation; it's a finding about marketing copy.
+4. **Surface what was inspected** — list the files / directories actually fetched, so the user can audit coverage.
+5. **"Not found" beats "probably not there"** — if a fetch budget was hit, say which subtrees are still un-inspected and ask before concluding absence.
+
+## Forbidden patterns
+
+- Reading only the README / homepage / package description and reporting capabilities.
+- Declaring "they don't support X" without listing the directories actually inspected.
+- Repeating a surface-level claim across turns without re-fetching when the user pushes back.
+- Treating `package.json` / `composer.json` keywords as evidence of behavior.
+- Summarizing a competitor's installer story from prose instead of reading `scripts/install*`, `bin/*`, or the npm `bin` field.
+
+## Failure mode catalog
+
+| Pattern | Why it fails | Fix |
+|---|---|---|
+| **README-summary-as-analysis** | Marketing prose ≠ implementation. Capabilities listed there may be aspirational, deprecated, or differently scoped. | Fetch the directory listing + 1–2 representative files per axis. |
+| **"Nothing matches" without enumeration** | Claims absence without proof. The user has to re-prompt to force the real lookup. | Before saying "no X", list the directories scanned. If the budget caps, ask which to expand. |
+| **Repeat-the-guess after pushback** | User says "really look" → agent re-paraphrases the same surface read. Burns trust. | On any pushback that names the source again, restart from a tree listing, not from prior notes. |
+| **Cross-tool path inference from a single example** | One config file ≠ a convention. | Inspect ≥2 unrelated tool integrations before claiming a pattern is the project's universal anchor strategy. |
+
+**Case-zero anchor.** May 2026 — an external reference suite was named as the source of truth for 23 AI-tool anchors. Three rounds of "we have no content for these tools" were reported from README inference. The actual `tool-configs/*.json` files in the reference repo gave the exact directory layout per tool in one fetch. Cost: ~2 hours of user frustration. Lesson: when an external source is named, the first action is `GET /repos/{o}/{r}/contents/{interesting-subtree}` — not paraphrase.
+
+## Escape hatch
+
+User explicitly fences the scope (*"quick scan only"*, *"just glance at the README"*, *"don't fetch the whole thing"*) → quick-scan path is allowed. Say so up front: *"Quick-scan mode per your scope — README + top-level layout only, not a full analysis."*
+
+## See also
+
+- Command [`/analyze-reference-repo`](../commands/analyze-reference-repo.md) — canonical deep-dive flow.
+- Rule [`think-before-action`](think-before-action.md) — sibling Iron Law for code paths in **this** repo; this rule is its mirror for **external** artifacts.
+- Rule [`ask-when-uncertain`](ask-when-uncertain.md) — when a fetch budget caps, ask which subtree to expand instead of guessing.
+- Skill [`markitdown`](../skills/markitdown/SKILL.md) — convert binary office formats before analysis.

package/dist/agent-src/rules/git-history-discipline.md

@@ -0,0 +1,148 @@
+---
+type: "auto"
+tier: "2a"
+alwaysApply: false
+description: "Git history ops — never rebase/squash/amend without request; never drop/exclude/force-over commits you didn't author (parallel / shared-PR work); once pushed, re-push same turn"
+triggers:
+  - intent: "rebase the branch"
+  - intent: "squash commits"
+  - intent: "clean up commit history"
+  - intent: "fold this into the previous commit"
+  - intent: "tidy history after pushing"
+  - intent: "reseat the branch base"
+  - intent: "exclude these commits from the branch"
+  - keyword: "git rebase"
+  - keyword: "rebase --onto"
+  - keyword: "reset --hard"
+  - keyword: "fixup"
+  - keyword: "--amend"
+  - keyword: "force-push"
+  - keyword: "--force-with-lease"
+  - keyword: "squash-merge"
+  - phrase: "branch diverged"
+  - phrase: "pull --rebase failed"
+  - phrase: "ahead and behind"
+  - phrase: "unexpected commits on the branch"
+  - phrase: "commits I did not create"
+routes_to:
+  - "skill:git-workflow"
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# Git History Discipline
+
+## Iron Law — Gate (no unsolicited rewrites)
+
+```
+NEVER REBASE, SQUASH, FIXUP, OR AMEND PUBLISHED OR LOCAL HISTORY
+WITHOUT THE USER ASKING FOR IT THIS TURN.
+LINEAR HISTORY IS A PREFERENCE, NOT A DEFAULT.
+COMMIT-CHUNK ORDER IS NOT A CORRECTNESS GOAL.
+```
+
+Add the next commit on top. Never reorder, fold, drop, or rewrite earlier
+commits to make the log "look right".
+
+## Iron Law — Protocol (once authorized)
+
+```
+ONCE PUSHED, A COMMIT IS PUBLISHED.
+ANY REWRITE OF PUSHED HISTORY MUST PAIR WITH AN IMMEDIATE RE-PUSH
+IN THE SAME TURN — OR DON'T REWRITE.
+NEVER END A SESSION WITH REWRITTEN-BUT-UNPUSHED LOCAL HISTORY.
+```
+
+## Iron Law — Inherited & shared-branch commits (never drop without asking)
+
+```
+COMMITS YOU DID NOT AUTHOR THIS SESSION ARE NOT YOURS TO DROP.
+NEVER EXCLUDE, RESET-AWAY, REBASE-OUT, OR FORCE-PUSH OVER A COMMIT
+THAT ALREADY EXISTS ON A BRANCH (LOCAL OR REMOTE) — WITHOUT ASKING
+THE USER THIS TURN. PARALLEL WORK IS THE DEFAULT, NOT THE EXCEPTION.
+```
+
+The user often works in parallel with the agent, and multiple agents may
+share one PR branch. A commit that looks "unrelated" or "stray" may be
+deliberate in-flight work the user expects to keep. Reseating a branch onto a
+different base, `git reset --hard`-ing away inherited commits, force-pushing
+over a branch you did not create, or branching from a base with unexpected
+commits and then "cleaning" them out all **silently discard work** — the exact
+failure this law prevents.
+
+Before ANY of these, STOP and ask (one numbered-options prompt per
+[`user-interaction`](user-interaction.md)):
+
+- reseating a branch's base (`git rebase --onto`, `git reset --hard <other-base>`)
+  in a way that drops commits already on the branch;
+- excluding / not-carrying-forward commits that were on the branch when you
+  started this session;
+- force-pushing (or `push <local>:<remote>`-replacing) a branch that carries
+  commits you did not author;
+- branching from a base with unexpected commits, then resetting them away.
+
+**Preserve-first is necessary but not sufficient.** Even when you keep the
+commits reachable (a save-branch / tag), you still **ask before** the branch
+the user sees loses them — "I preserved them locally" is not a substitute for
+the question, because the user may be mid-edit on the shared branch and a
+force-push would clobber their in-flight work regardless of your local backup.
+
+When in doubt about whether a commit is yours to touch: it is not. Ask.
+
+## When rewrite is allowed
+
+Exactly three:
+
+1. **User says so this turn** — "rebase onto main", "squash these two", "amend that". This operation only, not a standing rule.
+2. **Standing instruction not yet revoked** — the user said earlier in the conversation "always squash before pushing"; honor it.
+3. **Conflict resolution forced by `git pull --rebase`** — the user already invoked the rebase via pull; finish it.
+
+Anything else — chunk-tidiness, "logical order", folding a follow-up fix into its parent — **forbidden**. The follow-up ships as its own commit (`fix: …`, `chore: …`).
+
+## Two protective stops (for the protocol phase)
+
+1. **Pre-rewrite stop.** Before any squash / amend / rebase on a branch that is on origin: `git fetch && git rev-list --left-right --count HEAD...@{u}`. If **either** side is non-zero — STOP and route to `skill:git-workflow § Divergent-State Recovery`. A blind `git pull --rebase` in this state is the documented failure mode.
+
+2. **Post-rewrite stop.** After the rewrite, push in the **same turn** with `--force-with-lease=<branch>:<fetched-sha>` and verify `git rev-parse origin/<branch>` equals `git rev-parse HEAD`. If the push fails (hook, network, token budget) — fix the cause and re-push **before** ending the session, committing new work, or handing off.
+
+If either stop fires and resolution is not immediate → tag the state (`git tag local-rewritten-tip-<ISO-date>`) and hand control back to the user. Do not let a new session inherit a dirty divergence.
+
+## Equivalents that are also forbidden by default
+
+- `git rebase -i` (interactive)
+- `git rebase --autosquash`
+- `git commit --fixup` / `--squash` (helpers that feed autosquash)
+- `git commit --amend` on already-pushed commits
+- `git push --force` / `--force-with-lease` (unless paired with the protocol)
+- `git reset --hard` past unpushed work the user might want
+- Squash-merge of a PR via API or CLI when the user has not picked the merge strategy
+- Cherry-pick rewriting that drops or reorders commits
+
+`--amend` on the *current local* commit before the first push is the narrow exception (treated as continuing to compose the commit, not rewriting history).
+
+## Why this rule exists
+
+Interactive rebase + fixup loops generate disproportionate token cost on every iteration: re-running CI per replayed commit, resolving the same content conflict in three derived files (`.condensation-hashes.json`, `dist/router.json`, `.windsurfrules`), losing the working tree to a stash that silently re-introduces older state. A single conflict can burn the budget of an entire feature.
+
+A previous session squashed a pushed branch, the push hook failed at the token boundary, the session ended — and the next session saw local and origin pointing at different SHAs for the same logical work. A blind `git pull --rebase` cascaded into conflicts across every derived file. Recovery required forensic SHA-archaeology. The pre/post-rewrite stops make that sequence structurally impossible.
+
+## When you'd be tempted
+
+- "I want commit 3 to come before commit 2 because the topic flows better." → don't. Reviewers read the PR diff.
+- "There are two `chore: regenerate` commits, ugly." → don't. They are honest checkpoints.
+- "A linter caught an issue in commit 2 — let me fold the fix in." → don't. Add `fix(scope): …` on top.
+- "I want to drop the WIP commit before pushing." → ask the user first.
+- "Squash-merge when I open the PR will clean it anyway." → also true, also irrelevant — let the merge strategy do that work, not you.
+- "My branch inherited some unrelated commits — I'll reseat it on `origin/main` so my PR is clean." → **don't, ask first.** They may be the user's parallel work or another agent's. Preserve them and ask which base the user wants.
+- "The remote branch has commits I didn't author and no PR — I'll just force-push over it." → don't. No-PR is not no-owner; ask before replacing a branch you did not create.
+
+## See also
+
+- [`scope-control`](scope-control.md) — git-ops permission gate ("rebase" already named in the canonical list).
+- [`non-destructive-by-default`](non-destructive-by-default.md) — `reset --hard past unpushed work` and force-push are Hard-Floor triggers; the shared-branch Iron Law above is their commit-level companion.
+- [`user-interaction`](user-interaction.md) — the one-question-per-turn shape for the shared-branch ask.
+- [`commit-policy`](commit-policy.md) — commits are the user's call; rewriting them is a stronger version of the same restriction.
+- [`token-efficiency`](token-efficiency.md) — Iron Law on burning the user's tokens for cosmetic gain.
+- [`skill:git-workflow`](../skills/git-workflow/SKILL.md) — Safe Squash-After-Push protocol and Divergent-State Recovery decision tree.

package/dist/agent-src/rules/improve-before-implement.md

@@ -0,0 +1,124 @@
+---
+type: "auto"
+tier: "2b"
+description: "Before implementing features or architectural changes — validate request against existing code, challenge weak requirements, suggest improvements"
+alwaysApply: false
+council_depth: deep
+triggers:
+  - intent: "implement feature"
+  - intent: "architectural change"
+  - keyword: "refactor"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncondensed/"
+    reason: "Rule cites the authoring tree when describing where examples live."
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# Improve Before Implement
+
+## When to activate
+
+Before implementing:
+
+- New features
+- Refactoring or architectural changes
+- Module or service creation
+- Significant code changes that alter behavior
+
+**Does NOT activate for:**
+
+- Bug fixes (the problem is already defined)
+- Config changes, documentation, quality fixes
+- Tasks where the user said "just do it" or "skip validation"
+- Trivial changes (rename, typo, formatting)
+
+## What to check
+
+Before coding, quickly verify:
+
+### 1. Is the request clear?
+
+- Are acceptance criteria defined or derivable?
+- Is the scope bounded? (not "make it better" but "add X to Y")
+- Are edge cases considered?
+
+**If unclear** → ask ONE focused question. Max 2 questions, never an interrogation.
+
+### 2. Does it fit the existing architecture?
+
+- Does similar functionality already exist?
+- Does it follow established patterns in the codebase?
+- Does it contradict existing conventions?
+- Do **multiple valid patterns/frameworks** already exist (e.g. Tailwind + Flux, multiple form libraries, competing state stores)? If yes, do NOT pick one arbitrarily — ask which to use.
+- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`docs/guidelines/php/patterns/strategy.md`](../docs/guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+
+**If misfit** → show evidence (file references), propose alternative.
+**If multiple valid options** → list them, ask which to use. See [`no blind implementation`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
+
+### 3. Is the approach sound?
+
+- Is there a simpler way to achieve the same result?
+- Are there known problems with the requested approach?
+- Does the scope match the stated goal? (not over-engineered, not under-specified)
+
+**If problematic** → explain the concern, propose a better approach.
+
+## How to challenge
+
+- **Be concise** — one sentence per concern, not paragraphs
+- **Show evidence** — reference existing code, patterns, or conventions
+- **Offer alternatives** — don't just say "this is wrong"
+- **Use numbered options** — let the user choose quickly
+- **Respect "just do it"** — if the user insists after your challenge, execute immediately
+
+Example:
+
+```
+> ⚠️ `UserService` already has a `deactivate()` method that covers this case.
+>
+> 1. Use existing method — extend with new parameter
+> 2. Create new method anyway — I'll explain the overlap in a comment
+> 3. Skip validation — implement as requested
+```
+
+## The golden rule
+
+**Challenge to improve, never to refuse.**
+
+The agent is a thought partner, not a gatekeeper. After presenting concerns:
+- User picks an option → execute immediately
+- User says "just do it" → execute immediately
+- Never argue twice about the same point
+- Never block work — delay is only justified if it prevents a clear mistake
+
+## Scope limits
+
+- **Max 1-2 challenges per task** — not every request needs validation
+- **Max 1 minute of analysis** — if the check takes longer, skip it
+- **Never validate simple tasks** — only features, architecture, significant changes
+- **Never validate after the user already explained their reasoning**
+
+## Verify with concrete tools, not prose
+
+If the challenge requires you to confirm current behavior before proposing an alternative, use a concrete probe — a `curl` against the endpoint, a Playwright spec, a debugger / `xdebug` step-through, or the project's test runner with a targeted filter. Asserting current behavior from memory is not validation.
+
+## Intent inference (RDP, standard host)
+
+When the literal request and the underlying goal may differ, **state the inferred
+goal in one line and give ONE recommendation** — do not spread 2–3 framings (that
+is the overplanning [`direct-answers`](direct-answers.md) suppresses). Standard
+host only; a strong-reasoning host self-infers, so skip it there. Engage per
+[`rdp-gate`](../contexts/execution/rdp-gate.md).
+
+## Creating new agent artifacts
+
+When the request is to create or significantly rewrite a skill, rule, command,
+or guideline, the "fit the existing architecture" check above is handled by
+[`artifact-drafting-protocol`](artifact-drafting-protocol.md)'s Phase B
+(Research). Follow that protocol instead of improvising a one-shot check — it
+scans `.agent-src.uncondensed/` for overlap and reports candidates to extend
+before creating a new file.