@mmerterden/multi-agent-pipeline 14.2.2 → 15.0.0

package/pipeline/skills/shared/external/ios-module-structure/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ios-module-structure
+description: "The ios-module-structure rule registry: stable-ID rules over where a declaration lives, what its file is called and what its folder must contain beside it, plus a checker that runs them against one module. Use when auditing or refactoring a module's tree, or when a review wants a rule ID rather than a preference about layout."
+user-invocable: true
+standards-registry: references/rules.yml
+---
+
+# Module structure
+
+The registry is `references/rules.yml`. Sibling to the coding-standard registry: that one governs
+what is inside a file, this one governs the tree - which folder a declaration lives in, what its
+file is called, and what has to sit beside it.
+
+| File | What it is | When to read it |
+|---|---|---|
+| `references/rules.yml` | the rules, with stable IDs, severity, enforcement kind and the predicate each one runs | before asserting that a layout is or is not a violation |
+| `scripts/check_structure.py` | the checker: resolves the module's bindings, runs the predicates, reports by ID | every audit; never eyeball a tree you can measure |
+| `modules/<Module>.yml` | per-module overlay: role bindings, dialect choices, vocabulary, carve-outs. **Project-local, never shipped** - it lives in the installed copy, never in the authoring source | before auditing a module, and before raising any slot-bound rule |
+| `modules/_TEMPLATE.yml` | the overlay's shape and the evidence each binding wants | when onboarding a module |
+
+**Maturity: 0.x, iOS/Swift only.** The registry declares `scope.languages`, and the checker
+refuses a module that holds none of that language rather than reporting a clean run. A second
+language would be a second rules file passed to `--rules`, not a change to the checker.
+
+## The one idea
+
+A rule here never names a path or a type. It names a **role**, and the module's overlay binds that
+role to its own spelling. `STRUCT-07` does not say "a file under Subviews/ needs a Configuration
+beside it"; it says every file playing `subview.view` has the `subview.configuration` file beside
+it. A module that spells those two differently rebinds; a module that has no such shape leaves the
+role empty and the rule switches off.
+
+That is what lets one registry serve two modules whose trees share almost nothing, without either
+becoming a hundred findings.
+
+## How to use it
+
+1. **Cite, do not paraphrase.** Reference `STRUCT-04`, `VOCAB-01`. A finding without an ID is a
+   preference about folders, and the author cannot look it up to disagree.
+2. **A rule not in the registry is not a rule.** If an audit wants one, propose it as
+   `status: proposed` with a rationale rather than enforcing it silently.
+3. **An unbound slot or role DISABLES its rules, and the run reports that.** Never read a clean run
+   without reading its `DISABLED` block - that block is the coverage you did not have.
+4. **Severity decides whether it blocks.** `blocking` stops the change, `important` is fixed in the
+   same pass, `suggestion` is optional.
+5. **Exceptions are marked in code, with an expiry:**
+   `// standard:exception(<RULE-ID>) <reason> <expiry:YYYY-MM-DD>`. An unmarked deviation is a
+   finding; a marked one is a decision.
+6. **When a finding looks wrong, fix the overlay before the code.** A rule firing on a whole module
+   is almost always a dialect the overlay has not declared. Changing the code to satisfy a
+   mis-bound rule is the expensive mistake this registry exists to prevent.
+
+## Running it
+
+```bash
+python3 "$HOME/.claude/skills/ios-module-structure/scripts/check_structure.py" \
+  --rules   "$HOME/.claude/skills/ios-module-structure/references/rules.yml" \
+  --overlay "$HOME/.claude/skills/ios-module-structure/modules/<Module>.yml" \
+  --root    "<path/to/module>"
+```
+
+`--only <RULE-ID>` runs one rule, `--screen <Name>` one screen, `--format json` gives a machine
+result. Exit is 1 when there is any finding, 0 otherwise; notes and disabled rules never affect it.
+
+Requires PyYAML - the registry and the overlay are YAML.
+
+## Dialect slots, and why a rule becomes one
+
+Some layouts are a choice, not a defect: two shapes are each coherent and the cost is only in
+mixing them. Those rules bind to a slot in `module_overlay_slots` and the overlay picks a value.
+A slot is only legitimate when **both** values are genuinely defensible - a module with no analytics
+surface has not chosen a different dialect, it is missing the surface, so that stays a rule.
+
+The test when you are tempted to add one: can you write the second value's paragraph without it
+reading as an excuse? If not, it is a rule.

package/pipeline/skills/shared/external/ios-module-structure/modules/_TEMPLATE.yml

@@ -0,0 +1,131 @@
+########################################################################
+# Module overlay template.
+#
+# Copy to `modules/<YourModule>.yml` in your own project and fill it in from EVIDENCE IN YOUR OWN
+# CODE. A real overlay is never shipped with this skill: it quotes module paths, directory
+# spellings and file counts, so it describes one codebase and would bind another codebase's slots
+# to the wrong dialect.
+#
+# The rule that makes this safe: an UNBOUND slot or role DISABLES its rules. Leaving one empty
+# costs you those checks and the run says so. Guessing a value costs you a hundred findings against
+# a module that made the other defensible choice - a migration proposal wearing a structure pass.
+# Empty beats guessed.
+#
+# Every `*_evidence` field wants a COUNT, not a preference. The count is the only thing that
+# distinguishes "this module chose a shape" from "this module has a defect". No count, no binding.
+########################################################################
+
+module: <YourModule>
+path: <Path/To/Module>
+role: feature # feature | common | app
+registry_version: 1.0.0
+updated: <YYYY-MM-DD>
+
+description: >
+  One paragraph: how many targets, which of them carry screens, and what a screen's folders are.
+
+# --- Dialect slots -----------------------------------------------------
+# See `references/rules.yml -> module_overlay_slots` for what each governs and which values are
+# defensible. Bind only what you can evidence.
+dialect:
+  # Does every screen carry the same layer folders, or only the ones it needs?
+  ScreenLayerShape:
+  ScreenLayerShape_evidence: >
+    Count screens against each layer folder, e.g. "N of N carry X; M of N carry Y". A uniform count
+    means `layered`; a spread means `organic` and a missing folder is a fact, not a finding.
+
+  # Where does a service operation's request/response pair live?
+  ServiceModelDir:
+  ServiceModelDir_evidence: >
+    Count directories holding a pair under each candidate parent.
+
+  # Does every operation model both halves, or only the ones with a body?
+  ServiceModelPairing:
+  ServiceModelPairing_evidence: >
+    Count request models against response models. Close counts mean `both`; a large gap means
+    `response-only`.
+
+  # Does each screen ship its own construction seam, or does one factory build them all?
+  ScreenAssemblyShape:
+  ScreenAssemblyShape_evidence: >
+    Count factory files against screens. One each means per-screen-factory.
+
+  # Does UI state live in its own type, or on the view model?
+  UIStateHolder:
+  UIStateHolder_evidence: >
+    Count separate state types against screens. Zero means view-model-owned.
+
+  # Does an extracted view get a folder and a value type, or sit loose?
+  SubviewShape:
+  SubviewShape_evidence: >
+    Count view+value pairs against loose extracted views.
+
+  # Does the entry file compose its own fragments, or hand them to named views?
+  ScreenCompositionShape:
+  ScreenCompositionShape_evidence: >
+    Count view members on entry files against extracted view files. This one decides whether a
+    long entry file is the module's shape or a pile of un-extracted fragments; get it wrong in
+    either direction and the run is useless.
+
+  # Where is copy resolved?
+  CopyResolution:
+  CopyResolution_evidence: >
+    Count per-screen copy types against screens.
+
+# --- Roles -------------------------------------------------------------
+# Globs are relative to `path`. A role may bind to one glob or to a list of them. Roles other than
+# screen.root are relative to a screen directory.
+#
+# Leave a role empty when the module genuinely has no such thing - the rules that read it are then
+# reported as lost coverage, which is the honest answer.
+roles:
+  screen.root: # e.g. "Sources/*/Screens/*"
+  screen.entry:
+  screen.viewmodel:
+  screen.state:
+  screen.analytics:
+  screen.factory:
+  screen.mapper:
+  service.dir:
+  service.request:
+  service.response:
+  subview.view:
+  subview.configuration:
+  repository.live:
+  repository.mock:
+  shared.root:
+  test.root:
+
+# --- Vocabulary --------------------------------------------------------
+# Names and spellings the rules need in order to generate a check. An unfilled key disables the
+# rules that read it.
+vocabulary:
+  LayerDirs: [] # the folders `layered` expects on every screen
+  PresentationDir: []
+  SubviewViewSuffix:
+  SubviewConfigurationSuffix:
+  BooleanPrefixes: # a regex, e.g. "^(is|has|can|shows)[A-Z]"
+  IndexLabel: # a regex for the accepted parameter label
+  SectionHeadings: [] # the closed set of section headings, if the module declares one
+  BareVerbs: [] # verbs a presentation type may not use alone
+  ForbiddenTypeSuffixes: [] # last words that describe no role
+
+# --- Limits ------------------------------------------------------------
+limits:
+  source_target:
+  source_ceiling:
+  test_target:
+  test_ceiling:
+
+# --- Carve-outs --------------------------------------------------------
+# Declared per rule ID. Each is a decision with a reason, not a way to quiet the tool. A carve-out
+# with no reason is a finding you hid from yourself.
+#
+#   screens:  [Name, ...]   the rule does not describe these screens
+#   paths:    [glob, ...]   the rule does not describe files at these paths
+#   patterns: [regex, ...]  the rule does not describe findings whose detail matches
+exemptions: {}
+#  RULE-ID:
+#    screens: []
+#    reason: >
+#      Why this is a decision rather than a defect.