@event4u/agent-config 1.9.1

package/.agent-src/templates/agents/proposal.example.md

@@ -0,0 +1,143 @@
+---
+# proposal.example.md — curated self-improvement proposal
+#
+# Used by the five-stage pipeline in road-to-curated-self-improvement.md:
+#   capture → classify → propose → gate → upstream
+#
+# An agent drafting a rule/skill/guideline change in a consumer project
+# produces this doc and hands it to `upstream-contribute`. The gate
+# (`scripts/check_proposal.py`) verifies evidence, scope, and
+# portability before a PR is opened.
+#
+# Copy this file, fill every field, run `task check-proposal`, commit.
+
+proposal_id: ""                    # stable kebab-case slug, unique per repo
+type: ""                           # rule | skill | command | guideline
+scope: ""                          # project | package
+stage: proposed                    # captured | classified | proposed | gated | upstream
+source_learning: ""                # agents/learnings/<date>-<slug>.md
+target_artifact: ""                # .agent-src/<type>/<name>.md (for upstream scope)
+                                   # or agents/overrides/<...> (for project scope)
+author: ""                         # name or team slug
+created: 2026-01-01                # ISO date
+last_updated: 2026-01-01
+---
+
+# Proposal: <short title>
+
+## 1. Learning
+
+**What happened.** One paragraph, no log excerpts, no names. State
+the pattern, not the anecdote.
+
+> Example:
+> *Across 3 PRs in the `Billing` module, reviewers flagged the
+> same omission: mass-assignable attributes on `Payment` that
+> should be guarded. No existing skill covers this path.*
+
+## 2. Classification
+
+Check exactly one box per line.
+
+- **Scope:** [ ] project-local only  [ ] upstream (applies broadly)
+- **Type:** [ ] rule  [ ] skill  [ ] command  [ ] guideline
+- **Replaces existing:** [ ] yes → `<target_artifact>`  [ ] no → new artifact
+- **Urgency:** [ ] blocking  [ ] this quarter  [ ] opportunistic
+
+**Why this scope / type.** Two sentences max. The gate rejects
+proposals where scope is `upstream` but the evidence is single-repo.
+
+## 3. Evidence
+
+At least TWO independent references. The gate rejects proposals
+with fewer than two `source` entries, or with entries that all
+resolve to the same PR / incident / repository.
+
+```yaml
+evidence:
+  - kind: pr           # pr | issue | incident | review-comment | test-failure
+    ref: https://github.com/example/repo/pull/1234
+    summary: Reviewer caught the same omission as PR #1187 and #1221.
+  - kind: review-comment
+    ref: https://github.com/example/repo/pull/1221#discussion_r556677
+    summary: Three reviewers flagged mass-assignment on Payment.
+```
+
+## 4. Proposed artefact
+
+The full body of the draft rule / skill / command / guideline goes
+here. If it is more than ~80 lines, commit it as a separate file
+under `agents/drafts/<proposal_id>.md` and link from here.
+
+```markdown
+# <draft title>
+
+...complete draft body...
+```
+
+## 5. Quality gate expectations
+
+List the checks the draft MUST pass before the gate signs off. The
+gate auto-runs every item in this list.
+
+- [ ] Passes `scripts/skill_linter.py` with zero errors
+- [ ] Passes `scripts/check_portability.py` (no project-specific
+      identifiers)
+- [ ] References in the draft all resolve (`check_references.py`)
+- [ ] Size within budget for its type (per `size-enforcement` rule)
+- [ ] `preservation-guard` check: if `Replaces existing`, justify
+      the replacement below.
+
+## 6. Replacement justification (if applicable)
+
+Leave blank if `Replaces existing: no`. Otherwise:
+
+- **What the existing artefact does well:** …
+- **What it misses:** …
+- **Why extension inside the existing artefact was rejected:** …
+- **Migration note for consumer projects:** …
+
+## 7. Success signal
+
+How will we know this proposal pays off? One concrete metric, one
+time window, one decision rule.
+
+- **Metric:** <e.g., "reviewer comments about mass-assignment in the
+  Billing module per month">
+- **Baseline:** <current value from evidence>
+- **Target:** <e.g., "drop to < 1 per quarter">
+- **Evaluation date:** <ISO date, typically +90 days from upstream
+  merge>
+- **Retire rule:** <"if still > baseline after 2 windows, retire">
+
+## 8. Risks and alternatives rejected
+
+- **Risks:** …
+- **Alternatives rejected:**
+  - `<alt 1>` — <why not>
+  - `<alt 2>` — <why not>
+
+## 9. Gate verdict (filled by gate, not author)
+
+- **Verdict:** [ ] pass  [ ] request changes  [ ] block
+- **Gate run date:** …
+- **Notes:** …
+
+## 10. Upstream PR (filled on stage transition)
+
+- **PR URL:** …
+- **Merge date:** …
+- **Originating project:** <consumer repo slug; metadata only>
+- **Retired:** <YYYY-MM-DD when the shipped artefact was removed; blank while live>
+- **Superseded-by:** <proposal_id of the replacement, if any>
+
+---
+
+<!--
+Authoring checklist (delete before committing):
+  [ ] All ten sections filled (or explicitly N/A).
+  [ ] `proposal_id` is unique in this repo.
+  [ ] At least two independent `evidence` entries.
+  [ ] Draft body complete; no "TODO" / "TBD" markers.
+  [ ] `Success signal` has a real number and a real date.
+-->

package/.agent-src/templates/command.md

@@ -0,0 +1,84 @@
+# Command Template
+
+> Template for creating new commands in `.agent-src.uncompressed/commands/{command-name}.md`.
+
+## Instructions
+
+1. Create file: `.agent-src.uncompressed/commands/{command-name}.md`
+2. Copy the template below
+3. Replace all `{placeholders}` with actual content
+4. Remove all `<!-- comments -->` when done
+5. Run: `python3 scripts/skill_linter.py .agent-src.uncompressed/commands/{command-name}.md`
+6. Sync: `task sync` (regenerates `.agent-src/` and `.augment/`)
+7. Generate Claude symlink: `task generate-tools` (or manually create symlink)
+
+## Template
+
+````markdown
+---
+name: {command-name}
+description: {Short description of what the command does}
+disable-model-invocation: true
+skills: [{optional-skill-1}, {optional-skill-2}]
+---
+
+<!-- FRONTMATTER RULES (delete this comment when done):
+  - name: must match the filename (without .md)
+  - description: short, human-readable — what the command does
+  - disable-model-invocation: ALWAYS true for commands (prevents Claude from auto-invoking)
+  - skills: optional — list skills this command references or delegates to
+-->
+
+# /{command-name}
+
+{One-line summary of what this command does.}
+
+**Source of truth:** `.agent-src.uncompressed/` — never read or edit `.agent-src/` or `.augment/` directly.
+
+## Steps
+
+### 1. {First step}
+
+{What to do, what to check, what to run.}
+
+### 2. {Second step}
+
+{Next action.}
+
+### 3. {Third step}
+
+{Continue until workflow is complete.}
+
+### N. Present findings
+
+<!-- For audit/analysis commands: always present findings before applying changes.
+     For action commands: show summary of what was done. -->
+
+Ask the user:
+
+```
+> 1. {Option 1}
+> 2. {Option 2}
+> 3. Skip — report only
+```
+
+## Rules
+
+<!-- Command-specific constraints. Keep short. -->
+
+- {Rule 1}
+- {Rule 2}
+````
+
+## Checklist
+
+Before considering a command complete:
+
+- [ ] **Frontmatter**: has `name`, `description`, `disable-model-invocation: true`
+- [ ] **Steps**: numbered sub-headings (`### 1.`, `### 2.`, ...)
+- [ ] **Source of truth**: works on `.agent-src.uncompressed/`, not `.agent-src/` or `.augment/`
+- [ ] **No auto-apply**: presents findings, asks before destructive changes
+- [ ] **Linter passes**: `python3 scripts/skill_linter.py` reports 0 FAIL
+- [ ] **English only**: all content in English
+- [ ] **Synced**: `.agent-src/commands/` has the same file
+- [ ] **Claude symlink**: `.claude/skills/{name}/SKILL.md` → `../../../.agent-src/commands/{name}.md`

package/.agent-src/templates/contexts/auth-model.md

@@ -0,0 +1,59 @@
+# Auth Model
+
+<!--
+  Template shipped by event4u/agent-config.
+  Copy to `agents/contexts/auth-model.md` in the consumer project and
+  fill in. This file is consumed by the Waves 2-3 security skills (see
+  `road-to-defensive-agent.md`) — an agent asked to review auth logic
+  starts by reading this.
+
+  Delete this HTML comment after filling in.
+-->
+
+## Roles
+
+<!-- List every role the system recognizes. Include role slug, who holds it, and how they obtain it. -->
+
+| Role slug | Description | Granted by | Notes |
+|---|---|---|---|
+| `admin` | … | … | … |
+| `member` | … | … | … |
+
+## Permissions
+
+<!--
+  Describe the permission model: RBAC, ABAC, policy-based, mix. Name the primary
+  authorization checks (Gate, Policy, middleware, attribute) and where they live.
+-->
+
+- **Model:** <!-- RBAC | ABAC | Policy-based | Mix -->
+- **Primary checks:** <!-- e.g., `Gate::check`, `UserPolicy`, `@can` directive -->
+- **Source of truth:** <!-- file / table / config that defines the matrix -->
+
+## Override and impersonation
+
+<!--
+  If admins can act on behalf of other users (support, debugging, billing
+  adjustments), document the mechanism and its audit trail.
+-->
+
+- **Who can impersonate:** <!-- roles / feature flag / audit trail path -->
+- **How the audit trail is emitted:** <!-- log channel / event / table -->
+- **Fields or actions impersonation MUST NOT touch:** <!-- e.g., 2FA reset, password change -->
+
+## Known exceptions
+
+<!--
+  Intentional deviations from the default model: system-user endpoints,
+  CLI bypasses, public-read namespaces. Each exception MUST be listed —
+  reviewers assume anything missing is unauthorized.
+-->
+
+- …
+
+## See also
+
+- `agents/contexts/tenant-boundaries.md` — tenancy scope, multi-tenant
+  rules that sit on top of the role model
+- `.augment/guidelines/agent-infra/*` — reviewer skills that read this
+  file

package/.agent-src/templates/contexts/data-sensitivity.md

@@ -0,0 +1,60 @@
+# Data Sensitivity
+
+<!--
+  Template shipped by event4u/agent-config.
+  Copy to `agents/contexts/data-sensitivity.md` in the consumer project
+  and fill in. This is the canonical reference for what data leaves the
+  system (logs, error reports, analytics, third-party APIs) and what
+  MUST be masked.
+
+  Delete this HTML comment after filling in.
+-->
+
+## Classification levels
+
+<!-- Keep or adapt these; remove tiers that do not apply. -->
+
+| Level | Meaning | Examples | Handling |
+|---|---|---|---|
+| **public** | safe to log, render, expose | module names, status codes | no restriction |
+| **internal** | safe in server-side logs, not in responses | user IDs, tenant slugs | never render to unauthenticated clients |
+| **confidential** | masked in logs, error reports, analytics | emails, IP addresses, names | always mask in logs and Sentry |
+| **secret** | must never leave the process | passwords, tokens, API keys | encrypted at rest; never logged |
+
+## Field inventory
+
+<!--
+  List every persistent field that is NOT `public`. Missing fields are
+  treated as `public` by default — so an unlisted column is effectively
+  a leak-by-omission.
+-->
+
+| Table / model | Field | Level | Masking rule | Notes |
+|---|---|---|---|---|
+| `users` | `email` | confidential | redact middle portion → `a***@example.com` | … |
+| `users` | `password` | secret | never log, even redacted | hashed in DB |
+| … | … | … | … | … |
+
+## Log-safe types
+
+<!-- Document the helpers and conventions used to mask fields in log output. -->
+
+- **Logging helper / decorator:** <!-- e.g., `loggable()` trait, `SafeString` value object -->
+- **Sentry beforeSend hook:** <!-- where, and which fields it strips -->
+- **Structured log fields that MUST NOT contain confidential data:**
+  <!-- e.g., `request.body`, `exception.message` -->
+
+## Known leak points (regression watchlist)
+
+<!--
+  Places where confidential data has leaked before. A reviewer reads
+  this list before approving changes to: loggers, error handlers, admin
+  exports, third-party integrations, webhook payloads.
+-->
+
+- …
+
+## See also
+
+- `agents/contexts/auth-model.md` — who can see what
+- `agents/contexts/observability.md` — how logs are routed

package/.agent-src/templates/contexts/deployment-order.md

@@ -0,0 +1,72 @@
+# Deployment Order
+
+<!--
+  Template shipped by event4u/agent-config.
+  Copy to `agents/contexts/deployment-order.md` in the consumer project
+  and fill in. Required reading for any change involving schema
+  migrations, feature flags, or multi-service deploys. Without this,
+  "breaking change" reviews are guesswork.
+
+  Delete this HTML comment after filling in.
+-->
+
+## Environments
+
+<!-- Name every environment in promotion order. -->
+
+| Env | Purpose | Auto-deploy | Gate |
+|---|---|---|---|
+| `staging` | pre-prod verification | yes, on merge to `main` | smoke tests green |
+| `prod` | customer-facing | manual trigger | staging green + approval |
+| … | … | … | … |
+
+## Migration strategy
+
+<!-- Pick one and document deviations. -->
+
+- [ ] **Expand → migrate → contract** (default for schema changes).
+- [ ] **Backfill job** — migrations touch >1M rows.
+- [ ] **Zero-downtime required** — feature flagged through the window.
+
+### Concrete rules
+
+- Add columns **nullable** or with default in release N, make NOT NULL
+  or drop default in release N+1.
+- Rename columns by **adding the new name**, writing to both, reading
+  from the new one, dropping the old in a later release.
+- Lock-prone DDL (`ALTER TABLE … ADD COLUMN` on large tables,
+  `ADD INDEX` without `CONCURRENTLY`) requires a maintenance window or
+  an online-DDL tool.
+
+## Feature flags
+
+- **Flag system:** <!-- e.g., Pennant / LaunchDarkly / env config -->
+- **Flag naming:** <!-- e.g., `feature.<area>.<capability>` -->
+- **Default state for new flags:** <!-- off, enabled for internal tenants, etc. -->
+- **Retirement process:** <!-- how and when flags are removed after rollout -->
+
+## Rollback plan
+
+<!--
+  Every deploy MUST have a rollback answer. Describe the default,
+  then the exceptions.
+-->
+
+- **Default rollback:** <!-- e.g., redeploy previous tag, no data migration needed -->
+- **When rollback requires a reverse migration:** <!-- conditions + runbook -->
+- **When rollback is NOT possible:** <!-- destructive migrations; document how the team decides to ship anyway -->
+
+## Known ordering constraints
+
+<!--
+  Services that must deploy in a specific order (e.g., API before
+  worker, schema before app, flag before feature). A reviewer reads
+  this before approving any cross-service change.
+-->
+
+- …
+
+## See also
+
+- `agents/contexts/observability.md` — what to watch during a deploy
+- `.augment/skills/migration-safety/SKILL.md` <!-- if installed --> — reviewer

package/.agent-src/templates/contexts/observability.md

@@ -0,0 +1,64 @@
+# Observability
+
+<!--
+  Template shipped by event4u/agent-config.
+  Copy to `agents/contexts/observability.md` in the consumer project and
+  fill in. A reviewer reads this before approving changes to loggers,
+  error handlers, metrics, or alert rules.
+
+  Delete this HTML comment after filling in.
+-->
+
+## Error tracking
+
+- **System:** <!-- e.g., Sentry / Rollbar / Bugsnag / custom -->
+- **Project / DSN location:** <!-- env var or config path — NOT the value -->
+- **Environment tag convention:** <!-- `staging`, `prod`, `dev`; must be set -->
+- **Release tag source:** <!-- git SHA / version / deploy ID -->
+- **beforeSend / filter hook:** <!-- file path; what it strips — cross-reference `data-sensitivity.md` -->
+
+## Logging
+
+<!-- Document every channel and what it is for. -->
+
+| Channel | Destination | Retention | Used for |
+|---|---|---|---|
+| `stack` | stdout → collector | 30 days | default app logs |
+| `audit` | DB `audit_log` table | 2 years | user-facing compliance events |
+| `security` | separate index | 90 days | authn failures, permission denials |
+| … | … | … | … |
+
+### Structured log conventions
+
+- **Format:** <!-- JSON / logfmt / plain -->
+- **Required fields on every entry:** <!-- e.g., `request_id`, `user_id`, `tenant_id`, `channel` -->
+- **Log-safe types:** see `data-sensitivity.md`.
+
+## Metrics
+
+- **System:** <!-- e.g., Prometheus / CloudWatch / Grafana Cloud -->
+- **Naming convention:** <!-- `<service>_<verb>_<unit>` -->
+- **Cardinality limits:** <!-- which labels are capped, which are banned -->
+
+## Known alerts
+
+<!--
+  Every alert that will page a human. A reviewer checks this before
+  changing the upstream behaviour that triggers the alert.
+-->
+
+| Alert | Signal | Routed to | Runbook |
+|---|---|---|---|
+| High 5xx rate | `http_errors_rate_5m > 5` | on-call | `docs/runbooks/5xx.md` |
+| Queue backlog | `queue_depth{q=default} > 10k` | platform | `docs/runbooks/queue.md` |
+| … | … | … | … |
+
+## Dashboard references
+
+- <!-- link or path to the primary dashboard + the alerting dashboard -->
+
+## See also
+
+- `agents/contexts/data-sensitivity.md` — what must NOT appear in logs
+  or error reports
+- `agents/contexts/deployment-order.md` — what to watch during a deploy

package/.agent-src/templates/contexts/tenant-boundaries.md

@@ -0,0 +1,68 @@
+# Tenant Boundaries
+
+<!--
+  Template shipped by event4u/agent-config.
+  Copy to `agents/contexts/tenant-boundaries.md` in the consumer project
+  and fill in. Required reading for any review that touches data access,
+  queries, or public endpoints in a multi-tenant system.
+
+  Delete this HTML comment after filling in.
+-->
+
+## Tenancy type
+
+<!-- Pick one and delete the rest. -->
+
+- [ ] **Single-tenant** — one database per deployment. No cross-tenant
+      leakage is possible at the infra layer. Delete this file if true
+      and the app will never shard.
+- [ ] **Multi-tenant, shared database** — one table with a tenant key
+      column (e.g., `tenant_id`, `workspace_id`).
+- [ ] **Multi-tenant, schema per tenant** — one DB, one schema each.
+- [ ] **Multi-tenant, database per tenant** — each tenant has its own
+      connection.
+
+## Tenant identifier
+
+- **Column / connection key:** <!-- e.g., `tenant_id` on every tenanted table -->
+- **Request scope source:** <!-- JWT claim / subdomain / session / header -->
+- **Switched at:** <!-- middleware / service provider / connection factory -->
+
+## Scope propagation
+
+<!--
+  Name every layer that MUST filter by tenant. Omissions are the most
+  common bug class in multi-tenant systems.
+-->
+
+- **HTTP layer:** <!-- how controllers get the tenant -->
+- **Background jobs:** <!-- how tenant context is serialized -->
+- **Queued listeners and events:** <!-- same -->
+- **CLI commands:** <!-- explicit flag or env var -->
+- **Admin UI / support impersonation:** <!-- whether it switches tenant -->
+
+## Known exceptions
+
+<!--
+  Intentional cross-tenant read or write paths. Each one MUST be listed
+  — reviewers treat any missing entry as a bug.
+-->
+
+| Path | Why cross-tenant | Guard |
+|---|---|---|
+| e.g., `/admin/reports/usage` | aggregates across all tenants | superuser role + audit log |
+| … | … | … |
+
+## Gotchas
+
+<!--
+  Record every tenant-leak bug the team has ever shipped. A reviewer
+  reads this before approving any query touching tenanted data.
+-->
+
+- …
+
+## See also
+
+- `agents/contexts/auth-model.md` — roles that sit on top of tenants
+- `agents/contexts/data-sensitivity.md` — tenant-scoped vs. shared data

package/.agent-src/templates/contexts.md

@@ -0,0 +1,116 @@
+# Context Template
+
+Templates for context documents stored in `agents/contexts/` or `app/Modules/{Module}/agents/contexts/`.
+
+A **context document** captures the architectural understanding of a codebase area — its structure,
+key classes, patterns, dependencies, and conventions. It's a snapshot of knowledge that helps
+agents (and developers) quickly orient themselves when working in that area.
+
+---
+
+## Rules for Context Documents
+
+1. **Factual.** Based on codebase analysis, not assumptions.
+2. **Navigational.** Help others find their way — point to key files and patterns.
+3. **Maintainable.** Update when the codebase changes.
+4. **Language:** All context documents must be written in **English**.
+5. **One area per file.** Don't combine unrelated contexts.
+
+---
+
+## Context Types
+
+| Type | When to use | Example |
+|---|---|---|
+| **Module** | Document a module's structure and purpose | `client-software.md` |
+| **Domain** | Document a business domain across modules | `import-pipeline.md` |
+| **Service** | Document a complex service and its dependencies | `customer-service.md` |
+| **Integration** | Document an external API/system integration | `probaus-api.md` |
+| **Infrastructure** | Document infrastructure or DevOps concerns | `queue-system.md` |
+
+---
+
+## Template
+
+Copy the structure below into a new file:
+
+```markdown
+# Context: {title}
+
+> {One sentence: What area does this context cover?}
+
+**Type:** {Module | Domain | Service | Integration | Infrastructure}
+**Created:** {YYYY-MM-DD}
+**Last Updated:** {YYYY-MM-DD}
+**Module:** {module name or "project-wide"}
+**Related Features:** {links to feature plans or "none"}
+
+## Overview
+
+{2-3 sentences describing what this area does, why it exists, and who/what depends on it.}
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `{path/to/file.php}` | {what it does} |
+| `{path/to/file.php}` | {what it does} |
+
+## Architecture
+
+{How the pieces fit together. Data flow, request flow, or processing pipeline.
+Use bullet points or a simple ASCII diagram.}
+
+## Key Classes & Services
+
+### {ClassName}
+
+- **Location:** `{full/path.php}`
+- **Purpose:** {what it does}
+- **Key methods:** `{method1()}`, `{method2()}`
+- **Dependencies:** {what it depends on}
+
+## Database
+
+| Table | Purpose | Connection |
+|---|---|---|
+| `{table_name}` | {what it stores} | {api_database / customer_database} |
+
+## API Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/api/v1/{path}` | {what it does} |
+
+## Dependencies
+
+### Internal
+- {Other modules or services this depends on}
+
+### External
+- {External APIs, packages, or systems}
+
+## Patterns & Conventions
+
+- {Patterns specific to this area}
+- {Naming conventions, coding patterns}
+
+## Known Issues / Technical Debt
+
+- {Known problems or areas for improvement}
+
+## Notes
+
+{Optional: edge cases, gotchas, historical context.}
+```
+
+---
+
+## Tips
+
+- **Start with `/module-explore`** to gather data before creating a context.
+- **Link to specific files** — `app/Modules/Import/App/Services/ImportService.php` beats "the import service".
+- **Document the "why"** — why was it built this way? What tradeoffs were made?
+- **Include known issues** — future agents will thank you.
+- **Update `Last Updated`** whenever you modify the context.
+