@event4u/agent-config 1.9.1

package/.agent-src/commands/fix-references.md

@@ -0,0 +1,94 @@
+---
+name: fix-references
+description: Find and fix broken cross-references in .augment/ and agents/ files
+disable-model-invocation: true
+---
+
+# fix-references
+
+## Instructions
+
+### 1. Run the reference checker
+
+```bash
+python3 scripts/check_references.py --format json
+```
+
+### 2. Parse findings
+
+If output is `[]` or "No broken references found":
+
+```
+✅  No broken references found. All cross-references are valid.
+```
+
+Stop here.
+
+### 3. Display findings
+
+```
+═══════════════════════════════════════════════
+  🔗 BROKEN REFERENCE REPORT
+═══════════════════════════════════════════════
+
+  Found: {count} broken reference(s)
+```
+
+Group by file:
+
+```
+  {file}:
+    Line {line}: `{ref}` ({ref_type}) → suggested: `{suggestion}`
+    Line {line}: `{ref}` ({ref_type}) → no suggestion
+```
+
+### 4. Auto-fix with confirmation
+
+For each broken reference:
+
+1. **If suggestion exists** → open the file, find the line, replace the broken ref with the suggestion.
+2. **If no suggestion** → search the codebase for the closest match. If found, propose it. If not, flag for manual review.
+3. **If the reference is in a code block** → skip (code blocks are not cross-references).
+4. **If the reference is in an example/template** → skip (placeholders are intentional).
+
+Present a summary before applying:
+
+```
+  Proposed fixes:
+  1. {file}:{line} — `{old}` → `{new}`
+  2. {file}:{line} — `{old}` → `{new}`
+  3. {file}:{line} — MANUAL: no match found
+
+> 1. Apply all automatic fixes
+> 2. Apply interactively (ask for each)
+> 3. Skip — just show the report
+```
+
+### 5. Apply fixes
+
+Edit files in `.agent-src.uncompressed/` (source of truth). Regenerate `.agent-src/` and `.augment/` via `task sync`.
+
+After all fixes:
+
+```bash
+python3 scripts/check_references.py
+```
+
+Show final result.
+
+### 6. Mark hashes
+
+For each modified file:
+
+```bash
+python3 scripts/compress.py --mark-done "{relative_path}"
+```
+
+## Rules
+
+- **Always fix in `.agent-src.uncompressed/`** — never edit `.agent-src/` or `.augment/` directly.
+- **Run `task sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
+- **Do NOT commit or push** — the user decides.
+- **Do NOT fix references in code blocks** — they are examples, not live refs.
+- **Do NOT auto-fix without showing the summary first.**
+- **Run the checker again after fixing** to verify 0 remaining issues.

package/.agent-src/commands/fix-seeder.md

@@ -0,0 +1,146 @@
+---
+name: fix-seeder
+skills: [eloquent]
+description: Scan seeder data files for broken foreign key references — find constants used without getReference() and fix them
+disable-model-invocation: true
+---
+
+# fix-seeder
+
+Scans all `PhpDataSeeder` data files for foreign key references that use raw seeder constants
+instead of `getReference()`. Raw constants don't trigger lazy initialization of the referenced
+seeder, causing "items not available" errors when seeders run in unpredictable order.
+
+## The Rule
+
+In a seeder data file loaded by `FooSeeder`:
+
+- **Own seeder constants** are OK: `FooSeeder::REFERENCE_KEY_X` (these are primary keys, not foreign keys)
+- **Other seeder constants** are WRONG: `BarSeeder::REFERENCE_KEY_Y` (foreign key — must use `getReference()`)
+
+### ✅ Correct — triggers lazy initialization
+
+```php
+'cat_id' => MaterialDeliveryBillCategorySeeder::getReference(
+    MaterialDeliveryBillCategorySeeder::REFERENCE_CATEGORY_A
+)->getId(),
+```
+
+### ❌ Wrong — raw constant, no lazy initialization
+
+```php
+'cat_id' => MaterialDeliveryBillCategorySeeder::REFERENCE_CATEGORY_A,
+```
+
+## Step 1: Run the scanner script
+
+Run the automated scanner inside the Docker container:
+
+```bash
+docker compose exec -T <php-service> php .augment/scripts/scan-seeder-violations.php
+```
+
+The script (``.augment/scripts/scan-seeder-violations.php``) automatically:
+1. Finds all `PhpDataSeeder` / `JsonDataSeeder` classes and their `$dataFile` paths
+2. Scans each data file for foreign seeder constants used without `getReference()`
+3. Distinguishes PHP files (auto-fixable) from JSON files (manual fix needed)
+
+### What the scanner flags
+
+**Violation** = a `Seeder::CONSTANT` used directly (not via `getReference()`)
+where the seeder class is NOT the owner of the data file.
+
+**Not flagged:**
+- `OtherSeeder::getReference(...)` — correct
+- `OtherSeeder::getReferences()` — correct
+- `OwnSeeder::CONSTANT` — own primary key, correct
+- Known exceptions (circular dependencies) — configured in the scanner script
+
+### Known Exceptions
+
+Currently there are **no exceptions**. All circular dependencies have been resolved.
+
+**Pattern for resolving circular dependencies:** Use two-phase seeding. The data file seeds
+records with placeholder values (e.g., empty arrays). The Seeder's `run()` method then updates
+records with the real values using `getReference()`. Since `run()` is called after all seeders
+are initialized, the circular dependency is broken.
+
+Example: `UserWageTypeRuleSeeder` seeds `lohnart_lv` as empty arrays in the data file,
+then populates them with project numbers via `ProjectSeeder::getReference()` in `run()`.
+
+If a new exception is truly needed, add it to `.augment/scripts/scan-seeder-violations.php`
+in the `$exceptions` array. Format: `'OwnerSeeder' => ['AllowedForeignSeeder']`.
+
+## Step 2: Report findings
+
+Present a table of all violations:
+
+```
+| # | Data File | Line | Violation | Owning Seeder |
+|---|-----------|------|-----------|---------------|
+| 1 | material-delivery-bill-catalog-data.php:11 | CategorySeeder::REFERENCE_A | CatalogSeeder |
+```
+
+Then ask the user:
+
+> 1. Fix all violations automatically
+> 2. Fix interactively (ask for each)
+> 3. Report only — don't fix
+
+## Step 3: Fix violations
+
+For each violation, replace the raw constant with a `getReference()` call:
+
+**Before:**
+```php
+'foreign_key_column' => OtherSeeder::REFERENCE_CONSTANT,
+```
+
+**After:**
+```php
+'foreign_key_column' => OtherSeeder::getReference(
+    OtherSeeder::REFERENCE_CONSTANT
+)->getId(),
+```
+
+### Choosing the getter method
+
+- Default: `->getId()` (most foreign keys are IDs)
+- If the column name suggests a different attribute, use the appropriate getter
+  (e.g., `'name' => ...` might need `->getName()`)
+- If unsure, check the referenced model's primary key or the column definition
+
+### Extract to variable when referenced multiple times
+
+If the same `getReference()` call would appear multiple times in one data file,
+extract it to a variable at the top of the file:
+
+```php
+$category = MaterialDeliveryBillCategorySeeder::getReference(
+    MaterialDeliveryBillCategorySeeder::REFERENCE_CATEGORY_A
+);
+
+return [
+    [
+        'cat_id' => $category->getId(),
+        'cat_name' => $category->getName(),
+    ],
+];
+```
+
+## Step 4: Verify
+
+After fixing, run the seeder to verify:
+
+```bash
+docker compose exec -T <php-service> php artisan db:seed --env=testing
+```
+
+If it fails, investigate and fix the remaining issues.
+
+## Rules
+
+- **Do NOT commit or push.** Only apply local changes.
+- **Do NOT change the seeder classes** — only the data files.
+- **Do NOT change the DataSeeder framework** — only fix data file references.
+- When in doubt about the getter method, check the model class.

package/.agent-src/commands/implement-ticket.md

@@ -0,0 +1,133 @@
+---
+name: implement-ticket
+skills: [refine-ticket, feature-planning]
+description: Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over the `implement_ticket` Python engine, block-on-ambiguity, no auto-git.
+disable-model-invocation: true
+---
+
+# implement-ticket
+
+## Instructions
+
+### 1. Resolve input
+
+Accept one of four input paths:
+
+1. **Explicit key** — `/implement-ticket PROJ-123`
+2. **Branch detection** — no arg → `git branch --show-current` + regex
+   `[A-Z]+-[0-9]+`
+3. **Pasted text** — markdown block under the command
+4. **URL** — `/implement-ticket https://…/browse/PROJ-123`
+
+For paths 1, 2, 4: run steps 1-3 of the [`jira-ticket`](jira-ticket.md) command
+(extract ID, fetch ticket, scan for Sentry links). For path 3: parse the pasted
+markdown. If no input resolves:
+
+```
+🎫 Which ticket should I implement? Paste a key, URL, or the ticket text.
+```
+
+### 2. Prepare the state file
+
+The engine persists everything in a JSON state file (default:
+`.implement-ticket-state.json` in the repo root). Two cases:
+
+- **Fresh run** — state file does not exist. Write the resolved ticket to
+  `ticket.json` (id, title, body, acceptance_criteria) and pass it via
+  `--ticket-file ticket.json`. Honour `roles.active_role` from
+  `.agent-settings.yml` via `--persona`.
+- **Resume** — state file exists. Do **not** pass `--ticket-file` or
+  `--persona`; mid-flight persona switches are refused by the engine.
+
+### 3. Drive the Option-A dispatch loop
+
+Run the engine with the state file on every iteration:
+
+```bash
+PYTHONPATH=scripts python3 -m implement_ticket \
+    --state-file .implement-ticket-state.json \
+    [--ticket-file ticket.json --persona <name>]   # first call only
+```
+
+Then branch on the exit code:
+
+| Exit | Meaning | Action |
+|---|---|---|
+| `0` | SUCCESS — final report on stdout | Go to step 5 |
+| `1` | BLOCKED — halt surface on stdout, state persisted | Inspect `questions[0]` |
+| `2` | Config/IO error | Surface the stderr message to the user, stop |
+
+On exit `1`, look at the first line after `[halt] outcome=… step=…`:
+
+- **Starts with `@agent-directive:`** — agent work required, see §4.
+- **Starts with `>`** — user question per
+  [`user-interaction`](../rules/user-interaction.md). Emit the numbered
+  options verbatim, wait for the user, write their answer back onto the
+  matching state slice, then re-run the engine. Never guess.
+
+### 4. Directive mapping
+
+When `questions[0]` is `@agent-directive: <verb> [key=value …]`, dispatch:
+
+| Directive | What to do | State write-back |
+|---|---|---|
+| `create-plan` | Invoke [`/feature-plan`](feature-plan.md) with the refined ticket + memory hits | `state.plan` = result; `state.outcomes.plan = "success"` |
+| `apply-plan` | Apply changes per `state.plan` under [`minimal-safe-diff`](../rules/minimal-safe-diff.md) + [`scope-control`](../rules/scope-control.md); one file at a time, read before edit | `state.changes` = `[{path, purpose}]`; `state.outcomes.implement = "success"` |
+| `run-tests scope=targeted` | Invoke [`/tests-execute`](tests-execute.md) on the files in `state.changes` | `state.tests` = `{verdict, durations, details}`; `state.outcomes.test = "success"` only when `verdict == "success"` |
+| `run-tests scope=full` | Same but whole suite (persona `qa` widens to this) | Same as above |
+| `review-changes` | Invoke [`/review-changes`](review-changes.md) | `state.verify` = `{verdict, confidence, notes}`; `state.outcomes.verify = "success"` only when `verdict == "success"` |
+
+After the write-back, **re-run the engine**. The dispatcher skips
+already-successful steps and resumes at the next pending one. On a
+non-success verdict, do **not** flip `outcomes` — the engine will reissue
+the same directive so the agent can fix and retry.
+
+Never invent directive verbs. Never skip a directive because "the state
+already looks right". The state is authoritative only when the engine
+wrote it.
+
+### 5. Final report + close-prompt
+
+On exit `0`, the engine prints the delivery report (nine fixed sections
+per [`implement-ticket-flow`](../../agents/contexts/implement-ticket-flow.md#delivery-report-schema)).
+Surface it unchanged. Append the close-prompt:
+
+```
+> 1. /commit — stage + commit per the delivery report
+> 2. /create-pr — open a pull request from this branch
+> 3. Keep working — I'll hold the state file for the next /implement-ticket
+> 4. Discard — delete .implement-ticket-state.json
+```
+
+**Never run `/commit` or `/create-pr` without the user choosing them.**
+Per [`scope-control`](../rules/scope-control.md), git operations are
+permission-gated.
+
+### Rules
+
+- Honour [`scope-control`](../rules/scope-control.md),
+  [`minimal-safe-diff`](../rules/minimal-safe-diff.md), and
+  [`verify-before-complete`](../rules/verify-before-complete.md) inside
+  every directive.
+- Never bypass the engine. Don't skip steps, don't rewrite outcomes,
+  don't flip `verdict` from `failed` to `success`.
+- Persona is session-global. Read it from `.agent-settings.yml` on the
+  fresh run; never accept a `--persona` flag from the user mid-flight.
+- Memory section in the report is absent when no hit changed an outcome.
+  That is by design — don't pad it.
+
+## Examples
+
+```
+/implement-ticket PROJ-123
+/implement-ticket                               # uses current branch
+/implement-ticket https://acme.atlassian.net/browse/PROJ-123
+```
+
+## See also
+
+- [`implement-ticket-flow`](../../agents/contexts/implement-ticket-flow.md) — flow contract + directive semantics
+- [`adr-implement-ticket-runtime`](../../agents/contexts/adr-implement-ticket-runtime.md) — runtime choice
+- [`refine-ticket`](refine-ticket.md), [`feature-plan`](feature-plan.md), [`tests-execute`](tests-execute.md), [`review-changes`](review-changes.md) — skills the directives delegate to
+- [`commit`](commit.md), [`create-pr`](create-pr.md) — post-delivery commands the user runs explicitly
+- [`road-to-implement-ticket`](../../agents/roadmaps/road-to-implement-ticket.md) — governing roadmap

package/.agent-src/commands/jira-ticket.md

@@ -0,0 +1,71 @@
+---
+name: jira-ticket
+skills: [laravel]
+description: Read Jira ticket from branch name, analyze linked Sentry issues, implement feature or fix bug
+disable-model-invocation: true
+---
+
+# jira-ticket
+
+## Instructions
+
+### 1. Extract ticket ID from branch name
+
+- Run `git branch --show-current` to get the current branch name.
+- Extract the Jira ticket ID from the branch name (e.g. `fix/DEV-4673-some-description` → `DEV-4673`).
+- If no ticket ID is found in the branch name, or the ticket cannot be found in Jira, **ask the user** for the ticket number or a direct Jira link. Do not guess or proceed without a valid ticket.
+
+### 2. Fetch the Jira ticket
+
+- Use the Jira API to fetch the ticket: `GET /issue/{ticketId}`
+- Read and understand:
+  - **Summary** and **description** — what needs to be done?
+  - **Issue type** — Bug, Feature, Task, etc.
+  - **Priority** and **status**
+  - **Comments** — often contain additional context, decisions, or reproduction steps.
+  - **Linked issues** — may reference related work.
+
+### 3. Check for Sentry links
+
+- Scan the ticket description and comments for Sentry URLs (e.g. `https://*.sentry.io/issues/*`).
+- If Sentry links are found:
+  - Fetch the Sentry issue details using `get_issue_details` with the URL.
+  - Analyze the stacktrace, error message, and affected code.
+  - Check tag distributions (browser, environment, URL) if relevant.
+  - This gives you the real-world error context to understand the bug.
+
+### 4. Analyze the codebase
+
+- Use `codebase-retrieval` to find the relevant code based on what the ticket describes.
+- Read the affected files and understand the current behavior.
+- If it's a bug: reproduce the logic mentally by following the code path from the Sentry stacktrace or ticket description.
+- If it's a feature: understand the existing architecture and where the new code should go.
+
+### 5. Plan the implementation
+
+- Create a task list with the planned changes.
+- For bugs: identify the root cause and plan the fix.
+- For features: break down into subtasks.
+- Present the plan to the user and **ask for confirmation before making changes**.
+
+### 6. Implement
+
+- Apply the changes following all project coding standards (see AGENTS.md).
+- Use `Math` helper for calculations, proper type hints, `declare(strict_types=1)` in new files, etc.
+- Write the code as if a senior developer would review it.
+
+### 7. Verify
+
+- Run `php -l` on all modified files.
+- If the change is testable, suggest writing or running tests.
+
+### Rules
+
+- **Do NOT commit or push.** Only apply local changes.
+- **Always ask before implementing** — present the plan first.
+- If the ticket is unclear or missing information, ask the user for clarification.
+- If the Sentry issue reveals a different/bigger problem than the ticket describes, flag it.
+
+## See also
+
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)

package/.agent-src/commands/judge.md

@@ -0,0 +1,86 @@
+---
+name: judge
+skills: [subagent-orchestration]
+description: Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only
+disable-model-invocation: true
+---
+
+# judge
+
+## Instructions
+
+### 1. Identify the target
+
+The user invoked `/judge` on one of:
+
+- The current working-tree diff (`git diff`)
+- A specific commit range (`git diff A..B`)
+- A PR by number or URL
+- A single file or set of files
+
+Confirm the target in one sentence before proceeding. Do not silently
+assume the working tree.
+
+### 2. Gather the context
+
+Collect what the judge needs:
+
+- The diff in full
+- The original task, ticket, or PR description
+- Relevant acceptance criteria (tests, linter config, design doc)
+
+If any of these is missing and the judgment would be shallow without
+it, **stop** and ask.
+
+### 3. Resolve the judge model
+
+Read `.agent-settings.yml`:
+
+- `subagents.judge_model` → empty = one tier above session model
+
+Unknown alias → stop. Silence is not a fallback.
+
+### 4. Invoke the judge
+
+The judge reviews the diff against the task. Return one of:
+
+| Verdict  | Meaning                                      |
+|----------|----------------------------------------------|
+| `apply`  | Correct, complete, ready to land             |
+| `revise` | Specific issues listed — user decides next   |
+| `reject` | Fundamentally wrong approach                 |
+
+Unlike `/do-and-judge`, this command does **not** loop — no revision
+cycles. The verdict is the deliverable.
+
+### 5. Report
+
+```
+Mode:    judge (standalone)
+Target:  <diff | commit range | PR #N | files>
+Judge:   <resolved model>
+Verdict: apply | revise | reject
+Issues:  <numbered list if revise/reject>
+Next step: <what the user should do based on the verdict>
+```
+
+## Use this command when
+
+- A diff already exists and the user wants a second opinion
+- Reviewing someone else's PR before approving it
+- Double-checking a change before opening a PR
+- Stress-testing a refactor without committing to revisions
+
+## Do NOT
+
+- NEVER apply the diff — this command judges only
+- NEVER loop into a revision cycle — use `/do-and-judge` for that
+- NEVER run the judge on an empty diff — fail fast
+- NEVER silently fall back to the session model for the judge
+
+## See also
+
+- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
+- [`/do-and-judge`](do-and-judge.md) — if a revision loop is wanted
+- [`/review-changes`](review-changes.md) — human-oriented self-review
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)

package/.agent-src/commands/memory-add.md

@@ -0,0 +1,130 @@
+---
+name: memory-add
+description: Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decisions, incident-learnings, product-rules)
+skills: [file-editor]
+disable-model-invocation: true
+---
+
+# /memory-add
+
+Creates or updates a single entry in one of the four engineering-memory
+YAML files under `agents/memory/` in the consumer project. The entry
+is validated against the schema in
+[`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
+before the file is written.
+
+Absence of these files is legal — this command is the entry point for
+the first write and for every subsequent addition.
+
+## Prerequisites
+
+- Consumer project has an `agents/` directory (package installed).
+- `scripts/check_memory.py` is available (shipped with the package).
+- User can name a concrete pattern — see the "when to reject" section.
+
+## Steps
+
+### 1. Pick the memory type
+
+```
+> Which memory type is this entry for?
+>
+> 1. domain-invariants  — architectural boundaries, module rules
+> 2. architecture-decisions — ADR-style decisions with alternatives
+> 3. incident-learnings — post-mortem patterns with guardrails
+> 4. product-rules — intentional business constraints
+```
+
+If the user cannot pick one confidently, stop and ask what the entry
+**describes**. Never guess the type — a misfiled entry is worse than
+no entry.
+
+### 2. Check it does not already exist
+
+Read the target file (single-file layout: `agents/memory/<type>.yml`;
+sharded layout: `agents/memory/<type>/*.yml`). For each existing
+`id:`, compare against the proposed pattern:
+
+- Same `scope:` path + same rule text → **update** existing entry
+  (bump `last_validated`, append evidence to `source:`).
+- Overlapping `scope:` but different rule → surface the conflict and
+  ask which entry supersedes which.
+- No overlap → proceed as new entry.
+
+### 3. Collect the required fields
+
+All four types share the frontmatter in
+[`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md#shared-frontmatter-fields).
+Collect in this order, one numbered question at a time:
+
+1. `id` — kebab-case slug, unique within the type.
+2. `status` — `active` · `deprecated` · `archived` (default: `active`).
+3. `confidence` — `low` · `medium` · `high`.
+4. `source` — at least one URL, PR, incident, or ADR reference.
+5. `owner` — team slug.
+6. `last_validated` — today's ISO date (default).
+7. `review_after_days` — integer; suggest 90 for ADRs, 180 for
+   invariants, 365 for product rules.
+
+Then the type-specific fields (see the example templates under
+`.augment/templates/agents/memory/`).
+
+### 4. Show the draft
+
+Render the proposed YAML block to the user and ask for confirmation:
+
+```
+> About to add to agents/memory/<type>.yml:
+>
+> <yaml block>
+>
+> 1. Write it — run the gate
+> 2. Edit a field — ask which one
+> 3. Cancel — discard draft
+```
+
+### 5. Write and gate
+
+On confirmation:
+
+- Append the entry to the chosen layout (single-file: append under
+  `entries:`; sharded: write `agents/memory/<type>/<hash>.yml`).
+- Run `python3 scripts/check_memory.py --path agents/memory`.
+- On non-zero exit: show the error, **revert** the write, return to
+  step 3 or 4 depending on the failure.
+- On zero exit: report the entry `id` and path, remind the user to
+  commit.
+
+### 6. Cross-link
+
+If the entry has a `references:` block pointing to a skill, rule, or
+ADR file, run `python3 scripts/check_references.py` to verify the
+link resolves. Broken link → block and ask the user to fix.
+
+## When to reject
+
+- Vague frustration ("we should be more careful about X") — not a
+  pattern. Ask for a concrete rule or ADR instead.
+- One-off anecdote with no `trigger_conditions:` or `scope:` — not
+  generalizable.
+- Duplicate of an existing entry (step 2) — update instead.
+- Missing `source:` — an entry without evidence cannot be reviewed.
+
+## Output format
+
+```
+✅  Added <type>/<id> (confidence: <high|medium|low>)
+   Path: agents/memory/<type>.yml (or agents/memory/<type>/<hash>.yml)
+   Gate: scripts/check_memory.py → PASS
+   Next: commit and link from the relevant skill/command.
+```
+
+## See also
+
+- [`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
+  — full schema
+- [`capture-learnings`](../rules/capture-learnings.md) — when a
+  learning is better captured as an `incident-learnings` entry vs a
+  rule/skill proposal
+- [`road-to-engineering-memory.md`](../../agents/roadmaps/road-to-engineering-memory.md)
+  — Phase 3 writer ergonomics