@event4u/agent-config 14.11.0 → 14.13.0

package/dist/agent-src/skills/testing-anti-patterns/process-anti-patterns.md

@@ -17,11 +17,48 @@ is still mocking the mock.
 ```
 WHEN YOU FIND YOURSELF KEEPING UNTESTED CODE "AS REFERENCE" WHILE WRITING
 A TEST FOR IT — DELETE THE CODE. WRITE THE TEST. THEN REIMPLEMENT.
+THE CODE IN QUESTION IS THE UNTESTED CODE THIS TASK JUST WROTE.
+IT IS NOT PRE-EXISTING CODE, AND THE LAW NEVER OVERRIDES A REUSE VERDICT.
 ```
 
 The cheap path is one extra round-trip. The expensive path is a test that
 silently encodes the bug it was supposed to catch.
 
+### The three cases — only one of them is a deletion
+
+Unqualified, this law reads as a standing instruction to delete any untested
+code in reach. That reading is wrong in two of the three cases, and the wrong
+one is expensive: it discards working behavior a reuse verdict would keep.
+
+| The code is | Do | Why |
+|---|---|---|
+| **untested, written by this task** | delete it, write the test, reimplement | Nothing is lost — you can rewrite what you wrote minutes ago, and the test is then written against the behavior you wanted rather than the code you happened to produce |
+| **pre-existing and tested** | keep it | Its tests ARE the record of its behavior. Deleting it to re-derive the same thing throws away evidence you cannot cheaply rebuild, and directly contradicts a reuse / extend verdict |
+| **pre-existing and untested** | write a characterization test first | Deleting it destroys the only remaining record of what it does. The test comes first, but it pins TODAY's behavior — not the behavior you wish it had |
+
+### The characterization-test procedure
+
+For the third case, in order:
+
+1. **Observe, do not judge.** Run the code on real inputs and record what it
+   actually returns — including outputs you believe are wrong. Bug-compatible
+   is the point: the test's job is to detect *change*, not to assert *correctness*.
+2. **Pin the observed values.** Assert them exactly. A characterization test
+   whose expected value is derived from the same code it tests is a tautology.
+3. **Name it as one.** Prefix or tag the test (`characterizes_…`, a
+   `@characterization` marker) so a later reader does not mistake a pinned bug
+   for a desired behavior.
+4. **Now change the behavior.** With the pin in place, the intended change is
+   an ordinary red-green cycle: the characterization test that must now change
+   is the blast radius, made visible.
+5. **Update or delete the pin deliberately.** When the new behavior is
+   correct, the pinned assertion is edited *because the behavior changed* —
+   stated in the diff, never quietly.
+
+**What this is NOT.** Not permission to skip TDD on new behavior — the pin
+covers what exists, the new behavior still starts from a failing test. Not a
+coverage exercise: pin the behavior the change will touch, not the whole file.
+
 ## 12-row anti-rationalization table
 
 The urge to skip TDD is strongest on tasks where TDD matters most. Name

package/dist/agent-src/skills/ui-component-architect/SKILL.md

@@ -68,6 +68,14 @@ still exists in the tree. Absent or empty → fall through to
 
 Then review existing components in the codebase for the same
 responsibility — extend rather than rebuild when a match is found.
+
+**A new component's workshop is part of its design, on every React lane and not
+only `react-shadcn`.** When the extraction is agreed, the story set comes from
+[`storybook-workshop`](../storybook-workshop/SKILL.md) — one story per concept
+off the state-coverage matrix below, which is what makes the component
+agent-readable and its contrast floor checkable before it reaches a page. That
+skill is stack-agnostic and ships in `engineering-base`, so a plain-`react`
+project receives it exactly as a `react-shadcn` one does.
 If none exists, write the new component's purpose: *"Renders a
 labelled input with inline error and hint."* If the sentence has an
 "and" joining two unrelated jobs, the component is two components.
@@ -115,8 +123,51 @@ Prop budget per component:
 | Composite (Card, Dialog) | ≤ 8 props; prefer slots for variants |
 | Page section / feature shell | ≤ 4 props; everything else via context |
 
-Over-budget triggers a refactor: extract a config object, push
-state into context, or split into compound parts.
+Over-budget is a **prompt to look**, not a verdict. Extract a config object,
+push state into context, or split into compound parts — **or record why the
+count is right for this component.**
+
+```
+THE CAPS ABOVE ARE ADVISORY. THEY ARE NOT A GATE AND MUST NOT BECOME ONE
+WITHOUT A NEW MEASUREMENT. NOTHING COMPUTES THE TIER, SO NOTHING CAN APPLY THEM
+AUTOMATICALLY EVEN IF IT WANTED TO.
+```
+
+**Why advisory, measured rather than asserted** (2026-08-24, one production
+component library: 55 atoms, 3 molecules, 2 organisms):
+
+| component | its level | props | cap here | over |
+|---|---|---:|---:|---:|
+| `file-upload` | **atom** | 19 | 6 | **3.2×** |
+| `date-navigator` | molecule | 18 | 8 | 2.25× |
+| `picker-sheet` | organism | 14 | 4 | **3.5×** |
+| `duration-input` | molecule | 13 | 8 | 1.6× |
+| `stepper` | molecule | 4 | 8 | — |
+
+**The budget is INVERTED, and that is the finding rather than a calibration
+error.** This table tightens as granularity rises. Reality goes the other way:
+a higher-level component legitimately surfaces every label, callback and test id
+of the pattern it orchestrates, so a cap that shrinks with tier flags the
+components that are **correctly built** and clears the one that is 3.2× over.
+
+**And for most components the number does not exist.** Between **45 % and 72 %**
+of that library declares no root prop interface at all, depending on how you
+count — `React.ComponentProps<'div'> & VariantProps<cva>` is the dominant idiom.
+A cap over an uncountable quantity is not a lenient rule; it is no rule.
+
+**The tier itself is not computable.** Composition depth, state, sub-component
+count and prop count were each tested as a discriminator between the three
+levels. **Every one overlapped completely, and several inverted.** Sub-component
+count is the tempting replacement and fails the same way: `atoms/combobox`
+exports **16**, more than every molecule (1, 1, 2) and more than one of the two
+organisms. So there is no measurement that could assign the tier a cap would be
+applied to.
+
+**Revisit-if:** a corpus of levelled libraries — plural, and not four days old —
+yields a discriminator that separates the tiers without overlap, at which point
+the caps can be re-derived against it rather than restated. Until then these
+numbers are a conversation starter for a human reviewer, which is the only role
+the evidence supports.
 
 ### 5. Name the slot contract
 

package/dist/agent-src/skills/upstream-contribute/SKILL.md

@@ -9,7 +9,7 @@ scope:
 execution:
   type: assisted
   handler: internal
-  allowed_tools: ["github"]
+  allowed_tools: ["Bash(gh:*)"]
 workspaces:
   - agent-config-maintainer
 packs:
@@ -49,6 +49,43 @@ shared `agent-config` package — with correct file placement, quality gates, an
 - **Quality verified** — must pass linter before PR creation
 - **Local benefit immediately** — use override for instant project benefit while PR is pending
 
+## A repeated override is a signal, and a signal is not evidence
+
+```
+THE SAME ARTIFACT OVERRIDDEN IN INDEPENDENT INSTALLS IS THE CHEAPEST AVAILABLE
+HINT THAT A SHIPPED DEFAULT IS WRONG. IT IS A HINT.
+NEVER CHANGE A SHIPPED DEFAULT ON OVERRIDES FROM ONE ORGANISATION.
+INDEPENDENT MEANS DIFFERENT TEAMS, NOT DIFFERENT DIRECTORIES.
+```
+
+`agent-config doctor --check override-set` reports which shipped artifacts a
+tree overrides and in how many layers. Two same-culture installs overriding the
+same artifact is **n=2 from one toolchain culture**, which is a discovery
+channel and not a mandate — and the temptation to "just fix the default, we
+already know" is exactly how a general package becomes one organisation's house
+style.
+
+**What makes an aggregate admissible**, matching the *Evidence-based* and
+*Universality first* principles above:
+
+- overrides from **independently operated** consumers, not several repositories
+  of one team;
+- the overriding change **converging on the same substance**, not merely
+  touching the same filename — two teams deleting different halves of a rule
+  are not agreeing about anything;
+- a **named public mechanism** that explains why the shipped default is wrong,
+  rather than "several people changed it".
+
+Below that bar, the signal is one input to a future aggregate and nothing more.
+Record it and leave the default alone.
+
+**The signal carries no consumer content, by construction.** Artifact kind, name
+and a layer count — the type has no field that can hold a path, a diff or
+anything from the tree, so privacy is the schema's shape rather than a scrubbing
+pass that could fail. Never widen it to make a proposal more persuasive; a
+proposal that needs the consumer's diff is a proposal that has not cleared the
+bar.
+
 ## Package repository
 
 The shared agent-config package lives at:

package/dist/agent-src/skills/verify-repair-loop/SKILL.md

@@ -15,7 +15,8 @@ packs:
 > **executed verdict** — the project's real test/quality output, scored against a
 > numeric threshold — escalated to a **judge** for qualitative confirmation only
 > *after* the numeric gate passes (staged escalation). The loop is the
-> conversation, not a process: no daemon, no persistent cross-session state. Use
+> conversation, not a process: this loop introduces no resident process of its
+> own and no persistent cross-session state. Use
 > it to drive a change to green when the verdict source is *runtime execution*,
 > not a judge reading a diff.
 
@@ -126,7 +127,7 @@ iterating against a stale contract.
 
 State lives in the conversation, optionally mirrored to a re-read working file —
 **never** a daemon or persistent cross-session store (honors
-[`no-runtime-boundary`](../../../docs/contracts/no-runtime-boundary.md)).
+[`resident-process-governance`](../../../docs/contracts/resident-process-governance.md)).
 
 ## Validation
 
@@ -137,7 +138,11 @@ Before finalizing, confirm:
 3. The loop stopped at `max_attempts`, a plateau, or a judge `apply` — never
    ran unbounded.
 4. The judge saw only the diff + results, dispatched in fresh context.
-5. No daemon / persistent runtime introduced.
+5. No **unsupervised** resident process introduced — and none of the four
+   governance conditions in `resident-process-governance.md` left unmet if a
+   supervised one is. (Amended 2026-08-27, ADR-249: this read "No daemon /
+   persistent runtime introduced" when a daemon was prohibited outright. The
+   check still fires; what it tests moved from existence to governance.)
 
 ## Output format
 
@@ -211,7 +216,7 @@ iter2 fixes A, breaks B, 92% → "PASS"      ✗ regression ignored
 * [`playwright-testing`](../playwright-testing/SKILL.md),
   [`quality-tools`](../quality-tools/SKILL.md) — verdict sources.
 * [`autonomous-execution`](../../rules/autonomous-execution.md) — the N=3 cap.
-* [`no-runtime-boundary`](../../../docs/contracts/no-runtime-boundary.md) — the
+* [`resident-process-governance`](../../../docs/contracts/resident-process-governance.md) — the
   runtime-free constraint this loop honors.
 * Optional impact pre-step (when a code-graph is present, ADR-124): run
   `agent-config code-graph affected --since <ref>` to scope which symbols a

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.11.0"
+agent_config_version: "14.13.0"
 
 # --- Project identity ---
 project:

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

@@ -78,6 +78,53 @@ that was never a judgement call.
     `horizon_weeks` to a positive integer. Enforced by
     `task lint-roadmap-complexity` (plate-token detection skipped when
     `horizon_weeks > 0`).
+17b. **A carried deferral is annotated, or it blocks archival forever.**
+    `archive_completed_roadmaps` used to refuse any roadmap with
+    `count_deferred > 0` unconditionally. Three of the four council-decidable
+    dispositions in the preservation test — carry to a follow-up, merge into
+    existing work, restore to open — leave the `[~]` glyph in place, so a
+    genuinely UNEXECUTABLE item (one needing elapsed time rather than effort)
+    had no council-reachable path to an archived roadmap. The only glyph that
+    cleared the gate was `[-]`, which is owner-reserved AND pinned to "won't
+    happen at all"; using it for a carried item makes cancellation and transfer
+    indistinguishable to every later reader.
+    Since 2026-08-27 (AI council, 2 seats, convergent) a `[~]` step may carry
+    a machine-readable resolution, inside the step's own block:
+    ```markdown
+    - [~] **4.2 Measure the false-positive rate.**
+          <!-- deferred-resolution: carried-to=road-to-some-followup -->
+    ```
+    `merged-into=<slug>` is the second accepted form, for a merge into
+    pre-existing work rather than a new follow-up. `[-]` stays cancellation-only.
+    **Validation fails closed at every step** — a bare `[~]`, a malformed
+    annotation, a destination that does not exist, a destination in `archive/`
+    or `skipped/`, and (for `carried-to`) a destination with no
+    `parent_roadmap: <source-slug>` back-link each refuse the archive and print
+    which door closed. `merged-into` needs no back-link but the destination must
+    still mention the source slug. An annotation is cheap to write, so it is
+    made expensive to satisfy.
+    Three further doors, each found by an independent review of the first
+    version rather than designed in: the destination may not be the **source
+    itself** (it passes every other check and then dies with it); it may not be
+    a roadmap **this same sweep will archive** (both complete in one run leaves
+    the carried item with no receiver — the loss the annotation exists to
+    prevent, produced by the mechanism); and `merged-into` needs a
+    **structured** link — a `relates:` row or a `parent_roadmap:` line — because
+    a substring match on the source slug is satisfied by a filename, an example
+    or a comment. The back-link slug is regex-escaped: interpolated raw, a slug
+    like `road.parent` matched `roadXparent` and one containing `[` threw and
+    aborted the sweep.
+    **Not checked, and stated rather than implied:** that the destination's copy
+    of the criterion is faithful. Both council seats asked for stable item
+    identity over verbatim text matching, and neither exists today — the
+    back-link plus the source mention is the strongest link the sweep can verify
+    without inventing an identity scheme, and the human reviewing the carry is
+    still the one reading it.
+    Eligibility differs from representation: an item that is merely
+    **unfinished** (needs effort nobody spent) stays `[ ]`. Carrying it would be
+    scope laundering. Only an item that **cannot** be executed now qualifies.
+    Contract: `agents/roadmaps/*` · `src/agent-src/scripts/archive_completed_roadmaps.ts`
+    § `deferralProblems` · `tests/scripts/archive_deferral_resolution.test.ts`.
 17. **Follow-up roadmaps from deferred items carry `parent_roadmap`.**
     When a roadmap closes with `[~]` deferred items, the
     [`roadmap-management`](../skills/roadmap-management/SKILL.md) skill
@@ -193,7 +240,7 @@ that was never a judgement call.
     gap-table ritual. When it fires:
     - **(a) Gap-table before drafting.** Audit each proposed item against
       the existing skill / command / rule surface and keep only verified
-      gaps — `KEEP` (genuine gap) / `FOLD` (into an existing artefact) /
+      gaps — `KEEP` (genuine gap) / `FOLD` (into an existing artifact) /
       `CUT` (already covered). The plan integrates, it does not dump.
     - **(b) `## Provenance` block** — source named by a **neutral
       descriptor** (never the raw competitor / tool name, per
@@ -467,6 +514,46 @@ that was never a judgement call.
     Register: the register ranks *known* risks with mitigations; the
     pre-mortem imagines the *whole plan dead* and reconstructs why.
 
+26. **A consolidating roadmap declares its parent set in `consolidates:`.**
+    When a roadmap claims to fold sibling proposals into one — a "master",
+    a consolidation, a document that supersedes others — it declares every
+    parent as a frontmatter list:
+
+    ```yaml
+    consolidates:
+      - road-to-first-parent.md
+      - road-to-second-parent.md
+    ```
+
+    The field is the *only* spelling a tracked roadmap may use. Five
+    legacy spellings exist in inbox artifacts and are read by
+    `lint_consolidation_lineage` so a legacy folder parses to the same
+    parent set rather than to an empty one — `supersedes_analysis:`, a
+    prose `**Inputs consolidated:**` list, a prose `**Ersetzt als
+    führendes Proposal:**` list, a `Master-Konsolidierung` heading with a
+    table, and a prose supersession sentence. They are **deprecated
+    spellings a reader may still encounter**, never shapes to author.
+
+    Why the field rather than prose: a consolidation presents its content
+    as adjudicated — parents named, conflicts resolved, a kill register
+    for what was rejected. A parent missing from that list is not
+    *killed*, it is *undiscussed*, and nothing in the artifact
+    distinguishes those two states. Measured
+    (`agents/evidence/analysis/consolidation-lineage-census-2026-08-26.md`):
+    four inbox folders carrying a declared consolidation, four with an
+    incomplete lineage.
+
+    An omission is discharged in exactly one of three ways, never by
+    silence: fold the parent in · record a kill ID for it · state that it
+    was read and adds nothing. `/analyze:inbox` carries the obligation at
+    the point the artifacts are produced.
+
+    Reported by `lint_consolidation_lineage` — report-mode, not blocking
+    (council 2026-08-27, 2/2 convergent: the four measured cases come from
+    a high-noise drafting context and do not establish precision on the
+    tracked estate; blocking is earned by tracked-scope evidence, not
+    assumed).
+
 ---
 
 ## Quality Gates (remote CI by default)
@@ -587,8 +674,15 @@ complexity: lightweight
 <!-- ## Provenance — INCLUDE ONLY for source-derived / harvest / capability-adoption
      roadmaps (rule 19). OMIT entirely for internally-originated roadmaps —
      do NOT ship an empty Provenance section.
-- Source: <neutral descriptor> (anonymized per source-confidentiality);
-  link via `src/scripts/_lib/link_crypto.ts decrypt`: ENC1:<token>
+- Source: `agents/tmp.old/<opaque-round-id>/` — an OPAQUE round identifier
+  (`inbox-2026-08-h`, `round-a91f3c`, `S17`), never a speaking directory name.
+  The `source-header` and `tmp-quote` shape classes BLOCK inside `agents/**`, so
+  a speaking value fails CI. Naming rule: `/analyze:inbox` Phase 1.
+- Source class, if it needs saying: <neutral descriptor> (anonymized per
+  source-confidentiality) — describe the KIND, never the identity.
+- Identity: recorded once, encrypted, in the round's intake note; the codename
+  map is `agents/evidence/reports/source-codename-map.md`. Decrypt via
+  `src/scripts/_lib/link_crypto.ts decrypt`: ENC1:<token>
 - Council: <members>, <date>, <depth>; convergence inlined above. -->
 ```