@event4u/agent-config 1.9.1

package/.agent-src/scripts/scan-seeder-violations.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * 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.
+ *
+ * Usage (inside Docker container):
+ *   php .augment/scripts/scan-seeder-violations.php
+ *
+ * Used by: /fix-seeder command
+ */
+
+$seedersDir = __DIR__ . '/../../database/seeders';
+$dataDir = __DIR__ . '/../../database/seeder-data/data';
+
+if (!is_dir($seedersDir) || !is_dir($dataDir)) {
+    echo "Error: seeders or data directory not found. Run from project root.\n";
+    exit(1);
+}
+
+// Step 1: Build map of seeder short class name -> data file relative path
+$seederMap = [];
+$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($seedersDir));
+
+foreach ($iterator as $file) {
+    if ($file->getExtension() !== 'php') {
+        continue;
+    }
+
+    $content = file_get_contents($file->getRealPath());
+
+    if (preg_match('/class\s+(\w+)\s+extends\s+(?:Php|Json)DataSeeder/', $content, $classMatch)
+        && preg_match('/\$dataFile\s*=\s*[\'"]([^\'"]+)[\'"]/', $content, $dataMatch)) {
+        $seederMap[$classMatch[1]] = $dataMatch[1];
+    }
+}
+
+// Known exceptions: circular dependencies where getReference() would cause infinite loops.
+// Format: 'OwnerSeeder' => ['ReferencedSeeder', ...]
+// Currently empty — all circular dependencies have been resolved via two-phase seeding
+// (e.g., UserWageTypeRuleSeeder uses run() to apply project mappings after initReferences).
+$exceptions = [];
+
+// Step 2: For each data file, find violations
+$violations = [];
+
+foreach ($seederMap as $ownerSeeder => $dataFile) {
+    $filePath = $dataDir . '/' . str_replace('\\', '/', $dataFile);
+
+    if (!file_exists($filePath)) {
+        continue;
+    }
+
+    $lines = file($filePath);
+
+    if (!$lines) {
+        continue;
+    }
+
+    $fileExtension = pathinfo($filePath, PATHINFO_EXTENSION);
+
+    foreach ($lines as $lineNum => $line) {
+        if (!preg_match_all('/(\w+Seeder)::([A-Z][A-Z0-9_]+)/', $line, $matches, PREG_SET_ORDER)) {
+            continue;
+        }
+
+        foreach ($matches as $match) {
+            $referencedSeeder = $match[1];
+            $constant = $match[2];
+
+            // Skip own seeder constants (primary keys are OK)
+            if ($referencedSeeder === $ownerSeeder) {
+                continue;
+            }
+
+            // Skip known exceptions (circular dependencies)
+            if (isset($exceptions[$ownerSeeder]) && in_array($referencedSeeder, $exceptions[$ownerSeeder], true)) {
+                continue;
+            }
+
+            // Skip if the line already contains getReference/getReferences for this seeder
+            if (preg_match('/' . preg_quote($referencedSeeder, '/') . '::getReference/', $line)) {
+                continue;
+            }
+
+            // Check multiline: previous line may have getReference(
+            if ($lineNum > 0) {
+                $prevLine = $lines[$lineNum - 1];
+                if (preg_match('/' . preg_quote($referencedSeeder, '/') . '::getReference\s*\(\s*$/', trim($prevLine))) {
+                    continue;
+                }
+            }
+
+            $violations[] = [
+                'file' => str_replace($dataDir . '/', '', $filePath),
+                'line' => $lineNum + 1,
+                'owner' => $ownerSeeder,
+                'referenced' => $referencedSeeder,
+                'constant' => $constant,
+                'full' => $referencedSeeder . '::' . $constant,
+                'lineContent' => trim($line),
+                'extension' => $fileExtension,
+            ];
+        }
+    }
+}
+
+// Step 3: Output results
+if (empty($violations)) {
+    echo "✅  No violations found.\n";
+    exit(0);
+}
+
+$phpCount = count(array_filter($violations, static fn(array $v): bool => $v['extension'] === 'php'));
+$jsonCount = count(array_filter($violations, static fn(array $v): bool => $v['extension'] === 'json'));
+
+echo "Found " . count($violations) . " violation(s)";
+
+if ($jsonCount > 0) {
+    echo " ($phpCount in PHP files, $jsonCount in JSON files — JSON cannot be auto-fixed)";
+}
+
+echo ":\n\n";
+
+printf("%-4s %-65s %-6s %-55s %s\n", '#', 'Data File', 'Line', 'Violation', 'Owner');
+echo str_repeat('-', 185) . "\n";
+
+foreach ($violations as $i => $v) {
+    $prefix = $v['extension'] === 'json' ? '[JSON] ' : '';
+    printf(
+        "%-4d %-65s %-6d %-55s %s\n",
+        $i + 1,
+        $prefix . $v['file'],
+        $v['line'],
+        $v['full'],
+        $v['owner']
+    );
+}
+
+echo "\nPHP violations (auto-fixable): $phpCount\n";
+echo "JSON violations (manual fix needed): $jsonCount\n";
+

package/.agent-src/scripts/update_roadmap_progress.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Generate `agents/roadmaps-progress.md` — aggregated progress across open roadmaps.
+
+Scans every roadmap under `agents/roadmaps/` (excluding `archive/`, `skipped/`,
+`template.md`, `README.md`, `open-questions*.md`), counts checkbox states per
+phase, and writes a dashboard at `agents/roadmaps-progress.md` (outside the
+`roadmaps/` folder to keep it clean) with:
+
+  - Overall progress (open-roadmap count, steps done, %)
+  - A summary table of every open roadmap
+  - Per-roadmap phase breakdown
+
+Checkbox states:
+  [x]  done      [ ]  open      [~]  deferred      [-]  cancelled
+
+Percentage = done / (done + open). Deferred and cancelled do not count towards
+"open" (they are explicit decisions).
+
+Invocation (from project root):
+  python3 .augment/scripts/update_roadmap_progress.py              # rewrite
+  python3 .augment/scripts/update_roadmap_progress.py --check      # CI: exit 1 if stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
+# H2 or H3 heading starting with "Phase <number>"; separator (colon, em-dash,
+# hyphen, or whitespace) and name are optional.
+PHASE_RE = re.compile(r"^(#{2,3})\s+Phase\s+(\d+)(?:[\s:\u2014\-]+(.*?))?\s*$", re.MULTILINE)
+TITLE_RE = re.compile(r"^#\s+(?:Roadmap:\s*)?(.+?)\s*$", re.MULTILINE)
+EXCLUDE_NAMES = {"template.md", "README.md", "progress.md", "roadmaps-progress.md"}
+EXCLUDE_PREFIXES = ("open-questions",)
+EXCLUDE_DIRS = {"archive", "skipped"}
+
+
+@dataclass
+class PhaseStats:
+    number: int
+    name: str
+    done: int = 0
+    open_: int = 0
+    deferred: int = 0
+    cancelled: int = 0
+
+    @property
+    def total_active(self) -> int:  # denominator for %
+        return self.done + self.open_
+
+    @property
+    def percent(self) -> int:
+        return round(self.done * 100 / self.total_active) if self.total_active else 0
+
+    @property
+    def state(self) -> str:
+        if self.total_active == 0 and (self.deferred or self.cancelled):
+            return "⏭️ skipped"
+        if self.total_active == 0:
+            return "⬜ empty"
+        if self.done == 0:
+            return "⬜ not started"
+        if self.open_ == 0:
+            return "✅ done"
+        return "🟡 in progress"
+
+
+@dataclass
+class RoadmapStats:
+    path: Path
+    rel: str
+    title: str
+    phases: list[PhaseStats] = field(default_factory=list)
+
+    @property
+    def done(self) -> int:
+        return sum(p.done for p in self.phases)
+
+    @property
+    def open_(self) -> int:
+        return sum(p.open_ for p in self.phases)
+
+    @property
+    def deferred(self) -> int:
+        return sum(p.deferred for p in self.phases)
+
+    @property
+    def cancelled(self) -> int:
+        return sum(p.cancelled for p in self.phases)
+
+    @property
+    def total_active(self) -> int:
+        return self.done + self.open_
+
+    @property
+    def percent(self) -> int:
+        return round(self.done * 100 / self.total_active) if self.total_active else 0
+
+
+def is_roadmap_candidate(path: Path) -> bool:
+    if path.name in EXCLUDE_NAMES:
+        return False
+    if any(path.name.startswith(p) for p in EXCLUDE_PREFIXES):
+        return False
+    if any(part in EXCLUDE_DIRS for part in path.parts):
+        return False
+    return True
+
+
+def count_checkboxes(text: str) -> tuple[int, int, int, int]:
+    done = open_ = deferred = cancelled = 0
+    for m in CHECKBOX_RE.finditer(text):
+        c = m.group(1).lower()
+        if c == "x":
+            done += 1
+        elif c == " ":
+            open_ += 1
+        elif c == "~":
+            deferred += 1
+        elif c == "-":
+            cancelled += 1
+    return done, open_, deferred, cancelled
+
+
+def parse_roadmap(path: Path, roadmap_root: Path) -> RoadmapStats | None:
+    text = path.read_text(encoding="utf-8")
+    phase_matches = list(PHASE_RE.finditer(text))
+    if not phase_matches:
+        return None  # not a roadmap — no ## Phase headings
+    title_match = TITLE_RE.search(text)
+    title = title_match.group(1).strip() if title_match else path.stem
+    rel = str(path.relative_to(roadmap_root))
+    stats = RoadmapStats(path=path, rel=rel, title=title)
+    for i, pm in enumerate(phase_matches):
+        start = pm.end()
+        end = phase_matches[i + 1].start() if i + 1 < len(phase_matches) else len(text)
+        d, o, df, c = count_checkboxes(text[start:end])
+        number = int(pm.group(2))
+        name = (pm.group(3) or "").strip() or f"Phase {number}"
+        stats.phases.append(PhaseStats(number, name, d, o, df, c))
+    return stats
+
+
+def bar(pct: int, width: int = 10) -> str:
+    filled = round(pct * width / 100)
+    return "█" * filled + "░" * (width - filled)
+
+
+def collect(roadmap_root: Path) -> list[RoadmapStats]:
+    results: list[RoadmapStats] = []
+    for path in sorted(roadmap_root.rglob("*.md")):
+        if not path.is_file() or not is_roadmap_candidate(path):
+            continue
+        stats = parse_roadmap(path, roadmap_root)
+        if stats:
+            results.append(stats)
+    return results
+
+
+def render(roadmaps: list[RoadmapStats]) -> str:
+    total_done = sum(r.done for r in roadmaps)
+    total_active = sum(r.total_active for r in roadmaps)
+    overall_pct = round(total_done * 100 / total_active) if total_active else 0
+    lines: list[str] = []
+    lines.append("# Roadmap Progress\n")
+    lines.append(
+        "> Auto-generated by `.augment/scripts/update_roadmap_progress.py`. "
+        "Do not edit — regenerated on every roadmap-create, -execute, or "
+        "completion change (last-modified timestamp lives in git history).\n>\n"
+        f"> {len(roadmaps)} open roadmap"
+        f"{'s' if len(roadmaps) != 1 else ''} · "
+        "[roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · "
+        "[skipped/](roadmaps/skipped/)\n"
+    )
+    lines.append("## Overall\n")
+    lines.append(f"**{total_done} / {total_active} steps done · {overall_pct}%**\n")
+    lines.append("```text\n" + bar(overall_pct, 40) + f"   {overall_pct}%\n```\n")
+    if not roadmaps:
+        lines.append("_No open roadmaps._\n")
+        return "\n".join(lines) + "\n"
+    lines.append("## Open roadmaps\n")
+    lines.append("| # | Roadmap | Phases | Steps | Done | Open | Deferred | Cancelled | Progress |")
+    lines.append("|---|---|---:|---:|---:|---:|---:|---:|---|")
+    for i, r in enumerate(roadmaps, 1):
+        lines.append(
+            f"| {i} | [{r.rel}](roadmaps/{r.rel}) | {len(r.phases)} | {r.total_active} | "
+            f"{r.done} | {r.open_} | {r.deferred} | {r.cancelled} | "
+            f"{bar(r.percent)} {r.percent}% |"
+        )
+    lines.append("")
+    lines.append("---\n")
+    lines.append("## Per-roadmap phase breakdown\n")
+    for r in roadmaps:
+        lines.append(f"### [{r.rel}](roadmaps/{r.rel})\n")
+        lines.append(f"**{r.title}** — {r.done} / {r.total_active} done ({r.percent}%)\n")
+        lines.append("| # | Phase | State | Done | Open | Deferred | Cancelled | % |")
+        lines.append("|---|---|---|---:|---:|---:|---:|---:|")
+        for p in r.phases:
+            lines.append(
+                f"| {p.number} | {p.name} | {p.state} | {p.done} | {p.open_} | "
+                f"{p.deferred} | {p.cancelled} | {p.percent}% |"
+            )
+        lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="exit 1 if progress.md is stale")
+    parser.add_argument("--repo-root", type=Path, default=Path.cwd(),
+                        help="project root (default: cwd)")
+    args = parser.parse_args()
+    roadmap_root = args.repo_root / "agents" / "roadmaps"
+    target = args.repo_root / "agents" / "roadmaps-progress.md"
+    if not roadmap_root.is_dir():
+        # No roadmaps directory yet — skip silently so the CI check is safe in
+        # consumer projects that haven't adopted roadmaps.
+        if args.check:
+            return 0
+        print(f"ℹ️  No roadmaps directory at {roadmap_root} — nothing to do.")
+        return 0
+    roadmaps = collect(roadmap_root)
+    new_text = render(roadmaps)
+    current = target.read_text(encoding="utf-8") if target.exists() else ""
+    if args.check:
+        if current != new_text:
+            print(f"❌  {target.relative_to(args.repo_root)} is stale. "
+                  f"Run `task roadmap-progress` to regenerate.", file=sys.stderr)
+            return 1
+        print(f"✅  {target.relative_to(args.repo_root)} is up to date.")
+        return 0
+    target.write_text(new_text, encoding="utf-8")
+    print(f"✅  Wrote {target.relative_to(args.repo_root)} · "
+          f"{len(roadmaps)} roadmap(s) · "
+          f"{sum(r.done for r in roadmaps)}/{sum(r.total_active for r in roadmaps)} steps done.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.agent-src/skills/adversarial-review/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: adversarial-review
+description: "ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback."
+personas:
+  - critical-challenger
+source: package
+---
+
+# Adversarial Review
+
+## When to use
+
+Use this skill when:
+- You've completed a plan, design, or proposed fix and are about to present it.
+- The change is non-trivial (affects multiple files, changes behavior, touches critical paths).
+- You're about to recommend an architecture or design decision.
+
+Do NOT use when:
+- The task is trivial (renaming, formatting, simple config change).
+- The user explicitly asked for a quick/rough draft.
+- You're exploring options, not committing to one yet.
+
+## Procedure: Adversarial review
+
+### Step 1: Attack (Grumpy Senior Engineer)
+
+Assume your plan/fix is flawed. Ask yourself:
+
+- What's the weakest assumption?
+- Where will this break under load, at scale, or with edge cases?
+- What did I ignore or hand-wave?
+- Is this over-engineered for the actual problem?
+- Would a simpler approach work just as well?
+- What will the next developer curse me for?
+
+### Step 2: Defend (Balanced Engineer)
+
+Counter the criticism fairly:
+
+- Which criticisms are valid and must be addressed now?
+- Which are theoretical and can be deferred?
+- What's the pragmatic middle ground?
+
+### Step 3: Revise
+
+- Fix the valid issues in your plan/fix.
+- Move deferred concerns to "Open Questions" or "Known Limitations".
+- Present the improved version to the user.
+
+**Do this internally** — the user sees the improved result, not the raw debate.
+Only surface trade-offs or concerns that need the user's input.
+
+## Context-specific attack questions
+
+### Feature plans / Architecture
+
+- Is this the simplest solution that works?
+- What happens when requirements change (and they will)?
+- Are there hidden dependencies or coupling?
+- Does this respect existing patterns or introduce a new one unnecessarily?
+- What's the migration/rollback story?
+
+### Bug fixes
+
+- Is this the root cause or just a symptom?
+- Will this fix break something else?
+- Does the fix handle the edge case that caused the bug?
+- Is there a regression test that proves the fix works?
+- Are there other places with the same bug pattern?
+
+### Code changes / Refactoring
+
+- Would I understand this code in 6 months without context?
+- Did I check all callers and downstream effects?
+- Are the tests actually testing the right behavior?
+- Did I introduce a new pattern where an existing one would work?
+
+### Database migrations
+
+- Can this destroy or corrupt data?
+- Is rollback possible?
+- What happens to running queries during migration?
+- Did I check the table size (large table ALTER can lock)?
+
+### API design
+
+- Is this a breaking change?
+- Is it consistent with existing endpoints?
+- Are error responses clear and actionable?
+- Did I consider pagination, filtering, versioning?
+
+### Security-sensitive changes
+
+- Where is the attack surface I'm not seeing?
+- Am I trusting user input anywhere?
+- Are there authorization gaps?
+- Would this pass a security review?
+
+## Integration with other skills
+
+- **feature-planning** — adversarial review after Understanding Lock, before presenting the plan.
+- **bug-analyzer** — review the proposed fix before implementing.
+- **code-review** — self-review before creating a PR.
+- **migration-creator** — review migration for data safety.
+- **api-design** — review API design for consistency and breaking changes.
+- **security** — review security-sensitive changes for attack surface.
+
+## Auto-trigger keywords
+
+- adversarial review
+- self-review
+- challenge plan
+- review my approach
+- sanity check
+
+### Validate
+
+- Confirm each identified risk has a concrete mitigation or explicit acceptance.
+- Verify the review produced at least one actionable finding (or explicit "no issues found").
+- Check that the review did not just restate the plan — it must challenge assumptions.
+
+## Output format
+
+1. Improved plan/code incorporating adversarial findings
+2. Risk summary — top concerns discovered and how they were addressed
+3. Remaining open risks (if any) with severity rating
+
+## Gotcha
+
+- Don't use this on trivial changes — it adds overhead without value on simple renames or config tweaks.
+- The model tends to invent risks that don't exist. Ground every concern in actual code, not hypotheticals.
+- Don't challenge the user's explicit requirements — challenge the implementation, not the goal.
+
+## Do NOT
+
+- Do NOT present the raw adversarial debate to the user — only the improved result.
+- Do NOT use this as an excuse to delay work — the review should take seconds, not minutes.
+- Do NOT apply this to trivial changes — it adds overhead without value.
+- Do NOT let the "grumpy engineer" kill good ideas — the balanced engineer must counter.
+- Do NOT skip Step 3 (Revise) — attacking without improving is just complaining.
+
+## References
+
+- **Tree-of-Thoughts (ToT)** — [arxiv.org/abs/2305.10601](https://arxiv.org/abs/2305.10601)
+  Deliberate problem-solving by exploring multiple reasoning branches.
+  This skill adapts ToT by pitting a grumpy engineer against a
+  balanced engineer — the branching happens between roles, not
+  between thought-tree nodes.
+