@event4u/agent-config 9.8.0 → 9.9.0

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

@@ -1,143 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Linear AI — rules inclusion list
-
-> 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: `./scripts-run src/scripts/audit_cloud_compatibility
-> --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`, `dist/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`, `source-of-truth`, `capture-learnings`,
-`docs-sync`, `guidelines`, `package-ci-checks`, `preservation-guard`,
-`reviewer-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-command-routing-policy`.
-
-### 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.uncondensed/rules/`, this document MUST gain a row.
-
-## Source of tier data
-
-```
-./scripts-run src/scripts/audit_cloud_compatibility --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

@@ -1,130 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Linear AI — three-layer split rationale
-
-> 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`](../../src/scripts/build_linear_digest.py)
-- Generated digests: `dist/linear/{workspace,team,personal}.md` (gitignored)

package/docs/contracts/linter-structural-model.md

@@ -1,181 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Linter Structural Model
-
-**Status:** LOCKED — shipped 2026-05-08 on
-`feat/road-to-structural-linter-reform`. The linter now applies the
-structural model to skills, rules, and commands.
-
-## Why a structural model
-
-Council convergence (Sonnet + GPT-4o, 2026-05-06): raw line / word
-counts produce ratchet drift. Three failure modes that the pure-size
-gate cannot distinguish:
-
-- A 500-line skill with **one** 10-step procedure (legitimate) vs a
-  500-line skill with **ten** independent procedures (split candidate).
-- A 1700-word command that **delegates** to a cluster (legitimate
-  orchestrator) vs a 1700-word command that **inlines** the work.
-- A 60-line rule whose body is a **verbatim Iron-Law block**
-  (legitimate) vs a 60-line rule that is **prose explanation**
-  (split candidate).
-
-The structural model replaces the size threshold with four primitives.
-
-## Primitives
-
-### 1. Density score (0.0 – 1.0)
-
-```
-density = structured_lines / total_non_blank_lines
-```
-
-`structured_lines` = lines inside fenced blocks + markdown-table rows
-+ bullet-list lines + numbered-list lines + section-heading lines.
-Higher = more structured (catalogue, table, code, list); lower =
-prose-dominant.
-
-### 2. Multi-workflow detector (skills only)
-
-Skills with **≥ 2 `## Procedure`** (or `## Procedure: <name>`)
-sections ship multiple independently invocable procedures. Combined
-with size, this is the cluster-split signal.
-
-### 3. Delegation detector (commands only)
-
-Command has a delegation signal when **either** holds:
-
-- frontmatter declares `cluster:` or `routes_to:`
-- body contains ≥ 3 markdown links to other `.md` files
-
-Absence of both signals on a large command = inlined logic.
-
-### 4. Iron-Law block detector (rules only)
-
-A fenced block is an Iron-Law block when its body has **≥ 30
-alphabetical characters** with **≥ 60 % uppercase** across **≥ 1
-non-empty line**. The 30-character floor filters single ALL-CAPS
-markers (`OK`, `WIP`); the 60 % uppercase floor catches verbatim
-imperatives (`NEVER COMMIT.`).
-
-## Phase 1 calibration (2026-05-08)
-
-Sweep covered all 310 lintable artifacts via
-[`scripts/measure_density.py`](../../src/scripts/measure_density.py); raw
-data lives at `agents/runtime/density/snapshot.jsonl` (local-only — re-run
-`./scripts-run src/scripts/measure_density --root dist/agent-src --jsonl
-agents/runtime/density/snapshot.jsonl` to regenerate).
-
-| Type | Count | Avg density | Median | Bucket [0.4-0.6] | Bucket [0.6-1.0] |
-|---|---|---|---|---|---|
-| skill | 142 | 0.76 | 0.78 | 22 | 119 |
-| command | 103 | 0.59 | 0.57 | 46 | 45 |
-| rule | 58 | 0.47 | 0.48 | 25 | 11 |
-| persona | 7 | 0.38 | 0.38 | 1 | 0 |
-
-Iron-Law detector recall on 9 canonical Iron-Law rules: **8 / 9** (all
-except `agent-authority`, which uses a markdown-table index instead of
-a fenced block — correct miss).
-
-`quality-tools` (411 lines, single workflow): density **0.83**, single
-procedure → no warning under the new model. ✓ roadmap success criterion.
-
-`optimize/augmentignore.md` (1679 words): delegation signal **present**
-(frontmatter `routes_to:`) → no warning under the new model. ✓ roadmap
-success criterion.
-
-Of 13 commands ≥ 1000 words, only **2** lack a delegation signal —
-both are candidates for Phase 4.1 review (`condense.md`,
-`project-analyze.md`; the latter has density 0.86, exempt under the
-density-AND-delegation gate).
-
-## Warn rules (shipped Phase 3, 2026-05-08)
-
-| Artifact | Warn condition |
-|---|---|
-| **skill** | `lines > 400` AND (`density < 0.6` OR `procedures ≥ 2`) |
-| **command** | `words > 1000` AND no delegation signal AND `density < 0.65` |
-| **rule** | `lines > 60` AND `density < 0.5` AND `iron_law_blocks == 0` |
-
-The 200-line rule **error** stays unconditional. No new frontmatter
-keys ship — the four structural primitives are the contract.
-
-Calibration sweep on the 2026-05-08 corpus (310 artifacts):
-
-| Type | Old warns | New warns | New band | Δ |
-|---|---|---|---|---|
-| rule | 23 | 2 | 3.4 % | −91 % |
-| skill | 2 | 1 | 0.7 % | −50 % |
-| command | 9 | 1 | 1.0 % | −89 % |
-| **total** | **34** | **4** | **1.3 %** | **−88 %** |
-
-Pass rate: 186 → 209 (`pass`); 124 → 101 (`pass_with_warnings`); 0
-errors. Each remaining warning is a genuine structural defect:
-
-- `condense.md` (1569 words, density 0.58, no delegation signal) —
-  inlined logic in a non-orchestrator command.
-- `artifact-drafting-protocol.md` rule (65 lines, density 0.37, no
-  Iron-Law block) — prose-dominant long rule.
-- `minimal-safe-diff.md` rule (69 lines, density 0.41, no Iron-Law
-  block) — prose-dominant long rule.
-- `ai-council/SKILL.md` (525 lines, density 0.37) — orchestrator
-  skill below the density floor; refactor candidate.
-
-Roadmap target ≤ 10 % rule-warning band. ✓ (3.4 %)
-
-## Frontmatter contract — Phase 2 decisions (2026-05-08)
-
-AI Council run (Claude Sonnet 4.5 + GPT-4o, 2 rounds, $0.046; raw
-transcript local-only per the council-references convention).
-
-**Key 1 — `iron_law:` frontmatter — DECISION: Option A (auto-detect, no tag).**
-
-Both council members converged on Option A. The detector recall on
-the canonical 9-rule set is 8 / 9, and the one miss
-(`agent-authority`) uses a markdown-table priority index that is
-**not** an Iron-Law imperative — its body delegates to the rules it
-indexes. The detector is correct to skip it. No `iron_law:`
-frontmatter key is added.
-
-**Key 2 — `density_exempt:` frontmatter — DECISION: Option A (no flag).**
-
-Council split:
-
-- Sonnet 4.5: Reject any flag. Add **type-based density floors**
-  (orchestrators 0.35, executors 0.6, imperatives 0.4) so the
-  detector classifies structurally instead of relying on author
-  declarations.
-- GPT-4o: Adopt Option C (`density_exempt: true` + required
-  `density_exempt_reason:`) with periodic re-audit.
-
-Sonnet's structural argument carries: an escape hatch for a 1-in-142
-corpus case ships maintenance debt across every future artifact that
-brushes the boundary. The single failing skill (`ai-council`,
-density 0.36) is a documentation-heavy reference-orchestrator and is
-left as a Phase-4 review candidate — either restructure the skill or
-add orchestrator-aware type-floors as a follow-up. No
-`density_exempt:` key is added in Phase 3.
-
-The Phase-3 implementation therefore ships **zero new frontmatter
-keys** — the structural primitives are the contract.
-
-## Out of scope
-
-- Hard error thresholds beyond the 200-line rule cap.
-- Automatic refactoring of artifacts that fail the new model.
-- Cross-artifact dependency counts (a skill linking 4 other skills is
-  `routes_to` doing its job, not a defect).
-
-## References
-
-- `scripts/measure_density.py` — Phase 1.1 measurement tool.
-- `agents/runtime/density/snapshot.jsonl` — full per-artifact metrics
-  (gitignored, re-run the measurement script to regenerate).
-- `scripts/skill_linter.py` — structural-model implementation
-  (`_density_score`, `_count_procedure_sections`,
-  `_command_delegation_signal`, `_iron_law_blocks`).
-- `docs/guidelines/agent-infra/size-and-scope.md` — guideline now
-  describes the structural model; Option 2 transition notes removed.