@event4u/agent-config 14.13.0 → 14.14.0

package/src/scripts/hook_manifest.yaml

@@ -833,6 +833,28 @@ concerns:
     args: []
     fail_closed: false
     severity: blocking
+  # Comment-discipline advisory — the write-time half of
+  # `lint_code_comments`. Scans the TEXT JUST WRITTEN (Write ->
+  # tool_input.content, Edit -> tool_input.new_string), never the file on
+  # disk, so it is forward-only by construction: a pre-existing comment the
+  # edit did not touch cannot fire it and there is no baseline to keep. Three
+  # classes: `de-comment` (a non-English comment line), `report-comment` (a
+  # comment shaped like an analysis report — markdown table, box rule, `§`
+  # head, revisit-if) and `provenance-comment` (a roadmap or reference path
+  # explaining where the code came from). Reports `{decision:"warn", reason,
+  # additional_context}` at exit 2, the same verified delivery as
+  # `delegation-nudge`; never blocks, because the classifier is a line
+  # heuristic and the deterministic refusal belongs in the gate where a human
+  # reads the whole file. NOT once-per-session, unlike edit-shape: the
+  # measured failure was 41 files each carrying the defect, and a nudge that
+  # speaks once while forty more land is that incident. fail_closed: false.
+  comment-discipline:
+    script: src/scripts/hooks/comment_discipline_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    tools: [Write, Edit]
+    needs_payload_bodies: [input]
   # road-to-token-economy-cache Phase 5.1/5.2 — edit-shape advisory. Fires
   # when a Write replaced an existing, git-tracked file of >= 50 lines while
   # the effective diff (`git diff HEAD --numstat` added+deleted vs current
@@ -1145,7 +1167,7 @@ platforms:
     session_end:      [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, design-pass]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
   claude:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register, journal-record]
@@ -1153,7 +1175,7 @@ platforms:
     stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger, roadmap-progress, design-pass-stop, suggestion-capture, journal-record, run-continuation]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, skill-route, git-authorization, session-canary, self-repair, session-register, rule-inject, suggestion-capture, journal-record]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow, source-first-gate, rule-inject]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, language-mirror, design-pass, journal-record]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, language-mirror, design-pass, journal-record]
     # `language-mirror` — round-5 § 6.1. `pre_compact` sets a pin-lost marker;
     # the `post_tool_use` entry above re-emits the pin exactly once while that
     # marker is set, then clears it. One extra injection per compaction EVENT —
@@ -1207,7 +1229,7 @@ platforms:
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow, source-first-gate]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, design-pass]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
     # subagent-ledger IS bound here, unlike the two nudges above, and the
     # difference is the delivery channel rather than the platform: the nudges
     # depend on stdout reaching the model, which this trampoline discards by
@@ -1230,7 +1252,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, design-pass]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
   # Phase 7.6 — Cline. Hooks live under `.clinerules/hooks/<HookName>`
   # (project, no file extension, must be executable per Cline docs) or
@@ -1245,7 +1267,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, design-pass]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
   # Phase 7.7 — Windsurf (Cascade). Hooks live at `.windsurf/hooks.json`
   # (project) or `~/.codeium/windsurf/hooks.json` (user). Cascade has
@@ -1281,7 +1303,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, design-pass]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
   # Phase 7.9 — Copilot has no hook surface. Concerns route through
   # rule-only fallback; the dispatcher silently no-ops on --platform copilot.

package/src/scripts/hooks/comment_discipline_hook.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Comment-discipline advisory — `post_tool_use` concern.
+ *
+ * The write-time half of `lint_code_comments`. The gate answers "may this
+ * land"; this answers "was it written that way in the first place", which is
+ * the question the maintainer actually asked after a run produced 509 German
+ * comment lines across 41 of 45 changed source files without anything
+ * objecting once.
+ *
+ * `code-comment-discipline` is `type: auto` with PROMPT keywords (`comment`,
+ * `refactor`, `implement`, …). A run that writes forty-five files while the
+ * user says "build the todo module" matches none of them, so the rule never
+ * loads — the activation gap `fix-what-you-see` names for itself, in the one
+ * place where the agent is producing the artefact the rule governs. A
+ * post-write concern fires on the TOOL EVENT and therefore does not depend on
+ * what the prompt happened to say.
+ *
+ * `Write` carries the new content in `tool_input.content`; `Edit` carries the
+ * replacement in `tool_input.new_string`. Scanning that text rather than the
+ * file on disk makes the concern forward-only by construction: a pre-existing
+ * comment the edit did not touch cannot fire it, so there is no baseline to
+ * maintain and no legacy tree to clean before turning it on.
+ *
+ * Same shape as `edit_shape_hook.ts` and `delegation_nudge_hook.ts`:
+ * `host_semantics.emitFor`'s `severity === "warn"` branch returns exit 0 with
+ * the text in `hookSpecificOutput.additionalContext`, unconditionally, so the
+ * byte handed to the host is always 0. Advisory is the right severity here
+ * and not a hedge — the classifier is a line heuristic, and a heuristic that
+ * can refuse a write would turn one false positive into a blocked session.
+ * The deterministic refusal lives in the gate, where a human can read the
+ * whole file before answering.
+ *
+ * `edit-shape` fires once per session because its advice is a habit
+ * correction that lands the first time. This one is per-write on purpose: the
+ * measured failure is forty-one files each carrying the defect, and a nudge
+ * that speaks once and then watches forty more land is the shape that
+ * produced the incident. The cost is bounded by naming at most
+ * `MAX_REPORTED` findings and no more than one line per write.
+ *
+ * ROBUSTNESS: malformed payload → exit 0 silently. This concern never blocks.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { isScannable, scanText, type CommentFinding } from '../lint_code_comments.js';
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+/** Findings named in the advisory line. The rest are counted, never listed. */
+export const MAX_REPORTED = 3;
+
+function str(v: JsonValue | undefined): string {
+    return typeof v === 'string' ? v : '';
+}
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The written text, per tool. Empty string when the payload carries none. */
+export function writtenText(toolName: string, toolInput: JsonObject): string {
+    if (toolName === 'Write') return str(toolInput['content'] as JsonValue | undefined);
+    if (toolName === 'Edit') {
+        return str(toolInput['new_string'] as JsonValue | undefined)
+            || str(toolInput['newString'] as JsonValue | undefined);
+    }
+    return '';
+}
+
+/** One advisory line, naming what fired and where. */
+export function buildAdvisoryLine(file: string, findings: readonly CommentFinding[]): string {
+    const counts = new Map<string, number>();
+    for (const f of findings) counts.set(f.cls, (counts.get(f.cls) ?? 0) + 1);
+    const summary = [...counts].map(([c, n]) => `${c} ×${n}`).join(' · ');
+    const named = findings.slice(0, MAX_REPORTED)
+        .map((f) => `line ${f.line} (${f.signal})`)
+        .join(', ');
+    const more = findings.length > MAX_REPORTED ? `, +${findings.length - MAX_REPORTED} more` : '';
+    return (
+        `comment-discipline: the text just written to ${file} carries ${summary} — ${named}${more}. `
+        + 'A comment states a WHY or a constraint the code cannot show, in English; evidence for a '
+        + 'roadmap step belongs in that roadmap, not in a second copy in the source. Rewrite or '
+        + 'delete those lines now, before the next write — `lint_code_comments` refuses them at the gate.'
+    );
+}
+
+export function main(): number {
+    try {
+        const [envelope, payload] = unwrap(readHookStdin(), 'claude');
+
+        const event = str(envelope['event'] as JsonValue | undefined);
+        if (event !== '' && event !== 'post_tool_use') return EXIT_ALLOW;
+
+        const toolName = str(
+            (payload['tool_name'] ?? payload['toolName'] ?? payload['tool']) as JsonValue | undefined,
+        );
+        if (toolName !== 'Write' && toolName !== 'Edit') return EXIT_ALLOW;
+
+        const ti = payload['tool_input'] ?? payload['toolInput'] ?? payload['input'];
+        if (!isObject(ti)) return EXIT_ALLOW;
+
+        const filePath = str((ti['file_path'] ?? ti['path'] ?? ti['filePath']) as JsonValue | undefined);
+        if (!filePath || !isScannable(filePath)) return EXIT_ALLOW;
+
+        const text = writtenText(toolName, ti);
+        if (!text) return EXIT_ALLOW;
+
+        const workspaceRoot = str(envelope['workspace_root'] as JsonValue | undefined).trim() || process.cwd();
+        const abs = path.isAbsolute(filePath) ? filePath : path.resolve(workspaceRoot, filePath);
+        const rel = path.relative(workspaceRoot, abs);
+        const shown = rel.startsWith('..') ? path.basename(abs) : rel;
+
+        const findings = scanText(shown, text);
+        if (findings.length === 0) return EXIT_ALLOW;
+
+        process.stdout.write(
+            `${JSON.stringify({
+                decision: 'warn',
+                reason: `comment-discipline: ${findings.length} comment finding(s) in the text written to ${shown}`,
+                additional_context: buildAdvisoryLine(shown, findings),
+            })}\n`,
+        );
+        return EXIT_WARN;
+    } catch {
+        return EXIT_ALLOW;
+    }
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) process.exit(main());

package/src/scripts/hooks/concern_registry.ts

@@ -69,6 +69,7 @@ import { main as ruleInjectMain } from './rule_inject_hook.js';
 import { main as endReviewNudgeMain } from './end_review_nudge_hook.js';
 import { main as turnEndGateMain } from './turn_end_gate_hook.js';
 import { main as editShapeMain } from './edit_shape_hook.js';
+import { main as commentDisciplineMain } from './comment_discipline_hook.js';
 import { main as rereadGuardMain } from './reread_guard_hook.js';
 import { main as sessionEolMain } from './session_eol_hook.js';
 import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
@@ -129,6 +130,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/end_review_nudge_hook.ts': endReviewNudgeMain as ConcernMain,
     'src/scripts/hooks/turn_end_gate_hook.ts': turnEndGateMain as ConcernMain,
     'src/scripts/hooks/edit_shape_hook.ts': editShapeMain as ConcernMain,
+    'src/scripts/hooks/comment_discipline_hook.ts': commentDisciplineMain as ConcernMain,
     'src/scripts/hooks/reread_guard_hook.ts': rereadGuardMain as ConcernMain,
     'src/scripts/hooks/session_eol_hook.ts': sessionEolMain as ConcernMain,
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -579,12 +579,20 @@ export function readLanguagePin(workspaceRoot: string, session_id: string): Verd
  * WHAT IS ACTUALLY CLASSIFIED, stated accurately because R2 finding 9 caught
  * this file claiming otherwise in three places. `visibleProse` strips code,
  * quotes, tables, URLs and paths from the whole reply — but `classify` then
- * applies `instructionText` (which drops output-shaped lines and their
+ * applies `stripInjectedRegions` (which removes balanced host wrapper regions
+ * such as `<launch-selected-element>`, plus the host's advisory sentence beside
+ * them), then `instructionText` (which drops output-shaped lines and their
  * followers) and `humanAuthoredLead`, and RETURNS ON THE LEAD ALONE when the
  * lead is determined. So in the common case the verdict comes from the reply's
  * opening chunk, not from all of it, and indented prose is discarded before
  * scoring.
  *
+ * The region strip reaches this path too, and its effect here is small by
+ * construction: `visibleProse` has already removed fenced code, so a balanced
+ * bare-tag pair surviving into the scorer is prose the reply wrote around a tag
+ * rather than markup. Named rather than omitted, because enumerating the
+ * scoring surface accurately is this comment's entire job.
+ *
  * That is deliberately left as-is rather than swapped for a full-text scorer:
  * sharing one classifier with `language_mirror_hook` is what stops the pin and
  * the detector disagreeing about what language a turn is in, and changing the

package/src/scripts/language_mirror_hook.ts

@@ -83,7 +83,11 @@ import {
   session_state_file,
 } from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
-import { humanAuthoredLead, isSyntheticPrompt } from "./_lib/prompt_shape.js";
+import {
+  humanAuthoredLead,
+  isSyntheticPrompt,
+  stripInjectedRegions,
+} from "./_lib/prompt_shape.js";
 
 const EXIT_ALLOW = 0;
 // Severity is taken from the EXIT CODE, not from the `decision` field in the
@@ -296,9 +300,17 @@ export function instructionText(prompt: string): string {
  * an English instruction over a German paste resolves to English by the same
  * step. The fallback is what keeps it conservative: a prompt with no document
  * marker classifies exactly as it did before.
+ *
+ * `stripInjectedRegions` runs FIRST, and the order is load-bearing rather than
+ * tidy. A host wrapper the user never typed — `<launch-selected-element>` — is
+ * a bare tag line, which `humanAuthoredLead` read as the END of the human lead;
+ * prepended, as the host prepends it, that returned an empty lead and handed the
+ * verdict to ~4 KB of injected markup. Stripping before `instructionText` also
+ * keeps the block's indented lines from arming that filter's paste state, which
+ * was deleting the user's own sentence outright.
  */
 export function classify(prompt: string): Classification {
-  const text = instructionText(prompt);
+  const text = instructionText(stripInjectedRegions(prompt));
   const lead = humanAuthoredLead(text);
   const leadVerdict = _score(lead);
   if (leadVerdict.language !== "und") {