@event4u/agent-config 14.1.0 → 14.4.0

package/dist/agent-src/scripts/roadmap_gates.ts

@@ -342,6 +342,201 @@ function render(
  * Returns '' when nothing is owned by the user, so the caller can append the
  * result unconditionally and get silence when silence is correct.
  */
+/**
+ * Whether a recorded recommendation was drafted by the agent rather than decided
+ * by the maintainer.
+ *
+ * Read from the field's own text, because that is where the claim has to live: a
+ * drafted recommendation is written INTO the roadmap so every consumer
+ * (`gates`, `--reply`, the sheet) sees the same string, and a marker held only
+ * in the sheet would be invisible to the other two. The convention is a leading
+ * `(agent-drafted …)` — matched loosely on purpose, since the parenthetical also
+ * carries a date and a sentence of provenance.
+ */
+export function isAgentDrafted(recommendation: string): boolean {
+    return /\(agent-drafted\b/i.test(recommendation);
+}
+
+/**
+ * How a row names its decision.
+ *
+ * `legacy` is the parser's PLACEHOLDER id for a `> Blocked until …` note, not an
+ * identifier anyone wrote — `renderEntry` already substitutes "blocked-until
+ * note" for exactly that reason, and the sheet printing the raw placeholder made
+ * the two views disagree about the same row.
+ */
+export function sheetLabel(b: Blocker): string {
+    return isLegacy(b) ? 'blocked-until note' : `\`${b.id}\``;
+}
+
+/** First sentence of a passage, for the one-line `Default:` column. */
+function firstSentence(text: string): string {
+    const trimmed = text.trim();
+    if (trimmed === '') {
+        return '';
+    }
+    const m = /^(.+?[.!?])(\s|$)/.exec(trimmed.replace(/\s+/g, ' '));
+    return m === null ? trimmed.replace(/\s+/g, ' ') : (m[1] as string);
+}
+
+/**
+ * The one-line question a sheet row leads with.
+ *
+ * `Question:` is an optional field and only 5 of the 21 user-owned entries carry
+ * one (measured 2026-08-18), so a sheet that printed it and nothing else would
+ * be blank for three quarters of the estate. Falling back to the first step of
+ * `What to do:` and then to `Blocks:` is deterministic and derived from the
+ * blocker's own text — which is why the row LABELS which of the three it used
+ * rather than presenting all three as the same kind of statement.
+ */
+export function sheetQuestion(b: Blocker): { text: string; source: 'question' | 'todo' | 'blocks' } {
+    if (b.question.trim() !== '') {
+        return { text: firstSentence(b.question), source: 'question' };
+    }
+    const steps = regroupTodo(b.todo);
+    if (steps.length > 0 && (steps[0] as string).trim() !== '') {
+        return { text: firstSentence(steps[0] as string), source: 'todo' };
+    }
+    return { text: firstSentence(b.blocks), source: 'blocks' };
+}
+
+/**
+ * The consolidated decision sheet — every user-owned decision in ONE artefact.
+ *
+ * `road-to-estate-drawdown` Phase 0 exists because thirteen reading assignments
+ * spread across thirteen files did not happen once. The sheet is the whole of
+ * the human's contribution to that campaign, front-loaded: one document, sorted
+ * by how much each answer unblocks, with a default per item so that
+ * accept-all-defaults is a valid answer.
+ *
+ * This differs from `--all` in the two ways that matter for that job. `--all`
+ * renders every blocker grouped by owner and is a terminal view; the sheet is
+ * user-owned ONLY, and every row carries a `Default:` plus the PROVENANCE of
+ * that default. Provenance is the load-bearing column: a sheet that presented an
+ * agent-drafted default beside a maintainer-recorded one as the same thing would
+ * invite accept-all over exactly the items nobody has examined.
+ *
+ * No population figure is quoted here on purpose. The first version cited
+ * "14 of 21 record a `Recommendation:`, 7 do not" as the justification, and the
+ * change that added this renderer then drafted six of those seven — so the
+ * docstring was contradicted by the sheet committed beside it (R2 finding).
+ * The split is rendered in the sheet's own header from the live tree, which is
+ * the only place it cannot go stale.
+ *
+ * Deterministic by construction — the generator never invents a default. Where
+ * none is recorded it says so and names what the reader must supply, so
+ * regenerating the sheet cannot silently overwrite an answer with a guess.
+ */
+function renderSheet(entries: readonly Entry[], now: Date): string {
+    const mine = entries.filter((e) => needsUser(e.blocker.owner));
+    const stamp = now.toISOString().slice(0, 10);
+    if (mine.length === 0) {
+        return (
+            `# Consolidated decision sheet — nothing owned by you (${stamp})\n\n` +
+            'No open blocker in the active roadmap tree carries `Owner: user`. Nothing to answer.\n'
+        );
+    }
+
+    const noRec = mine.filter((e) => e.blocker.recommendation.trim() === '');
+    const legacyNotes = noRec.filter((e) => isLegacy(e.blocker)).length;
+    const missing = noRec.length - legacyNotes;
+    const drafted = mine.filter((e) => isAgentDrafted(e.blocker.recommendation)).length;
+    const maintainerRecorded = mine.length - noRec.length - drafted;
+    const out: string[] = [
+        `# Consolidated decision sheet — ${String(mine.length)} decisions owned by you`,
+        '',
+        `> Generated ${stamp} by \`agent-config gates --sheet\` over \`agents/roadmaps/\`.`,
+        '> Sorted by unblock count, descending. **Accept-all-defaults is a valid answer**',
+        '> (`road-to-estate-drawdown` blocker `b-consolidated-decision-sheet`, option (a));',
+        '> answering only the two largest-unblock items and deferring the rest is option (c),',
+        '> which the roadmap itself recommends. Whichever you pick, the agent writes the answers',
+        '> back into each roadmap at its own blocker — that is not your work.',
+        '>',
+        `> **Provenance of the ${String(mine.length)} defaults: ${String(maintainerRecorded)} maintainer-recorded ·`,
+        `> ${String(drafted)} \`agent-drafted\` · ${String(missing)} with no recommendation at all ·`,
+        `> ${String(legacyNotes)} legacy \`> Blocked until …\` note(s) that have no field to carry one.**`,
+        '> The distinction is in every row on purpose: an agent-drafted default is the',
+        '> least-examined thing on this sheet, and accept-all-defaults would accept those too.',
+        '>',
+        '> This file is DERIVED — every line above and below comes from the roadmaps themselves,',
+        '> so regenerating is deterministic and an answer written into this file would be lost.',
+        '> Answers go back into each roadmap at its own blocker; the agent does that.',
+        '',
+        '| # | Decision | Roadmap | Unblocks | Default source |',
+        '|---:|---|---|---:|---|',
+    ];
+    mine.forEach((e, i) => {
+        const source =
+            e.blocker.recommendation.trim() !== ''
+                ? isAgentDrafted(e.blocker.recommendation)
+                    ? '`agent-drafted`'
+                    : 'maintainer-recorded'
+                : isLegacy(e.blocker)
+                  ? 'none — legacy note'
+                  : 'none recorded';
+        out.push(
+            `| ${String(i + 1)} | ${sheetLabel(e.blocker)} | ${e.roadmapRel} | ` +
+                `${String(e.openSteps)} | ${source} |`,
+        );
+    });
+
+    mine.forEach((e, i) => {
+        const q = sheetQuestion(e.blocker);
+        const qLabel =
+            q.source === 'question'
+                ? 'recorded `Question:`'
+                : q.source === 'todo'
+                  ? 'derived from the first `What to do:` step'
+                  : 'derived from `Blocks:`';
+        const recorded = e.blocker.recommendation.trim();
+        out.push(
+            '',
+            `## ${String(i + 1)} · ${sheetLabel(e.blocker)}`,
+            '',
+            `- **Roadmap:** ${e.roadmapRel}`,
+            `- **Unblocks:** ${String(e.openSteps)} open step(s) — ${e.blocker.blocks || '(not recorded)'}`,
+            `- **Question** (${qLabel})**:** ${q.text || '(the blocker records no question, no steps and no Blocks: field)'}`,
+        );
+        if (recorded === '' && isLegacy(e.blocker)) {
+            // A legacy `> Blocked until …` note is not a `### blocker:` entry and
+            // has no field to carry a recommendation. Saying "agent-drafted, to
+            // be written in" would point at a slot that does not exist, so the
+            // row names the actual next action instead.
+            out.push(
+                '- **Default:** _this is a legacy `> Blocked until …` note, not a `### blocker:` entry,' +
+                    ' so it has no `Recommendation:` field to read. Converting it into a real blocker' +
+                    ' entry is what gives it a default._',
+                '- **Default source:** none — legacy note',
+            );
+        } else if (recorded === '') {
+            out.push(
+                '- **Default:** _none recorded — needs an agent-drafted default before this row can be' +
+                    ' answered by accepting it._',
+                '- **Default source:** `agent-drafted` (to be written in below, and marked as such)',
+            );
+        } else {
+            const drafted = isAgentDrafted(recorded);
+            out.push(
+                `- **Default:** ${firstSentence(recorded)}`,
+                drafted
+                    ? '- **Default source:** `agent-drafted` — written into the roadmap’s ' +
+                      '`Recommendation:` field and marked there, NOT a maintainer decision'
+                    : '- **Default source:** maintainer-recorded `Recommendation:` in the roadmap',
+                `- **Recommendation (full):** ${recorded.replace(/\s+/g, ' ')}`,
+            );
+        }
+        if (e.blocker.ifNothing.trim() !== '') {
+            out.push(`- **If you do nothing:** ${e.blocker.ifNothing.replace(/\s+/g, ' ')}`);
+        }
+        out.push(
+            `- **Done when:** ${e.blocker.resolvedWhen.replace(/\s+/g, ' ') || '(not recorded)'}`,
+            '- **Your answer:** _(accept default · override · defer)_',
+        );
+    });
+    out.push('');
+    return out.join('\n');
+}
+
 function renderReply(entries: readonly Entry[]): string {
     const mine = entries.filter((e) => needsUser(e.blocker.owner));
     if (mine.length === 0) {
@@ -564,6 +759,7 @@ function main(argv?: readonly string[]): number {
     const json = args.includes('--json');
     const reply = args.includes('--reply');
     const pending = args.includes('--pending');
+    const sheet = args.includes('--sheet');
 
     // `--execute <id>` is answered FIRST, and it is the only mode that writes.
     // It used to sit after the `--pending` early return, so `--pending
@@ -643,13 +839,20 @@ function main(argv?: readonly string[]): number {
     // `--reply` deliberately does not carry the probe: ADR-222 fixes that form
     // at exactly ONE decision rendered in full, and a fired resume condition is
     // not a decision the reader owes anybody — it is a file that can move.
-    const resumed = reply ? [] : probeLater(roadmapRoot);
+    // `--reply` and `--sheet` deliberately do not carry the probe: ADR-222 fixes
+    // the reply form at exactly ONE decision rendered in full, and a fired resume
+    // condition is not a decision the reader owes anybody — it is a file that can
+    // move. The sheet is the same argument for the same reason: it is the set of
+    // answers the user owes, and a movable file is not one of them.
+    const resumed = reply || sheet ? [] : probeLater(roadmapRoot, repoRoot);
     process.stdout.write(
-        reply
-            ? renderReply(entries)
-            : json
-              ? renderJson(entries, all, resumed)
-              : render(entries, all, resumed),
+        sheet
+            ? renderSheet(entries, new Date())
+            : reply
+              ? renderReply(entries)
+              : json
+                ? renderJson(entries, all, resumed)
+                : render(entries, all, resumed),
     );
     return 0;
 }
@@ -687,6 +890,7 @@ export {
     renderJson,
     renderReply,
     renderResumed,
+    renderSheet,
     renderPending,
     renderPendingJson,
 };

package/dist/agent-src/skills/roadmap-management/SKILL.md

@@ -293,8 +293,8 @@ After the last step of a roadmap is done, check completion status:
    |---|---|---|---|---|
    | ≥ 1 | 0 | 0 | 0 | **Auto-archive** (silent) — pure completion |
    | ≥ 1 | 0 | 0 | ≥ 1 | **Auto-archive** (silent) — done with explicit drops |
-   | ≥ 1 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Surface deferred items, present follow-up options, wait. See step 4b. |
-   | 0 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Was this a scope-drop or deferred-to-later? Same options as 4b. |
+   | ≥ 1 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Surface deferred items, present the options, resolve by the preservation test (council where the item survives, user where it does not). See step 4b. |
+   | 0 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Was this a scope-drop or deferred-to-later? Same options and same routing as 4b. |
    | 0 | 0 | 0 | ≥ 1 | **Auto-skip** (silent) — no work, all cancelled |
    | ≥ 0 | ≥ 1 | ≥ 0 | ≥ 0 | **Ask the user** — open work remains (step 4a) |
 
@@ -343,8 +343,13 @@ After the last step of a roadmap is done, check completion status:
    the active tree.
 
 4b. **Deferred items present (`count_deferred ≥ 1`, `count_open == 0`)** — Iron Law 3 flow.
-   The archive is **blocked** until the user resolves the deferrals. Surface
-   the plan and ask:
+   Archive **blocked** until resolved. WHO resolves is the preservation test in
+   [`roadmap-progress-sync § Who resolves it`](../../rules/roadmap-progress-sync.md),
+   never the mode — same menu either way, only the resolver differs:
+
+   - **1, 2, 4** keep the item alive → **council**, recorded at the item (2 only
+     if the follow-up lands in the SAME change).
+   - **3, 5** drop or weaken it → **user**, always. In doubt: user.
 
    ```
    📋 Roadmap closure check — deferred items must resolve before archive:

package/dist/agent-src/templates/agent-settings.md

@@ -507,6 +507,68 @@ telemetry:
       # Append-only JSONL log. Path is relative to the project root.
       # Always gitignored (see config/gitignore-block.txt).
       path: .agent-engagement.jsonl
+  # --- Org telemetry (road-to-org-telemetry Phase 1) ---
+  #
+  # Class-A usage records: which skill was invoked, on which host, at which
+  # package version and rule tier, under a pseudonymous user hash and an
+  # hour-bucketed timestamp. Zero bytes of project content — the record type
+  # has no field capable of holding free text.
+  #
+  # `enabled: true` on its own does NOT switch this on. All three of
+  # `endpoint`, `org_id`, and `salt` must also carry a value, and none of
+  # them has a default. That is deliberate: this repository is public, so it
+  # ships the key NAMES and no values, and a clone cannot reach the write
+  # path by copying the tree. The values come from an org pack.
+  #
+  # Phase 1 writes records LOCALLY and nothing else. The outbound flush is
+  # Phase 2 and org-wide enablement is Phase 3; both are gated on open
+  # blockers in the roadmap.
+  remote:
+    # Master switch. Combined with the three required fields below — see
+    # `active` in scripts/telemetry/settings.ts.
+    enabled: false
+    # Where Phase 2 will flush to. Recorded now, never called in Phase 1.
+    endpoint: ""
+    # The org whose pack enabled this install; written into every record.
+    org_id: ""
+    # Org-pack secret. Salts the user and session hashes so a digest of a
+    # login name is not reversible by dictionary. Never written into a
+    # record, never logged.
+    #
+    # It must live in the SAME `.agent-settings.yml` the reader resolves —
+    # `read_remote_settings` opens one file and consults no override layer,
+    # so a salt placed in `.agent-settings.local.yml` leaves the install
+    # silently inactive. Keep that file out of version control, or supply it
+    # from the org pack at install time.
+    salt: ""
+    # `session-end` = flush at session end (Phase 2). `never` = no transport,
+    # which is a legitimate way to run the local half while the sink question
+    # is still open.
+    #
+    # `never` is NOT an unbounded steady state: the retention budget below
+    # bounds the log whether or not a flush is configured. The consequence
+    # worth knowing before choosing `never` is that the local file is then the
+    # only store, so a record retention evicts is a record that is never sent
+    # anywhere. Raise `retention.max_age_days` if you need a longer local
+    # history.
+    flush: session-end
+    # Growth budget for the log below (`scale-discipline` R-A7). Enforced by
+    # the writer itself, so there is no sweep to remember to run: after each
+    # append, records older than `max_age_days` are dropped, and the file is
+    # held under `max_bytes` from the oldest end regardless of dates.
+    #
+    # The defaults are measured, not guessed. The busiest machine this tree
+    # has observed writes 6.6 skill invocations a day at ~270 bytes each, so
+    # 90 days is roughly 600 records (~160 KiB) and is the cap that actually
+    # binds; 2 MiB is the backstop for a rate that has not been observed.
+    # Omit the section to take both defaults — there is no way to configure
+    # "unbounded", which is the state R-A7 forbids.
+    retention:
+      max_age_days: 90
+      max_bytes: 2097152
+    output:
+      # Append-only JSONL log, relative to the project root. Gitignored.
+      path: .agent-telemetry.jsonl
 
 # --- Linked projects (cross-repo awareness, local-only) ---
 #
@@ -602,6 +664,14 @@ the canonical narrative lives in
 | `telemetry.artifact_engagement.record.consulted` | `true`, `false` | `true` | When `true`: record artefacts loaded into context. |
 | `telemetry.artifact_engagement.record.applied` | `true`, `false` | `true` | When `true`: record artefacts cited or driving a decision. |
 | `telemetry.artifact_engagement.output.path` | path | `.agent-engagement.jsonl` | Append-only JSONL log path, relative to the project root. Always gitignored. |
+| `telemetry.remote.enabled` | `true`, `false` | `false` | Opt-in for Class-A org usage records. **Not the switch on its own** — `endpoint`, `org_id`, and `salt` must all carry a value too, and none has a default, so a clone of the public repository cannot reach the write path. Not in the shipped template; a missing section means disabled. |
+| `telemetry.remote.endpoint` | URL | *(none)* | Where Phase 2 will flush records to. Recorded now; no outbound call exists in Phase 1. Empty ⇒ inactive. |
+| `telemetry.remote.org_id` | string | *(none)* | The org whose pack enabled this install; written into every record. Empty ⇒ inactive. |
+| `telemetry.remote.salt` | string | *(none)* | Org-pack secret salting the user and session hashes — without it a digest of a login name is dictionary-reversible. Never written into a record, never logged. Must sit in the same `.agent-settings.yml` the reader resolves: it consults no override layer, so a salt in `.agent-settings.local.yml` leaves the install silently inactive. Empty ⇒ inactive. |
+| `telemetry.remote.flush` | `session-end`, `never` | `session-end` | When Phase 2 flushes. `never` means no transport — a legitimate way to run the local half while the sink question is open. It is **not** an unbounded steady state: `retention` below bounds the log either way. Under `never` the local file is the only store, so a record retention evicts is never sent anywhere. |
+| `telemetry.remote.retention.max_age_days` | positive integer | `90` | TTL for the local log (`scale-discipline` R-A7). Records older than this are dropped after an append. At the observed 6.6 invocations/day this is ~600 records (~160 KiB) and is the cap that actually binds. Zero, negative, and non-integer values fall back to the default — there is no way to configure "unbounded". |
+| `telemetry.remote.retention.max_bytes` | positive integer | `2097152` (2 MiB) | Hard ceiling on the local log regardless of record age; the oldest records are dropped first, back to 75 % of the cap so the next prune is not immediate. Backstop for a write rate this tree has not observed. |
+| `telemetry.remote.output.path` | path | `.agent-telemetry.jsonl` | Append-only JSONL log path, relative to the project root. Gitignored. Bounded by `retention` above. |
 | `linked_projects` | list of `{path, include}` | `[]` | IDE-attached sibling repos in scope for proactive cross-repo awareness. **Belongs in `.agent-settings.local.yml` (in agents/settings/)** (per-machine, gitignored). See [cross-repo guide](../../docs/guides/cross-repo-linked-projects.md) + ADR-032. |
 | `linked_projects_max_files` | integer | `20000` | File-count ceiling above which a detected sibling is flagged `large` (awareness only). Never excludes. |
 | `knowledge.global_sharing.enabled` | `true`, `false` | `true` | **User-global** (keep in `~/.event4u/agent-config/agent-settings.yml`). Master switch for the file-first global knowledge-card store (ADR-100; default-ON per ADR-119, the council-validated bounded-downside flip superseding ADR-103 — adversarially spot-checked redaction incl. hidden-unicode hardening, narrowest tier default, pre-registered demotion trigger). `false` fully no-ops the layer (single-key revert); v1 project-local cards unaffected. |

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "14.1.0"
+agent_config_version: "14.4.0"
 
 # --- Project identity ---
 project: