@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "20.6.0",
+  "version": "20.8.0",
   "description": "6-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
@@ -55,7 +55,7 @@
     "codex-cli"
   ],
   "author": "Mert Erden",
-  "license": "MIT AND LicenseRef-PolyForm-Perimeter-1.0.0",
+  "license": "MIT",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/pipeline/multi-agent-refs/features/design-conformance.md

@@ -12,14 +12,12 @@
 <!-- /toc -->
 
 A design audit that reads a screen top to bottom and reports what looks wrong
-finds about one defect per element: the wrong font on a label, and not that same
-label's wrong colour and wrong inset. This file is the catalog, and the three
+catches roughly a single defect per element: it spots a label's wrong font and
+misses the wrong colour and wrong inset on that very label. This file is the catalog, and the three
 mechanisms that turn "I looked at it" into a countable result.
 
-Derived generically from an upstream corporate screen-QA tool (recorded in
-`derivedSkillSources`). The doctrine is portable. Its vendored design-token
-catalogs and product examples are not, and were not taken - section 7 says what
-replaces them.
+The doctrine is generic. It carries no design-token catalog and no product
+examples - section 7 says what stands in for them.
 
 Consumers: `/multi-agent:design-check` (the runner), Phase 3 review when a UI
 diff is under review, and `features/visual-evidence.md` when a capture has to
@@ -27,10 +25,9 @@ prove a fix. Gate: `smoke-design-conformance.sh`.
 
 ## 0. Why this runs as a gate
 
-`design-check` existed as a command for a while with no phase invoking it, so the only
-thing standing between a build and visual drift was the user opening the app and
-looking. On one run that produced 16pt padding where the frame said `Spacing/12`, and a
-full sheet rebuild afterwards.
+A conformance check that no phase invokes leaves the user opening the app as the
+only barrier between a build and visual drift: 16pt padding where the frame says
+`Spacing/12` ships, and is found after the fact.
 
 The reason it cannot be advice is structural, not historical: a reviewer reading a diff
 cannot see spacing. Every other Phase 4 check reads text and reasons about text; this
@@ -49,8 +46,8 @@ once, before any comparison:
    into its parent.
 2. For each row, pre-fill the design side of every rule that applies and leave
    the implementation side blank.
-3. Fill every blank. **A blank cell is a fail-to-verify, not a pass**, and it is
-   reported as one.
+3. Complete every empty cell. **Any blank cell is a fail-to-verify** (never a pass),
+   and the report lists it that way.
 
 The inventory is the coverage guarantee; the rule groups in section 5 are the
 per-cell recipe. A truncated inventory makes the denominator wrong, so it is
@@ -74,15 +71,15 @@ and safe-area insets are not in it.
 ## 3. Adaptive per-component convergence
 
 One pass over a component catches roughly one defect on it. So each component is
-re-checked until **two consecutive attempts find nothing new on it**.
+checked again and again, stopping once **two consecutive attempts find nothing new** there.
 
-- Soft cap: reaching attempt 8 without two consecutive clean attempts stops that
-  component with a `did-not-converge` warning. There is never a ninth attempt.
+- Soft cap: if attempt 8 arrives and the last two attempts were not both clean, the
+  component ends with a `did-not-converge` warning. A ninth attempt never runs.
 - A component with a font, a margin and a colour defect needs about three
   finding attempts plus two clean ones. A correct component needs the two clean
   attempts and nothing more.
-- The screen is done when **every** inventoried component has reached two
-  consecutive clean attempts or its cap with a warning. Not when the walk
+- The screen is finished once **each** component in the inventory has either two
+  clean attempts in a row or has hit its cap and carries the warning. Not when the walk
   reached the bottom.
 
 On a fixing run, each attempt that found something is fixed, re-captured, and
@@ -94,37 +91,37 @@ what each attempt changed rather than one undifferentiated diff.
 | Tag | Meaning |
 |---|---|
 | `[MEASURE]` | Verified in the primary capture: design value against measured pixels or resolved code value (section 2) |
-| `[CAPTURE+]` | Needs an extra capture pass - a second appearance, a mirrored layout, another width, another state. Skipping one is allowed only if the skip is logged |
+| `[CAPTURE+]` | Requires one more capture - a second appearance, a mirrored layout, a different width or state. A pass may be skipped, provided the log records the skip |
 | `[A11Y]` | Accessibility lane: the platform accessibility tree (labels, element frames) plus contrast math |
-| `[DYNAMIC]` | Behavioural or temporal; a static capture cannot show it. Verify by driving the device, or report `not verified (dynamic)`. **Never silently pass a `[DYNAMIC]` item** |
+| `[DYNAMIC]` | Behavioural or temporal; a static capture cannot show it. Drive the device to verify it, or report `not verified (dynamic)`. **Never silently pass a `[DYNAMIC]` item**; it is either exercised or reported |
 
 ## 5. The catalog
 
 Run every applicable item for **every** component, then every gap through
-group 2, then the whole-screen passes (17, 21, 22, 24, 25). A check that was not
-run is a fail-to-verify.
+group 2, then the whole-screen passes (17, 21, 22, 24, 25). Any check left unrun
+counts as a fail-to-verify.
 
-**1. Layout** `[MEASURE]` - x relative to container (never absolute y: the status
-bar offsets it), y relative to an in-content span, L/R/T/B margin to parent,
+**1. Layout** `[MEASURE]` - x measured from the container (y is never taken as an
+absolute value, since the status bar shifts it), y relative to an in-content span, L/R/T/B margin to parent,
 centring, baseline alignment across a row, shared leading edge for siblings,
 label-left/value-right rows aligned at both ends, safe-area and system-bar
 clearance.
 
 > **Horizontal-inset lane** - the most-skipped one. For every element record
 > **both** sides of the leading inset: the design value and the measured
-> implementation value. One side filled is a fail-to-verify. Then two cheap
-> catches that need no per-element math: (a) **leading rail** - every loose,
-> non-carded text in a vertical group must share one leading x; if the
-> implementation puts a subtitle at the card's outer edge while the design insets
-> it, the rail is broken; (b) **sibling consistency** - when sibling screens
-> exist, diff the same element's inset across them; the outlier is usually the
-> bug. A different text-wrap point is a symptom of a different margin, not only
-> of a different font.
+> implementation value. If only one of the two is filled, that is a fail-to-verify.
+> Two inexpensive checks follow that require no per-element arithmetic:
+> (a) **leading rail** - loose text outside any card, stacked vertically, lines up
+> on a single leading x; a subtitle the implementation places on the card's outer
+> edge, where the design indents it, breaks the rail; (b) **sibling consistency** -
+> if the screen has siblings, compare the inset of one element across all of them;
+> the one that differs is usually the defect. Text that wraps at another point
+> often signals a changed margin, and not only a changed font.
 
 **2. Spacing** `[MEASURE]` - outer margins, inner padding, screen edge margin
 (L=R symmetric), text-to-icon and icon-to-button and card-to-card and
 section-to-section gaps, list/grid/row spacing, the vertical gap **between**
-adjacent components (`next.y - (prev.y + prev.h)` against the stack spacing), and
+neighbouring components (compute `next.y - (prev.y + prev.h)` and compare it with the stack spacing), and
 every gap resolving to a spacing token - an off-scale value is a deviation.
 
 **3. Size** `[MEASURE]` - width and height against the design (measured), min and
@@ -166,23 +163,23 @@ single-tint template is a defect), and vector crispness.
 
 **11. Buttons** `[MEASURE]` - width and **measured height** (from the rendered
 fill rect, never a frame token), L/R/T/B spacing with L=R symmetry, the inner
-label's font/weight/colour/alignment **as its own row**, the inner icon
+label as a **separate row** (font, weight, colour, alignment), the inner icon
 (presence, size, colour, side, spacing), centring, fill and border and text
 colour for the current state, `[CAPTURE+]` the state set (group 21).
 
 > A button instance matches no text, icon or field kind, so an inventory built by
 > kind drops it silently - and with it the button height and its nested label.
-> The button is its own row and its children are exploded into their own rows.
+> So each button gets a row, and each child inside it gets a row of its own too.
 
 **12. Input fields** `[MEASURE]` - **measured height** (the rendered field box,
 never a frame or size token, because internal padding is not in the token),
 width, border, radius, placeholder text and its colour and alignment, background
-shade (read-only vs editable), prefix or affix and its colour, cursor and
+shade (editable vs read-only), the prefix or affix with its colour, cursor and
 selection colour, character counter behaviour, `[CAPTURE+]` focus/error/disabled/
 filled states with the error message's colour, position and icon, `[DYNAMIC]`
 keyboard type.
 
-**13. Card** `[MEASURE]` - padding, radius, background, border, shadow, and
+**13. Card** `[MEASURE]` - radius, padding, border, background, shadow, and
 content grouping: **sample the pixel behind every text block** - is it inside a
 card or bare on the page background? A design block in a card that the
 implementation renders bare (or the reverse) is a wrong-container finding
@@ -192,7 +189,7 @@ side is code-verifiable (inside a card helper vs placed bare in a stack with
 padding). Never infer this from a glance.
 
 **14. Lists** `[MEASURE]` - item height and internal padding, divider colour and
-thickness and insets, inter-item spacing, section header grouping and order,
+thickness and insets, spacing between items, how section headers group and order,
 `[DYNAMIC]` scroll behaviour and lazy loading.
 
 **15. Navigation / header** `[MEASURE]` - bar height, title text and alignment,
@@ -200,8 +197,8 @@ back affordance present and correct and mirrored under RTL, right-side actions
 present and ordered, bottom navigation items with icons, labels and selected
 state, `[DYNAMIC]` transition style.
 
-**16. Scroll** - `[DYNAMIC]` smooth scroll, bounce, overscroll, sticky header,
-scroll indicator; `[MEASURE]` the pinned header or footer position, which is the
+**16. Scroll** - `[DYNAMIC]` scroll smoothness, bounce and overscroll, a sticky
+header, the scroll indicator; `[MEASURE]` the pinned header or footer position, which is the
 static part a capture can check.
 
 **17. Responsive** `[CAPTURE+]` - small, medium and large phone widths, tablet,
@@ -214,23 +211,23 @@ width rather than reasoning about it.
 fade/scale/slide/rotation, loading and skeleton animation, haptics. Verify by
 recording the device or report `not verified (dynamic)`.
 
-**20. Visibility** `[CAPTURE+]` - hidden vs visible renders correctly; collapse
-and expand states captured separately.
+**20. Visibility** `[CAPTURE+]` - both the visible and the hidden variant render as
+designed; the expanded and collapsed states each get their own capture.
 
 **21. States** `[CAPTURE+]` per interactive component - default, pressed, focus,
 selected, active, disabled (colour, opacity, and genuinely not tappable),
 loading, empty, error, success.
 
-> **State fidelity gate**: the captured implementation must be in the exact state
-> the design frame depicts - the same toggle position, the same filled or empty
+> **State fidelity gate**: before comparing, put the implementation into precisely
+> the state shown by the design frame - the same toggle position, the same filled or empty
 > content, the same validation result. A capture in the wrong state is redone,
 > not compared.
 
 **22. Accessibility** `[A11Y]` - contrast at least 4.5:1 computed from sampled
 colours, tap target at least 44x44pt / 48x48dp from the accessibility tree,
 screen-reader label present and meaningful plus a meaningful hint, correct
-traits, an accessibility identifier on every interactive element, and a logical
-focus order. Whether to also audit scaled text sizes depends on the project: a
+traits, an accessibility identifier on each element a user can interact with, and
+a logical focus order. Whether to also audit scaled text sizes depends on the project: a
 design system with fixed, non-scaling typography makes a forced-scale render
 meaningless noise, so state which of the two the project is instead of assuming.
 
@@ -258,31 +255,31 @@ overflow. The value itself (a name, a number, a masked field) is not under test.
 **27. Component presence and order  -  hard gate** - the group the whole walk
 exists for.
 
-> Mechanical, not a glance. Number every element of the design list - text **and**
-> every icon, avatar, badge, **and every button** - and for each write its
-> implementation counterpart or `MISSING`. Report the count explicitly: "N design
-> components -> N implementation counterparts". "Complete" may not be concluded
+> Done mechanically, never by eye. Give a number to each element in the design
+> list - the text **and** each icon, avatar and badge, **and each button** - and
+> beside it name the matching implementation element, or write `MISSING`. State
+> the totals outright: "N design components -> N implementation counterparts". "Complete" may not be concluded
 > without that list. A button and the label nested inside it are two presence
 > checks, not one.
 >
-> - **Icons are the most-missed presence class.** For every icon in the design
->   list, locate it in the render by measuring its coloured bounding box. A design
+> - **Presence checks miss icons more than anything else.** Find each design-list
+>   icon in the render by measuring the bounding box of its coloured pixels. A design
 >   icon with roughly no matching pixels is a missing-element finding.
-> - **Recurse into nested blocks.** The gate applies to rows inside cards - masked
->   rows, list rows, key/value rows - not only to top-level sections. "That card
->   looks right" is not a pass.
+> - **Descend into nested blocks.** Rows within cards (masked, list, key/value)
+>   fall under the gate just as top-level sections do. A card that "seems fine"
+>   has not passed.
 > - **Bidirectional, and code-side too.** Diff design-to-implementation
 >   (`MISSING`) *and* implementation-to-design (`EXTRA`). The most-missed extra is
 >   a neutral decoration the implementation adds - a trailing chevron, an
 >   underline, a strikethrough - which a colour-based, one-directional comparison
 >   cannot see. Diff the implementation's explicit decoration modifiers against
 >   the design's own decoration nodes, independently of the string.
-> - **A localization gap does not short-circuit this gate.** Raw keys are one
+> - **Missing localization never ends this gate early.** Raw keys form a single
 >   finding; presence, icon, decoration and structure checks still run, because
 >   they read code and spec rather than the rendered string.
 
-Findings: `MISSING` · `EXTRA` · `MISSING-BETWEEN` (dropped from the middle of the
-sequence) · `REORDERED` · `WRONG-STATE` · `WRONG-CONTAINER` (present but grouped
+Findings: `MISSING` · `EXTRA` · `MISSING-BETWEEN` (absent from inside the sequence,
+not at its ends) · `REORDERED` · `WRONG-STATE` · `WRONG-CONTAINER` (present but grouped
 differently, loose vs carded).
 
 **28. Keyboard and input behaviour** `[DYNAMIC]` - keyboard avoidance with the
@@ -291,17 +288,18 @@ correct field.
 
 **29. Analytics** - out of visual scope; checked only when the spec requires it.
 
-**30. Cross-check matrix** - per component confirm x, y, w, h, the four margins,
-the four paddings, font family/size/weight, line height, letter spacing, text
-colour, background colour, border width/radius/colour, shadow, opacity, icon
-size/colour/position, image size/crop, divider, alignment, responsive, state,
+**30. Cross-check matrix** - for each component confirm x, y, w and h, all four
+margins and all four paddings, the font's family, size and weight, letter spacing,
+line height, text colour, background colour, the border's width, radius and
+colour, shadow, opacity, icon size, colour and position, image crop and size,
+divider, alignment, responsive behaviour, state,
 animation, safe area, and overflow. **Mark only deviations** on the image;
 matches belong in the report text.
 
 ## 6. Output
 
-Mark only problems on the image, with thin lines. Everything else goes in the
-report, whose section keys are stable and whose prose follows `outputLanguage`:
+Draw thin lines on the image around problems and nothing else. All other
+content belongs in the report, whose section keys are stable and whose prose follows `outputLanguage`:
 
 | Key | Content |
 |---|---|
@@ -309,7 +307,7 @@ report, whose section keys are stable and whose prose follows `outputLanguage`:
 | `localization` | Raw keys, missing keys, hardcoded strings |
 | `matches` | What was checked and agreed |
 | `ignored` | What was deliberately out of scope, with the reason |
-| `not_verified` | **Every** `[DYNAMIC]` and `[CAPTURE+]` item that was not run, so the coverage gap is explicit rather than absent |
+| `not_verified` | **Every** `[DYNAMIC]` and `[CAPTURE+]` item left unrun, which makes the coverage gap visible instead of silent |
 
 Each finding is `[what] + [why] + [how]` with `file:line` wherever the
 implementation side is code-resolvable. A finding without a file reference is

package/pipeline/scripts/_notices.mjs

@@ -2,7 +2,7 @@
 //
 // A vendored skill carries `metadata.source: "<upstream> (<license>)"` in its
 // frontmatter, and its upstream's NOTICE-*.md lists it in a `## Skills (N)`
-// section. The licenses involved (MIT, Apache 2.0, PolyForm Perimeter) require
+// section. The licenses involved (MIT, Apache 2.0) require
 // the notice to travel with every copy, and build-stack-plugins.mjs ships a
 // NOTICE only beside the skills that section lists, so the two records are
 // checked against each other here: lint-skills fails on a mismatch and the
@@ -158,3 +158,14 @@ export function unnamedUpstreams(externalDir) {
   }
   return out;
 }
+
+/**
+ * Skills under shared/external with no `metadata.source`. Every skill that ships
+ * into a stack plugin states where it came from: `multi-agent-pipeline` when it
+ * was written here, `"<upstream> (<license>)"` when it is vendored.
+ */
+export function sourcelessSkills(externalDir) {
+  return skillDirs(externalDir).filter(
+    (s) => !metadataSource(readFileSync(join(externalDir, s, "SKILL.md"), "utf8")),
+  );
+}

package/pipeline/scripts/gen-skills-index.mjs

@@ -81,7 +81,7 @@ md += `Single source of truth for skills delivered to both Claude Code (\`~/.cla
 md += `**Total:** ${total} skills (${breakdown}). Auto-generated by \`scripts/gen-skills-index.mjs\`  -  do not edit by hand.\n\n`;
 md += `## Directory layout\n\n`;
 md += `- **\`core/\`**  -  ${counts.core} \`multi-agent*\` orchestration skills that are pipeline-critical. Edits here are core-code changes.\n`;
-md += `- **\`external/\`**  -  ${counts.external} iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.\n`;
+md += `- **\`external/\`**  -  ${counts.external} iOS / Android / generic skills that ship into the stack plugins. Each names its origin in \`metadata.source\`: \`multi-agent-pipeline\` when written here, or the upstream and license a \`NOTICE-*.md\` in this directory covers.\n`;
 md += `- Install destinations (ADR-0009): Claude Code gets NO local copy of \`external/\` - it loads those skills from the \`multi-agent-plugins\` marketplace, namespaced (\`ai-<stack>-toolkit:<name>\`); only the two compliance catalogs from \`core/\` land in \`~/.claude/skills/\`. Copilot CLI and Codex CLI receive a flat copy filtered to the enabled stacks. \`external/\` remains the single authoring source that \`build-stack-plugins.mjs\` publishes from.\n\n`;
 md += `Source layout is logical grouping only  -  skill discovery at runtime is unchanged.\n\n`;
 md += `## Categories\n\n`;