@event4u/agent-config 1.14.0 → 1.15.0

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -0,0 +1,143 @@
+---
+stability: beta
+---
+
+# Linear AI — rules inclusion list
+
+> Phase 3 Step 1 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
+> Per-rule decision for the Linear AI rules digest. The digest is a
+> Markdown blob the user pastes into Linear's `Settings → Agents →
+> Additional guidance` (workspace / team / personal). The third-party
+> agent (Codegen, Charlie, Cursor's Linear app, …) reads it verbatim —
+> no skill triggering, no script execution, no `.augment/` access.
+>
+> Source of tier data: `python3 scripts/audit_cloud_compatibility.py
+> --details` (47 rules: T1=20, T2=19, T3-S=8).
+>
+> Last refreshed: 2026-04-29.
+
+## Inclusion criteria
+
+- **Workspace** — universal coding posture and interaction discipline.
+  Survives without filesystem, scripts, or this package's tooling.
+- **Team** — framework-specific (Laravel, PHP, E2E with Playwright).
+  Only applied where the team uses that stack.
+- **Personal** — empty by default; reserved for individual preferences
+  the user may add manually.
+- **Excluded** — meta-rules about authoring this package, Augment Code
+  specifics, or rules already declared `cloud_safe: noop`.
+
+Two transformations the digest builder (Phase 3 Step 2) must apply
+to *included-degraded* rules:
+
+1. Strip references to scripts, `.agent-settings.yml`, `.agent-src/`,
+   `.augment/`, `agents/`, and `task <foo>` invocations.
+2. Replace `[link](path)` to other rules/skills/files with a footnote
+   or inline summary, since the path won't resolve outside this repo.
+
+## Workspace digest (18 rules)
+
+Universal coding posture — applies to every team regardless of stack.
+
+| Rule | Tier | Mode | Notes |
+|---|---|---|---|
+| `ask-when-uncertain` | T1 | as-is | One-question-per-turn iron law; strip cross-refs to `user-interaction` / `artifact-drafting-protocol` |
+| `commit-conventions` | T1 | as-is | Generic Conventional Commits |
+| `context-hygiene` | T1 | as-is | Conversation freshness, 3-Failure Rule, tool-loop detection; strip Augment-specific `.augmentignore` section |
+| `direct-answers` | T1 | as-is | Iron Laws (no flattery, no invented facts, brevity); strip emoji whitelist refs to other rules |
+| `markdown-safe-codeblocks` | T1 | as-is | Generic markdown safety |
+| `minimal-safe-diff` | T1 | as-is | Universal coding discipline |
+| `reviewer-awareness` | T1 | as-is | Anchor reviewer choice in paths and risk |
+| `scope-control` | T1 | as-is | Universal scope discipline + git-ops permission gating |
+| `security-sensitive-stop` | T1 | as-is | Stop-and-threat-model on security-sensitive paths |
+| `think-before-action` | T1 | degraded | Strip `memory-access` guideline ref (no shared memory on Linear) |
+| `verify-before-complete` | T1 | as-is | Evidence gate; the tool list (PHPStan etc.) is illustrative, harmless |
+| `cli-output-handling` | T2 | degraded | Keep "use targeted output, not full dumps"; strip `rtk` Iron Law (rtk is a local tool) |
+| `downstream-changes` | T2 | as-is | Universal post-edit propagation |
+| `improve-before-implement` | T2 | as-is | Challenge weak requirements before implementing |
+| `language-and-tone` | T2 | degraded | Keep mirroring + tone; strip "all `.md` docs must be English" clause (no `.md` files on Linear) |
+| `missing-tool-handling` | T2 | as-is | Don't install silently |
+| `token-efficiency` | T2 | degraded | Strip `.agent-settings.yml` references (`personal.minimal_output`, `personal.play_by_play`) |
+| `user-interaction` | T3-S | degraded | Numbered-options Iron Law, single-source recommendation; strip `scripts/check_reply_consistency.py` reference |
+
+## Team digest (4 rules)
+
+Framework-specific. Only paste into the Team layer of teams that use
+the stack. Each rule already names the stack in its own trigger line,
+so nothing to strip.
+
+| Rule | Tier | Stack | Notes |
+|---|---|---|---|
+| `docker-commands` | T1 | Docker / Laravel | Container-prefixed CLI for artisan/composer/phpunit |
+| `laravel-translations` | T1 | Laravel | `__()` helper, `lang/de`, `lang/en` |
+| `e2e-testing` | T2 | Playwright | Locators, Page Objects, fixtures, flake prevention |
+| `php-coding` | T2 | PHP | Strict types, naming, comparisons, Eloquent conventions |
+
+## Personal digest (0 rules)
+
+Empty by default. The user may paste individual preferences (preferred
+naming, IDE-specific shortcuts, response language overrides) into this
+layer manually. The digest builder emits an empty stub with a comment.
+
+## Excluded (25 rules) — categorised
+
+### Meta — about authoring this package (20)
+
+These rules govern how skills/rules/commands are created, kept in sync,
+and shipped from this repository. They have no meaning for a third-party
+agent that does not maintain `event4u/agent-config`.
+
+`agent-docs`, `architecture`, `artifact-drafting-protocol`,
+`augment-portability`, `augment-source-of-truth`, `capture-learnings`,
+`docs-sync`, `guidelines`, `package-ci-checks`, `preservation-guard`,
+`review-routing-awareness`, `roadmap-progress-sync`,
+`role-mode-adherence`, `rule-type-governance`, `runtime-safety`,
+`size-enforcement`, `skill-improvement-trigger`, `skill-quality`,
+`tool-safety`, `upstream-proposal`.
+
+### Augment Code specifics (3)
+
+These reference Augment-only mechanics — model identity in Augment's
+system prompt, Augment's `/slash` command surface, and the Augment
+onboarding flow gated by `.agent-settings.yml`.
+
+`model-recommendation`, `onboarding-gate`, `slash-commands`.
+
+### Skill-routing only (1)
+
+`analysis-skill-routing` — routes to one of our `analysis-*` skills.
+Skills do not exist on Linear AI; the third-party agent has its own
+capability surface.
+
+### Already declared inert on cloud (1)
+
+`chat-history` — carries `<!-- cloud_safe: noop -->` by design. No
+persistence on cloud platforms; the rule is a no-op.
+
+## Open follow-ups
+
+- **Phase 3 Step 2** (`scripts/build_linear_digest.py`) implements the
+  two transformations above (strip script/path/setting refs, replace
+  cross-refs with inline summaries or footnotes). Pin the *degraded*
+  set in the script's source so a human can audit which rules ship
+  modified vs. as-is.
+- **Phase 3 Step 4 char-budget test** — Linear's per-field char limit
+  is still unresearched (Open Question #1 in the roadmap). Before the
+  test is wired, run a quick recon and capture the value. The
+  conservative fallback (~30 KB) probably fits this 18-rule workspace
+  digest without contention; team layer is far smaller.
+- **Phase 3 Step 3 three-layer split** — this document already
+  partitions workspace / team / personal. Step 3 only needs to
+  document the three-layer rationale for the README.
+- Re-classify on every audit run; if a rule is added to
+  `.agent-src.uncompressed/rules/`, this document MUST gain a row.
+
+## Source of tier data
+
+```
+python3 scripts/audit_cloud_compatibility.py --details --format json
+```
+
+47 rules: T1=20, T2=19, T3-S=8. Counts in this document derive from the
+above; if they drift, this document is stale and the digest builder
+must refuse to emit until reconciled.

package/docs/contracts/linear-ai-three-layers.md

@@ -0,0 +1,131 @@
+---
+stability: beta
+---
+
+# Linear AI — three-layer split rationale
+
+> Phase 3 Step 3 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
+> Per-rule routing is in [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md);
+> this file documents *why* the split is workspace / team / personal and
+> what belongs in each.
+
+## The three slots Linear gives us
+
+`Settings → Agents → Additional guidance` exposes three text fields:
+
+| Field | Scope | Inheritance | Editable by |
+|---|---|---|---|
+| **Workspace** | Whole organisation | Inherited by every team and every member | Workspace admins |
+| **Team** | One Linear team | Overrides workspace for that team's issues | Team admins |
+| **Personal** | One member, on their own assigned issues | Layered on top of workspace + team | The member |
+
+Linear's docs frame this as **most-specific-wins**: when an agent is
+linked to a Linear issue, it reads workspace + team + personal
+concatenated, with later layers overriding earlier ones. The third-party
+agent (Codegen, Charlie, Cursor's Linear app, …) receives the bytes
+verbatim — no filesystem, no skill triggering, no `.augment/` access.
+
+## Our mapping — workspace / team / personal
+
+The inclusion list partitions our 47 rules into three mutually exclusive
+buckets. Counts and per-rule decisions live in
+[`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md); this
+section explains the *principle* behind each bucket.
+
+### Workspace — universal coding posture (18 rules)
+
+Goes into the **Workspace** field. Rules that:
+
+- Apply regardless of stack (PHP, Node, Python, Go, …)
+- Govern *interaction discipline* — when to ask, how to commit, how to
+  surface options, how to push back on weak reviews
+- Survive without filesystem, scripts, or this package's tooling
+- Carry no Augment-specific or repo-authoring scaffolding
+
+Examples: `ask-when-uncertain`, `commit-conventions`, `direct-answers`,
+`minimal-safe-diff`, `scope-control`, `verify-before-complete`,
+`user-interaction`. Anything that helps a generic third-party agent
+behave like a competent engineer on *any* codebase.
+
+A few rules in this bucket are **degraded** — the digest builder strips
+the local-only sections (rtk, `.agent-settings.yml`, `.augment/` paths,
+`.md`-files-must-be-English clause). The substance survives; the tooling
+references don't.
+
+### Team — framework-specific (4 rules)
+
+Goes into the **Team** field of teams that match the stack. Rules that:
+
+- Name a specific framework, language, or tool in their trigger line
+- Carry conventions that only fire when that stack is touched
+- Don't apply to teams using a different stack (a frontend-only team
+  doesn't need the PHP rules)
+
+Currently four rules: `docker-commands`, `laravel-translations`,
+`e2e-testing` (Playwright), `php-coding`. Each rule already names its
+stack, so the digest builder ships them as-is — no per-rule stripping.
+
+If the org has a Node-only team, paste only `e2e-testing`. If a
+Laravel-Docker team, paste all four. The Team layer is per-team, not
+universal.
+
+### Personal — empty by default (0 rules)
+
+Goes into the **Personal** field of individual members. Empty stub by
+default. Each developer pastes their own preferences into this layer
+manually. Examples a member might add:
+
+- Response language overrides ("respond in German on my issues")
+- Personal naming conventions ("I prefer `result_` prefixes for outputs")
+- Individual IDE shortcuts they want surfaced in PR descriptions
+- Scoped opt-outs from a workspace rule, with a one-sentence reason
+
+The digest builder emits an empty stub with a comment line so members
+have a starting point, but the file is intentionally minimal — the
+package does not own personal preferences.
+
+## Why this split, not a flat blob
+
+Three reasons we don't merge everything into one workspace digest:
+
+1. **Stack-specific noise.** A frontend-only team doesn't need 4 KB of
+   Laravel + PHP + Docker conventions cluttering their guidance field.
+   Pushing those into Team layers keeps the workspace lean and
+   universal.
+2. **Per-team override surface.** When a team needs to override a
+   workspace rule (e.g. their own commit-message convention), Linear's
+   layering already gives them the surface. We don't need to fork the
+   workspace digest per team.
+3. **Personal autonomy.** Members own the Personal layer. The package
+   never writes there; it's the user's escape hatch for individual
+   preferences without lobbying for a workspace-wide rule change.
+
+## Excluded from all three layers (25 rules)
+
+[`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md) §
+"Excluded" covers the four categories: meta-rules about authoring this
+package (20), Augment Code specifics (3), skill-routing only (1),
+already-cloud-inert (1). None of these benefit a third-party agent that
+does not maintain `event4u/agent-config`.
+
+## Future evolution
+
+- **More stacks → more team rules.** When the package gains a Node,
+  Python, or Go equivalent of `php-coding`, the Team digest grows. The
+  decision criterion stays: stack-named in the trigger line → Team;
+  stack-agnostic → Workspace.
+- **Workspace stays bounded.** Adding new universal rules is fine, but
+  the workspace digest should not grow to swamp Linear's per-field cap.
+  Current digest is well under the 100 KB safety budget; if growth
+  approaches the cap, split workspace by *concern* (interaction vs.
+  code-shape vs. delivery) rather than relaxing the cap.
+- **Personal layer stays empty in this package.** Even if patterns
+  emerge, they belong in workspace (if universal) or team (if
+  stack-bound), not in a curated personal blob the package owns.
+
+## Source of truth
+
+- Per-rule decision: [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md)
+- Builder script: [`scripts/build_linear_digest.py`](../../scripts/build_linear_digest.py)
+- Generated digests: `dist/linear/{workspace,team,personal}.md` (gitignored)
+- Roadmap: [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md) Phase 3

package/docs/contracts/rule-interactions.md

@@ -0,0 +1,107 @@
+---
+stability: beta
+---
+
+# Rule-Interaction Matrix
+
+> **Audience:** rule authors and reviewers — anyone editing
+> `.agent-src.uncompressed/rules/*.md` or proposing a new always-rule.
+> **Authoritative source:** [`rule-interactions.yml`](rule-interactions.yml).
+> **Linter:** `scripts/lint_rule_interactions.py` (run via `task lint-rule-interactions`).
+
+The matrix captures how the package's `always` rules relate when more
+than one fires on the same turn. It exists because rules at this size
+(55 rules, ~49k tokens budget) develop emergent precedence relationships
+that no single rule file can document on its own.
+
+The anchor pair is `non-destructive-by-default` — the universal safety
+floor — paired with the five rules most likely to be invoked in the
+same turn:
+
+- `autonomous-execution` — autonomy never lifts the floor.
+- `scope-control` — git-ops permission gate; floor is the never-overridable subset.
+- `commit-policy` — four exception paths to commit; floor still gates the diff content.
+- `ask-when-uncertain` — both rules push toward the same response on a destructive ambiguous request.
+- `verify-before-complete` — independent gates; both must be satisfied.
+
+## Diagram
+
+```mermaid
+graph LR
+  NDD["non-destructive-by-default<br/>(Hard Floor)"]
+  AE["autonomous-execution"]
+  SC["scope-control"]
+  CP["commit-policy"]
+  AWU["ask-when-uncertain"]
+  VBC["verify-before-complete"]
+
+  NDD -- "overrides" --> AE
+  NDD -- "restates" --> SC
+  NDD -- "gates diff" --> CP
+  NDD -- "complements" --> AWU
+  NDD -- "complements" --> VBC
+
+  SC -- "gates git ops" --> AE
+  CP -- "overrides<br/>commit Q" --> AE
+
+  classDef floor fill:#7a1f1f,stroke:#fff,color:#fff,font-weight:bold
+  classDef gate fill:#1f4f7a,stroke:#fff,color:#fff
+  class NDD floor
+  class SC,CP gate
+```
+
+## Relations
+
+The YAML uses six relation kinds. Definitions:
+
+| Relation | Meaning |
+|---|---|
+| `overrides` | Senior rule's outcome wins when both fire — junior's permission cannot proceed past senior's stop. |
+| `narrows` | Senior shrinks the surface area on which junior applies, but does not stop it. |
+| `defers_to` | Junior explicitly hands over to senior on the overlapping surface. |
+| `restates` | The two rules cover overlapping ground intentionally — the restatement prevents future weakening of one side. |
+| `gates` | Senior fires *in addition to* junior on a specific subset, not instead of. |
+| `complements` | Both rules independently apply; outcomes are additive and harmonious. |
+
+## Reading a pair entry
+
+```yaml
+- id: ndd-x-autonomous-execution
+  rules: [non-destructive-by-default, autonomous-execution]   # senior, junior
+  relation: overrides
+  conflict: …                                                  # what triggers both
+  resolution: …                                                # what the agent does
+  evidence:
+    - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+    - .agent-src.uncompressed/rules/autonomous-execution.md#hard-floor--see-non-destructive-by-default
+```
+
+`rules: [a, b]` is ordered: `a` is senior (wins on conflict), `b` is
+junior (yields). For `complements`, ordering is documentary only.
+
+## Adding a new pair
+
+1. Edit `rule-interactions.yml`, append a pair under `pairs:` with all
+   six required fields.
+2. Add both rule slugs to the top-level `rules:` block if not already
+   listed.
+3. Run `task lint-rule-interactions` — must exit 0.
+4. Update the Mermaid diagram above if the pair is anchor-relevant
+   (involves `non-destructive-by-default` or one of its five partners).
+5. Reference the matrix from the rule files that are involved (one
+   line each — the matrix is the source, not the rules).
+
+## When **not** to add a pair
+
+- Two rules that never fire on the same turn — no interaction means
+  no entry; the matrix is for *active* relationships.
+- Documentation-only cross-references (e.g. "see also") — those stay
+  in the rule files.
+- Skill ↔ rule interactions — the matrix is rule-only. Skills are
+  invoked, not always-active.
+
+## See also
+
+- [`docs/contracts/STABILITY.md`](STABILITY.md) — public-surface stability tiers.
+- [`docs/contracts/adr-chat-history-split.md`](adr-chat-history-split.md) — ADR pattern for major rule structural changes.
+- [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](../../agents/roadmaps/archive/road-to-post-pr29-optimize.md) § P2.2 — anchor for this matrix.

package/docs/contracts/rule-interactions.yml

@@ -0,0 +1,142 @@
+# Rule-Interaction Matrix
+# -----------------------
+# Machine-readable contract for how the package's `always` rules relate
+# when more than one fires on the same turn. Linted by
+# `scripts/lint_rule_interactions.py`. Rendered diagram in
+# `docs/contracts/rule-interactions.md`.
+#
+# Schema:
+#   version: integer
+#   rules: list of rule slugs that participate in any interaction (each
+#     must exist as `.agent-src.uncompressed/rules/<slug>.md`)
+#   pairs: list of pairwise interactions
+#     - id:        kebab-case stable identifier
+#       rules:     [senior, junior] — `senior` wins on conflict
+#       relation:  overrides | narrows | defers_to | restates | gates | complements
+#       conflict:  one-line trigger that causes both to fire
+#       resolution: one paragraph — what the agent does
+#       evidence:  list of `file#anchor` citations
+#       tests:     optional list of test paths
+#
+# Anchor pair: `non-destructive-by-default` × five rules per
+# `road-to-post-pr29-optimize.md` Phase 2.
+
+version: 1
+
+rules:
+  - non-destructive-by-default
+  - autonomous-execution
+  - scope-control
+  - commit-policy
+  - ask-when-uncertain
+  - verify-before-complete
+
+pairs:
+
+  - id: ndd-x-autonomous-execution
+    rules: [non-destructive-by-default, autonomous-execution]
+    relation: overrides
+    conflict: >-
+      Standing autonomy directive ("arbeite selbstständig") is active and
+      the next step crosses a Hard-Floor trigger (production-branch merge,
+      deploy, push, prod data/infra, whimsical bulk deletion, commit with
+      bulk deletion / infra change).
+    resolution: >-
+      Autonomy never lifts the floor. Stop, surface the action via one
+      numbered-options block, wait for explicit user confirmation on
+      this turn before proceeding.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/autonomous-execution.md#hard-floor--see-non-destructive-by-default
+
+  - id: ndd-x-scope-control
+    rules: [non-destructive-by-default, scope-control]
+    relation: restates
+    conflict: >-
+      Push, merge, branch creation, PR ops, tag pushes — both rules speak
+      to the same git operations.
+    resolution: >-
+      `scope-control` is the canonical permission gate; the floor restates
+      the prod-trunk and deploy-tied subset so the never-overridable layer
+      cannot be weakened by future scope-control edits. On any conflict,
+      the floor wins.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+      - .agent-src.uncompressed/rules/scope-control.md#production-infrastructure-bulk-destructive--hard-floor
+
+  - id: ndd-x-commit-policy
+    rules: [non-destructive-by-default, commit-policy]
+    relation: gates
+    conflict: >-
+      A commit is otherwise authorized by one of `commit-policy`'s four
+      paths (user-this-turn, standing instruction, `/commit*` invocation,
+      roadmap pre-scan), but the diff contains bulk deletions or infra
+      changes (row 6 of the Hard Floor).
+    resolution: >-
+      The commit pre-scan triggers regardless of which authorization path
+      applies. Surface the diff (paths + counts), confirm this turn,
+      then commit. The four exceptions cover *whether* commits happen;
+      the floor covers *which diffs* still need a separate confirmation.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/commit-policy.md#hard-floor-still-applies--bulk-deletions-and-infra-changes
+
+  - id: ndd-x-ask-when-uncertain
+    rules: [non-destructive-by-default, ask-when-uncertain]
+    relation: complements
+    conflict: >-
+      A floor trigger fires AND the request is ambiguous (e.g. "delete
+      the legacy folder" without a file list).
+    resolution: >-
+      Both rules require the same response — stop and ask. The floor
+      provides the categorical reason (destructive); ask-when-uncertain
+      provides the question shape (one numbered-options block, blocking).
+      No conflict; both fire harmoniously.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#failure-modes
+      - .agent-src.uncompressed/rules/ask-when-uncertain.md#vague-request-triggers--must-ask
+
+  - id: ndd-x-verify-before-complete
+    rules: [non-destructive-by-default, verify-before-complete]
+    relation: complements
+    conflict: >-
+      A floor-crossing action (deploy, prod-data write) was authorized
+      and executed; agent is about to claim "done".
+    resolution: >-
+      Both rules apply independently. Floor is satisfied by user
+      confirmation; verify-before-complete is satisfied by fresh
+      verification evidence in the same message. Skipping either is a
+      rule violation.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/verify-before-complete.md#the-iron-law
+
+  - id: autonomy-x-scope-control
+    rules: [scope-control, autonomous-execution]
+    relation: gates
+    conflict: >-
+      Autonomy is `on` and the next step is a permission-gated git
+      operation (push, branch create/delete, PR open, tag push) below
+      the floor threshold.
+    resolution: >-
+      `scope-control`'s permission gate stays in force. Autonomy
+      suppresses *trivial* questions only; git-shape decisions are
+      blocking. Stop and ask.
+    evidence:
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+      - .agent-src.uncompressed/rules/autonomous-execution.md#blocking--still-ask-regardless-of-personalautonomy
+
+  - id: autonomy-x-commit-policy
+    rules: [commit-policy, autonomous-execution]
+    relation: overrides
+    conflict: >-
+      Autonomy is `on` and the agent could plausibly "just commit" after
+      a green verification step.
+    resolution: >-
+      `commit-policy` Iron Law forbids both committing AND asking about
+      committing unless one of the four exceptions applies. Autonomy
+      does not add a fifth exception.
+    evidence:
+      - .agent-src.uncompressed/rules/commit-policy.md#the-iron-law
+      - .agent-src.uncompressed/rules/autonomous-execution.md#commit-policy--see-commit-policy