@event4u/agent-config 9.33.0 → 9.35.0

package/src/scripts/lint_framework_leakage_allowlist.json

@@ -1,152 +1,160 @@
 {
   "version": 1,
-  "_doc": "Each entry: { file: relative path from repo root, lines: [int,...] | \"*\" for whole file, reason: short justification }. Use sparingly — first ask whether the file should be neutralized or carved out. Policy cap: > 20 entries means the linter (or the content) is wrong — fix the tool or the text, never grow the list. Rebuilt 2026-07-12 (road-to-opt-hygiene-and-debt Phase 1): 104 → minimal set after heuristic upgrades + 25 content neutralizations + 2 carve-outs.",
+  "_doc": "Each entry: { file: relative path from repo root, anchor: a substring of the exempted line (the ONLY per-line key — position keys are refused by validate_allowlist), or lines: \"*\" for the whole file, reason: short justification }. Use sparingly — first ask whether the file should be neutralized or carved out. Policy cap: > 20 exempted FILES means the linter (or the content) is wrong — fix the tool or the text, never grow the list. The cap counts files because that is the unit it was written in, when one entry meant one file; entries are now per-line, so the two numbers differ on purpose (15 files / 31 entries as of the anchor migration) and the entry count is not the cap. Rebuilt 2026-07-12 (road-to-opt-hygiene-and-debt Phase 1): 104 -> minimal set after heuristic upgrades + 25 content neutralizations + 2 carve-outs. Re-keyed to content anchors 2026-08-12: 8 of the 39 exempted lines were found to exempt nothing — three named blank or out-of-range lines, five named lines that produce no hit — and were dropped rather than carried forward; the gate now refuses both shapes.",
   "entries": [
-    {
-      "file": "src/rules/code-comment-discipline.md",
-      "lines": [
-        100
-      ],
-      "reason": "Worked PHP docblock demo inside the rule's own wrong/right example block — quoted teaching content."
-    },
     {
       "file": "src/skills/api-testing/SKILL.md",
-      "lines": [
-        218
-      ],
+      "anchor": "- Don't test framework internals (e.g., \"does Laravel return",
       "reason": "Quoted example of a framework-internal behavior explicitly marked as what NOT to test — meta content, not a mandate."
     },
     {
       "file": "src/skills/learning-to-rule-or-skill/SKILL.md",
-      "lines": [
-        320,
-        322
-      ],
+      "anchor": "Decision: Create focused skill for Laravel route inspection ",
+      "reason": "Example learnings/decisions quoted verbatim in the promotion-flow walkthrough — meta content."
+    },
+    {
+      "file": "src/skills/learning-to-rule-or-skill/SKILL.md",
+      "anchor": "Learning: \"I forgot to run PHPStan once.\"",
       "reason": "Example learnings/decisions quoted verbatim in the promotion-flow walkthrough — meta content."
     },
     {
       "file": "src/skills/markitdown/SKILL.md",
-      "lines": [
-        74,
-        111
-      ],
+      "anchor": "uv pip install 'markitdown-mcp==0.0.1a4'",
       "reason": "Tool-intrinsic install lines — markitdown IS a pip package; the install command is the tool's identity, not stack leakage."
     },
+    {
+      "file": "src/skills/markitdown/SKILL.md",
+      "anchor": "Plugins enable arbitrary code paths inside the conversion pi",
+      "reason": "Tool-intrinsic install lines — markitdown IS a pip package; the install command is the tool's identity, not stack leakage."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "### Laravel HMVC carve-out",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "│   ├── api.php   web.php   console.php",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "**Auto-loading:** `app/Providers/ModuleServiceProvider.php` ",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "`app/Modules/` and registers routes (`Routes/api.php` → `/ap",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "`api` middleware; `Routes/web.php` → `web` middleware) plus ",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "// Routes/api.php — auto-prefixed /api",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
     {
       "file": "src/skills/module-management/SKILL.md",
-      "lines": [
-        87,
-        99,
-        107,
-        108,
-        109,
-        115,
-        124,
-        156,
-        172
-      ],
+      "anchor": "### Symfony DDD-lite carve-out",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "metadata in `pyproject.toml`.",
       "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
     },
     {
       "file": "src/skills/po-discovery/SKILL.md",
-      "lines": [
-        45
-      ],
+      "anchor": "(\"upgrade Laravel to 11\") — discovery adds noise; skip.",
       "reason": "Quoted example ticket title ('upgrade Laravel to 11') illustrating when discovery adds noise — meta content."
     },
     {
       "file": "src/skills/repomix-packer/SKILL.md",
-      "lines": [
-        44
-      ],
+      "anchor": "npm install -g repomix",
       "reason": "Tool-intrinsic install line — repomix IS an npm package."
     },
     {
       "file": "src/skills/rule-writing/SKILL.md",
-      "lines": [
-        78
-      ],
+      "anchor": "description: \"Writing or reviewing PHP code — strict types, ",
       "reason": "Quoted rule-description example (the php-coding rule's own description string) — meta content. Re-anchored 76→78 after the description-cap edit above it."
     },
-    {
-      "file": "src/skills/security-audit/SKILL.md",
-      "lines": [
-        122
-      ],
-      "reason": "Multi-ecosystem XSS row (Blade/JSX/Jinja peers on one line) + a quoted false-positive example ('Laravel's CSRF is already handled') — documentation, not a mandate."
-    },
     {
       "file": "src/skills/skill-reviewer/SKILL.md",
-      "lines": [
-        70
-      ],
+      "anchor": "- ❌  Describing how Laravel middleware works (in a middlewar",
       "reason": "Quoted anti-example ('❌ Describing how Laravel middleware works') — the line teaches what NOT to write."
     },
     {
       "file": "src/skills/skill-writing/SKILL.md",
-      "lines": [
-        148,
-        456
-      ],
+      "anchor": "Use when creating Laravel middleware for request filtering",
       "reason": "Quoted description examples + the 'too-broad skill (Laravel skill)' anti-pattern — meta content."
     },
     {
       "file": "src/skills/supply-chain-intake/SKILL.md",
-      "lines": [
-        80,
-        82
-      ],
+      "anchor": "rg -n '\"[^\"]+\":\\s*\"(\\^|~|\\*|latest)' package.json",
       "reason": "Per-ecosystem check commands in fenced blocks; the pip/composer siblings sit farther apart than the ±10-line window — genuine multi-ecosystem documentation."
     },
     {
-      "file": "src/skills/test-driven-development/SKILL.md",
-      "lines": [
-        197,
-        200,
-        208,
-        212
-      ],
-      "reason": "Worked Example A (PHP/Pest) paired with Example B (TypeScript/Jest) farther apart than the ±10-line window — canonical two-stack demo."
+      "file": "src/skills/supply-chain-intake/SKILL.md",
+      "anchor": "[ -f package.json ] && [ ! -f package-lock.json ] && echo \"n",
+      "reason": "Per-ecosystem check commands in fenced blocks; the pip/composer siblings sit farther apart than the ±10-line window — genuine multi-ecosystem documentation."
+    },
+    {
+      "file": "src/skills/testing-anti-patterns/SKILL.md",
+      "anchor": "Replacement: a `tests/Support/cleanupSession.php` helper or ",
+      "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
+    },
+    {
+      "file": "src/skills/testing-anti-patterns/SKILL.md",
+      "anchor": "**Concrete capture tools** for recording the real shape: `cu",
+      "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
     },
     {
       "file": "src/skills/testing-anti-patterns/SKILL.md",
-      "lines": [
-        87,
-        124,
-        185
-      ],
+      "anchor": "rg -n '\\b(it|test|describe)\\.skip\\b|\\.only\\b|xit\\(|xdescribe",
       "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
     },
     {
       "file": "src/skills/test-driven-development/SKILL.md",
-      "lines": [
-        228,
-        231,
-        239,
-        243
-      ],
+      "anchor": "### Example A — PHP / Pest",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "// tests/Unit/EmailValidatorTest.php — RED",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "Run: `./vendor/bin/pest --filter='rejects empty email'` → fa",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "// app/Validators/EmailValidator.php — GREEN (minimum)",
       "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
     },
     {
       "file": "src/skills/image-editing/SKILL.md",
-      "lines": [
-        48
-      ],
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/ada",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     },
     {
       "file": "src/skills/image-generation/SKILL.md",
-      "lines": [
-        45
-      ],
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/ada",
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
+    },
+    {
+      "file": "src/skills/prompt-engineering-image/SKILL.md",
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/adapters/<provider>.sh`",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     },
     {
       "file": "src/skills/prompt-engineering-image/SKILL.md",
-      "lines": [
-        74,
-        115
-      ],
+      "anchor": "- `node_modules/@event4u/agent-config/src/scripts/ai-image/a",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     }
   ]

package/src/scripts/lint_handoffs.ts

@@ -360,6 +360,91 @@ export function validate_handoff_artifact(text: string): string[] {
     return missing;
 }
 
+/**
+ * The body of a `## <heading>` section, up to the next heading of the same or a
+ * higher level. Fenced blocks are stripped first so a `##` inside a code fence
+ * cannot end the section early — a resume artefact routinely quotes commands.
+ */
+export function handoff_section_body(text: string, heading: string): string | null {
+    const withoutFences = text.replace(/^```[\s\S]*?^```\s*$/gm, '');
+    const start = new RegExp(`^##\\s+${heading}\\s*$`, 'mi').exec(withoutFences);
+    if (start === null) {
+        return null;
+    }
+    const rest = withoutFences.slice(start.index + start[0].length);
+    const next = /^#{1,2}\s+\S/m.exec(rest);
+    return next === null ? rest : rest.slice(0, next.index);
+}
+
+// An explicit "there are none" answer. Kept as a closed list rather than a
+// heuristic so the escape cannot be widened by accident: a section saying
+// nothing and a section saying "none" are different facts, and only the first is
+// a defect.
+const _NO_OPEN_QUESTIONS = new Set(['none', 'keine', 'n/a', 'na', 'no open questions', 'nothing']);
+
+/**
+ * Strip list markers, checkbox glyphs, emphasis and trailing sentence
+ * punctuation. The trailing strip is skipped when it would empty the line: a
+ * line that is ONLY punctuation (`...`) is a placeholder to name, not an empty
+ * section to report as blank, and the two findings say different things.
+ */
+function _bareLine(line: string): string {
+    const stripped = line
+        .trim()
+        .replace(/^[-*+]\s*/, '')
+        .replace(/^\[[ x~-]\]\s*/i, '')
+        .replace(/[*_`]/g, '')
+        .trim()
+        .toLowerCase();
+    const trimmed = stripped.replace(/[.!]+$/, '').trim();
+    return trimmed.length > 0 ? trimmed : stripped;
+}
+
+/**
+ * Shape check on the one required section whose emptiness is the defect rather
+ * than a style nit. `validate_handoff_artifact` only tests that the heading
+ * exists, so `## Open questions` followed by nothing passed while carrying
+ * nothing — and a resume artefact whose open questions are blank hands the next
+ * session a false all-clear.
+ *
+ * **The step this implements claimed the false-positive class was empty because
+ * one `?`-terminated line is required. It is not, and the counterexample ships
+ * in this repo:** `tests/scripts/lint_handoffs_artifact.test.ts` carries
+ * `## Open questions` / `- none`, which is an honest answer and would be forced
+ * to grow a fake question. So the check accepts EITHER a real question OR an
+ * explicit none-marker, and fires only on a section that answers neither —
+ * blank, or a bare placeholder. That keeps the defect the step names without
+ * turning a truthful "none" into a lint error.
+ *
+ * Returns a finding string, or null when the shape holds. A MISSING section is
+ * not this check's business — `validate_handoff_artifact` already reports it.
+ */
+export function validate_handoff_open_questions(text: string): string | null {
+    const body = handoff_section_body(text, 'Open questions');
+    if (body === null) {
+        return null;
+    }
+    const lines = body
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    if (lines.some((l) => l.length > 1 && l.endsWith('?'))) {
+        return null;
+    }
+    const bare = lines.map(_bareLine).filter((l) => l.length > 0);
+    if (bare.some((l) => _NO_OPEN_QUESTIONS.has(l))) {
+        return null;
+    }
+    if (bare.length === 0) {
+        return 'section `## Open questions` is empty — carry a `?`-terminated question, or state `none`';
+    }
+    const placeholder = new Set(['tbd', 'todo', 'wip', '...', '…', '?']);
+    if (bare.every((l) => placeholder.has(l))) {
+        return 'section `## Open questions` carries only a placeholder — carry a `?`-terminated question, or state `none`';
+    }
+    return null;
+}
+
 export function main(argv?: readonly string[]): number {
     let skills_dir = SKILLS_DIR;
     // Positional-only: flags are NOT paths. Before this filter the CI invocation
@@ -373,14 +458,19 @@ export function main(argv?: readonly string[]): number {
         // artifact mode — validate the workflow-resume file's required fields
         const text = fs.readFileSync(_resolve(args[0] as string), 'utf-8');
         const missing = validate_handoff_artifact(text);
-        if (missing.length === 0) {
+        const shape = validate_handoff_open_questions(text);
+        if (missing.length === 0 && shape === null) {
             if (!QUIET) process.stdout.write('✅  HANDOFF artifact: all required fields present\n');
             return 0;
         }
         for (const m of missing) {
             process.stdout.write(`${args[0]}:1:handoff-artifact-missing-field: missing required section \`## ${m}\`\n`);
         }
-        process.stderr.write(`❌  ${missing.length} missing HANDOFF field(s)\n`);
+        if (shape !== null) {
+            process.stdout.write(`${args[0]}:1:handoff-artifact-empty-section: ${shape}\n`);
+        }
+        const problems = missing.length + (shape === null ? 0 : 1);
+        process.stderr.write(`❌  ${problems} HANDOFF artifact problem(s)\n`);
         return 1;
     }
     if (args.length > 0) {