methodology-m 0.3.1

package/bin/m.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+// Copyright (C) 2026 Textology Labs Ltd. All rights reserved.
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+const HELP = `
+  methodology-m — inject and manage Methodology M in your project
+
+  Usage:
+    m init                   Set up M in the current project (root repo)
+    m clone <url> [--ide X]  Clone root + all managed repos into a workspace
+    m clone [--ide X]        (from inside root repo) Clone missing siblings
+    m update [version]       Upgrade M to a new version
+    m diff                   Show changes between installed and available M
+    m version                Show installed, bundled, and latest versions
+    m changelog [version]    Show changelog (optionally for a specific version)
+    m help                   Show this help
+
+  Starting a new M project?   Run "m init" in your root repo.
+  Joining an existing project? Run "m clone <root-repo-url>".
+
+  Options:
+    --ide vscode             IDE workspace format (default: vscode)
+`;
+
+async function main() {
+  switch (command) {
+    case 'init': {
+      const { init } = await import('../src/commands/init.mjs');
+      await init(args);
+      break;
+    }
+    case 'clone': {
+      const { clone } = await import('../src/commands/clone.mjs');
+      await clone(args);
+      break;
+    }
+    case 'update': {
+      const { update } = await import('../src/commands/update.mjs');
+      await update(args);
+      break;
+    }
+    case 'diff': {
+      const { diff } = await import('../src/commands/diff.mjs');
+      await diff(args);
+      break;
+    }
+    case 'version': {
+      const { version } = await import('../src/commands/version.mjs');
+      await version(args);
+      break;
+    }
+    case 'changelog': {
+      const { changelog } = await import('../src/commands/changelog.mjs');
+      await changelog(args);
+      break;
+    }
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(HELP);
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/dist-m/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to Methodology M are documented in this file.
+
+## [0.3.1] — 2026-04-11
+
+### Added
+- **M CLI** (`methodology-m` npm package) — zero-dependency Node.js CLI for distributing M into projects. Commands: `init`, `clone`, `update`, `diff`, `version`, `changelog`.
+- **`m clone`** — clones root repo + all managed repos from `project.yaml` topology, generates IDE workspace file (VS Code by default, configurable via `--ide`).
+- **JSON Schemas** — formal contracts at `.m/schemas/pat.schema.json` (PAT.yaml) and `.m/schemas/project.schema.json` (project.yaml). Agent rule in `m.md` requires validation against schemas before committing generated artefacts.
+- **Backlog prioritisation** — all 41 improvement items tiered by impact (Tier 1: structural integrity, Tier 2: delivery loop, Tier 3: extensibility, Tier 4: polish). TOC added to `docs/improvements-and-ideas.md`.
+- **I-041** improvement item — pessimistic invalidation (push `pending` to all story MRs when any constituent pipeline starts).
+
+### Changed
+- **Agent Skills standard** — all capabilities migrated from `.m/capabilities/<name>.md` to `.m/capabilities/<name>/SKILL.md` per the [agentskills.io](https://agentskills.io) standard. Claude wrappers migrated from one monolithic skill to 8 individual skills in `.claude/skills/<name>/SKILL.md`.
+- **README.md** — rewritten to reflect current state: `.m/` layer, CLI, capabilities, provider model.
+- **`.m/m.md`** — schemas added to Key Files and Directory Structure. "Schemas — Mandatory Validation" section with agent enforcement rule. Removed empty `steering/`, `roles/` from directory listing.
+
+## [0.3.0] — 2026-04-11
+
+### Added
+- **Agent-neutral `.m/` layer** — capabilities, steering, and provider interface extracted from Kiro powers into a canonical, agent-agnostic directory. Any AI agent can execute M capabilities by reading `.m/`.
+- **Provider interface** — formal `scm.*` namespace with 14 function contracts (`create_repo`, `protect_branch`, `create_webhook`, etc.). Provider resolution via `project.yaml` → `.m/providers/<category>/<provider>.md`.
+- **GitLab SCM provider** — reference implementation at `.m/providers/scm/gitlab.md` mapping all `scm.*` functions to GitLab MCP tools with full gotcha documentation.
+- **Claude adapter** — thin wrapper skill (`.claude/skills/m-capabilities/SKILL.md`) and steering (`.claude/steering/m-steering.md`) pointing to canonical `.m/` content.
+- **`decompose-story` Step 4** — auto-compile story PAT into Cypress spec and raise root MR at decomposition time (I-039). Integration gate exists from the moment a story is decomposed.
+- **`scm.create_branch`** and **`scm.create_merge_request`** functions added to provider interface.
+- **Pipeline failure propagation (I-032)** — managed repo webhooks now include `pipeline_events: true`. `detect-trigger-event.sh` handles `pipeline_failure` event type, skipping compose and going straight to failure fan-out.
+- **Completeness failure mode** — integrity gate now checks ALL repos (managed + root) for open story MRs.
+- **I-040** improvement item — topology changes (adding/removing components in a live project).
+
+### Changed
+- **`wire-orchestration` capability** — updated with pipeline events on webhooks, `pipeline_failure` detection, fan-out to all repos including root, and inline `after_script` pattern for validate:integration status reporting.
+- **`report-shadow-status.sh`** — `REPOS` includes root repo alongside managed repos.
+- **`integration-test.sh`** — `REPOS` replaces `MANAGED_REPOS`, includes root repo.
+- **Path convention** — all paths in M documents are relative to repo root (pinned in `.m/m.md`).
+
+### Fixed
+- Root repo MR missing from story integrity gate (I-039 partial).
+- Cypress image pinning (`cypress/included:latest` → `cypress/included:15.13.0`) on MFE repo.
+- `validate:integration` CI pipeline failure caused by `when: on_failure` inside `rules:` block — replaced with inline `after_script` fan-out pattern.
+
+## [0.2.0] — 2026-04-07
+
+Initial M Power capabilities under `.kiro/powers/m-power/`. Workshop reference implementation with GitLab CI orchestration.

package/dist-m/capabilities/bootstrap-root-repo/SKILL.md

@@ -0,0 +1,138 @@
+# bootstrap-root-repo
+
+**Capability:** Create and seed the root repo for an M-type project
+
+## What it does
+
+Creates the root repo on GitLab, seeds it with the project manifest and
+Story Zero. After this step, the root repo is the source of truth — all
+subsequent M Power actions read from and write to it.
+
+On completion, offers to run `generate-pats` to produce story-level PATs
+and commit them to the root repo. PAT generation is delegated to the
+existing `generate-pats` capability — this capability orchestrates the
+sequence but does not reimplement PAT logic.
+
+## Parameters
+
+| Parameter        | Type   | Required | Description                                    |
+|------------------|--------|----------|------------------------------------------------|
+| story-file       | path   | Yes      | Path to Story Zero markdown file               |
+| group-path       | string | No       | GitLab group path (extracted from story if omitted) |
+| project-name     | string | No       | Project name (extracted from story if omitted)  |
+| components       | list   | No       | Component catalogue (extracted from story if omitted) |
+| topology-mode    | string | No       | "distributed" or "monolith-first" (default: distributed) |
+| pat-framework    | string | No       | "cypress" or "playwright" (default: cypress)   |
+| deployment-model | string | No       | "docker-compose", "kubernetes", or "none"      |
+
+Story Zero is the primary input. If the story file contains a `## Project`
+section, the capability extracts project metadata automatically. Explicit
+parameters override extracted values. Anything the capability cannot find
+in the story or in explicit parameters, it asks the user for.
+
+### Expected `## Project` section format
+
+The story file's `## Project` section should contain:
+
+- `Name:` — project name (used for repo naming pattern)
+- `GitLab group:` — full group path where repos will be created
+- `Topology:` — "distributed" or "monolith-first"
+- `CI platform:` — "GitLab CI", "GitHub Actions", or "none"
+- `Story management:` — "local markdown" or "Jira"
+- `PAT framework:` — "Cypress", "Playwright", or "both"
+- `Deployment:` — "Docker Compose", "Kubernetes", or "none"
+- Component list — repo names with roles and types (embedded/referenced)
+
+## Execution
+
+### Step 1 — Extract project metadata
+
+Read the story file. Parse the `## Project` section to extract:
+- Project name (from `Name:` field)
+- GitLab group path (from `GitLab group:` field)
+- Component catalogue (from the repo list)
+
+If any of these are missing from the story and not provided as explicit
+parameters, ask the user.
+
+### Step 2 — Create the root repo
+
+```
+scm.create_repo(
+  name: "<project-name>-root",
+  namespace_id: <resolved-from-group-path>,
+  initialize_readme: false
+)
+```
+
+Do NOT initialise with README — the seed commit in Step 6 includes a
+project-specific README. Initialising with a default README causes a
+conflict when pushing the seed files.
+
+### Step 3 — Generate project.yaml
+
+Build the project manifest from the component catalogue:
+
+- Shell component: embedded, location `./packages/shell`
+- All other components: type based on topology-mode
+  - distributed: referenced, location `<group-path>/<project-name>-<component>`
+  - monolith-first: embedded, location `./packages/<component>`
+- All tags set to `~` (YAML null — nothing released yet)
+
+### Step 4 — Seed Story Zero
+
+Place the story file into the root repo at `jira/<story-id>.md`.
+
+### Step 5 — Create conventional folder structure
+
+Create placeholder structure for the root repo:
+
+- `pats/` — story-level PAT files (empty until generate-pats runs)
+- `stories/` — readiness trackers
+- `packages/shell/` — shell package stub (embedded component)
+- `.m/` — methodology configuration (steering, capabilities)
+
+### Step 6 — Commit and push
+
+Commit all seeded files to the root repo in a single commit:
+
+- `project.yaml`
+- `jira/<story-id>.md`
+- `README.md` (project-specific, not the GitLab boilerplate)
+- Folder structure with `.gitkeep` files
+
+Because the repo was created without `initialize_with_readme`, all files
+can be pushed in one commit with no conflicts.
+
+### Step 7 — Offer PAT generation
+
+Present the user with:
+
+```
+Root repo created and seeded with Story Zero.
+Want me to generate PATs now? (delegates to generate-pats)
+```
+
+If confirmed, run `generate-pats` with:
+- `story-file`: the story file just committed to the root repo
+- Output target: `pats/<story-id>.pat.yaml` in the root repo
+
+The `generate-pats` capability handles the draft/review/confirm cycle.
+On confirmation, the PAT file is committed to the root repo.
+
+### Step 8 — Report
+
+Output the root repo URL and a summary of what was created.
+Note that the next step is `decompose-story`.
+
+## Notes
+
+- The root repo becomes the source of truth the moment it's created
+- This capability orchestrates a sequence but delegates PAT generation
+  to `generate-pats` — each capability stays atomic
+- Managed repos are NOT created here — that happens during
+  `decompose-story` or via a future `scaffold-repo` capability
+- The story file parameter can be a local file path; the capability
+  reads it and commits it to the root repo
+- The user has a decision point between seeding and PAT generation —
+  they can pause, edit the story, or generate PATs later

package/dist-m/capabilities/decompose-story/SKILL.md

@@ -0,0 +1,299 @@
+# decompose-story
+
+**Capability:** Decompose a story into component-scoped sub-tasks
+
+## What it does
+
+Reads a story file, proposes a mapping of story-level PATs to components,
+waits for confirmation, then generates:
+
+- An enriched story file in the workspace with the mapping and sub-task refs
+- One sub-task file per component in the workspace
+
+The source story file is never modified.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `story-file` | path | Yes | Path to the source story markdown file |
+| `pat-file` | path | Yes | Path to the story-level PAT.yaml file (generated by `generate-pats`) |
+| `workspace` | path | No | Output folder for generated artefacts |
+
+## Execution
+
+### Step 1 — Read the story and PATs
+
+Read the story file. Extract:
+- Story ID and title
+- Component list (from the Project section)
+
+Read the PAT file. Extract:
+- Story-level acceptance criteria (the `acceptance` entries)
+
+### Step 2 — Propose PAT mapping
+
+Reason about which PATs (from the pat.yaml `acceptance` entries) each component
+is responsible for, then present the proposed mapping to the user.
+
+**PAT supersession:** If any PAT in the new story declares `replaces` or
+`removes` against an existing PAT from a previous story, include this in
+the mapping presentation:
+
+```
+  <component-name> (sub-task: <story-id>a)
+    - <PAT description>
+    - <PAT description> [replaces TODOM-000/AC-001]
+```
+
+The sub-task file for that component must include the supersession info
+in its acceptance criteria so the CAT compilation step knows which
+existing tests to update or remove.
+
+**Mandatory root repo sub-task:** Every story MUST include a sub-task for the
+root repo, regardless of whether the shell code changes. The root repo owns
+story-level integration tests — the gate that validates the composed system
+satisfies the story's acceptance criteria. Without this sub-task, shadow
+integration has no tests to run and will fail structurally.
+
+The root repo sub-task always includes:
+- Story-level integration tests (`scripts/integration-tests/<story-id>.sh`)
+- Any compose config changes needed for the story (e.g. shared volumes, new services)
+- Readiness tracker updates
+
+Even when the shell component has no feature changes, the root repo sub-task
+exists because the integration tests are the root repo's contribution to
+every story. This is not optional — it is how M ensures that shadow
+integration is a real gate, not a permissive placeholder.
+
+Present the proposed mapping to the user:
+
+```
+Proposed PAT mapping for <story-id>:
+
+  <component-name> (sub-task: <story-id>a)
+    - <PAT description>
+    - <PAT description>
+
+  <component-name> (sub-task: <story-id>b)
+    - <PAT description>
+
+  root (sub-task: <story-id><last-suffix>) [MANDATORY]
+    - Story-level integration tests
+    - Compose config changes (if any)
+    - End-to-end validation of all story PATs
+
+  ...
+
+Confirm, or tell me what to change.
+```
+
+Wait for explicit confirmation before writing any files.
+
+### Step 3 — Generate workspace artefacts
+
+On confirmation, write to the workspace folder:
+
+**Enriched story: `<story-id>.md`**
+
+Copy of the source story with two additions:
+- A `## Component PAT Mapping` section showing which PATs each component owns
+- A `## Sub-Tasks` section listing the generated sub-task IDs and their repos
+
+**Readiness tracker: `<story-id>.readiness.yaml`**
+
+Tracks high-water marks for each component sub-task. All marks start as null.
+This is the artefact that monitors story progress through the Development phase.
+It gets committed to the root repo under `stories/<story-id>.yaml`.
+
+```
+story: <story-id>
+status: pending
+
+components:
+  - name: <component-name>
+    subtask: <story-id><suffix>
+    high-water-mark: null
+  ...
+
+story-pats:
+  - pats/<story-id>.pat.yaml
+```
+
+**Sub-task files: `<story-id>a.md`, `<story-id>b.md`, etc.**
+
+One file per component. Each contains:
+- Sub-task ID, title, component name, repo name
+- Status and parent story reference
+- The component's slice of the PATs as its acceptance criteria
+- A `## PAT Stubs` section with test skeletons (one per PAT, using the
+  project's configured PAT framework)
+
+## Sub-task file format
+
+```
+# <story-id><suffix>: <component-name>
+
+**Type:** Technical Sub-Task
+**Status:** Pending
+**Parent:** <story-id>
+**Component:** <component-name>
+**Repo:** <repo-name>
+
+## Summary
+
+<Brief description of what this component implements for this story.>
+
+## Acceptance Criteria (Repo-Level PATs)
+
+1. <PAT title>
+   - <detail>
+   - <detail>
+
+2. <PAT title> [replaces <old-story-id>/<old-sub-task-id> AC-N]
+   - <detail>
+   - Supersedes: <old-sub-task-id> AC-N (<brief description of what changed>)
+
+...
+
+## PAT Stubs
+
+<Test skeletons — one per PAT, framework determined by project config>
+```
+
+When a PAT declares `replaces` or `removes`, the sub-task file must
+include this in the acceptance criteria section. This tells the
+implementing agent:
+
+- **replaces:** the old test for this AC must be updated or replaced
+  when compiling CATs. The old `.cy.js` or `.spec.js` file should be
+  modified to test the new behaviour, or the old test removed and a
+  new one written.
+- **removes:** the old test should be deleted entirely. The feature
+  it tested no longer exists.
+
+### Step 4 — Compile story PAT and raise root MR
+
+The root repo sub-task is not just documentation — its primary
+deliverables (Cypress spec + integration test script) are mechanically
+derivable from the story PAT. This step produces them and raises the
+root MR so that the integration gate exists from the moment the story
+is decomposed.
+
+#### 4a — Compile story PAT → Cypress spec
+
+Transform the story-level PAT YAML into `pats/<story-id>.cy.js` using
+this mapping:
+
+| PAT step | Cypress command |
+|---|---|
+| `navigate: /path` | `cy.visit('/path')` |
+| `wait: "[data-testid='X']" is visible` | `cy.get('[data-testid="X"]').should('be.visible')` |
+| `wait: "[data-testid='X']" contains "Y"` | `cy.get('[data-testid="X"]').should('contain', 'Y')` |
+| `assert: "[data-testid='X']" is visible` | `cy.get('[data-testid="X"]').should('be.visible')` |
+| `assert: "[data-testid='X']" contains "Y"` | `cy.get('[data-testid="X"]').should('contain', 'Y')` |
+| `assert: "[data-testid='X']" count > N` | `cy.get('[data-testid="X"]').should('have.length.greaterThan', N)` |
+| `assert: "[data-testid='X']" is disabled` | `cy.get('[data-testid="X"]').should('be.disabled')` |
+| `assert: "[data-testid='X']" contains ""` | `cy.get('[data-testid="X"]').should('have.value', '')` |
+| `click: "[data-testid='X']"` | `cy.get('[data-testid="X"]').click()` |
+| `type: "[data-testid='X']" value "Y"` | `cy.get('[data-testid="X"]').type('Y')` |
+
+Each AC becomes an `it()` block. The `when` field becomes the test
+description. Order ACs so that tests with data dependencies run in
+sequence (e.g. "add a todo" before "list shows todos").
+
+ACs that require mutually exclusive starting states (empty vs populated)
+should be ordered so the empty-state test runs first, then the add
+action, then the populated-state test — building state as they go.
+
+#### 4b — Create branch and commit
+
+```
+scm.create_branch(repo: <root-repo>, branch: "feat/<story-id>d-integration-gate", ref: "main")
+scm.push_files(repo: <root-repo>, branch: "feat/<story-id>d-integration-gate", files: [
+  { path: "pats/<story-id>.cy.js", content: <compiled-cypress-spec> }
+], commit_message: "✅ compile story PAT into Cypress spec for <story-id>")
+```
+
+#### 4c — Raise root MR
+
+```
+scm.create_merge_request(
+  repo: <root-repo>,
+  source_branch: "feat/<story-id>d-integration-gate",
+  target_branch: "main",
+  title: "<story-id>d: Story-level integration tests"
+)
+```
+
+The root MR exists from the moment the story is decomposed. Shadow
+integration will see it in the completeness check. The Cypress tests
+will fail until all components implement their parts — this is correct
+behaviour. The gate is red until the story is genuinely complete.
+
+## Root repo sub-task format
+
+The root repo sub-task has a distinct structure because its primary
+deliverable is integration tests, not feature code:
+
+```
+# <story-id><suffix>: root — Story-level integration
+
+**Type:** Technical Sub-Task
+**Status:** Pending
+**Parent:** <story-id>
+**Component:** root
+**Repo:** <root-repo-name>
+
+## Summary
+
+Story-level integration validation for <story-id>. Provides the
+integration tests that gate shadow integration — no managed repo MR
+can merge until these tests pass against the composed system.
+
+## Deliverables
+
+1. Cypress spec: `pats/<story-id>.cy.js`
+   - Compiled from story PAT — auto-generated during decomposition
+   - Full browser-based acceptance tests against composed system
+   - Committed to root repo MR at decomposition time
+
+2. Integration test script: `scripts/integration-tests/<story-id>.sh`
+   - Curl-based checks against the composed system
+   - Lightweight CI smoke test (runs without a browser)
+   - Runs automatically during shadow integration
+
+3. Compose config changes (if needed)
+   - Shared volumes, new services, environment variables
+   - Updates to docker-compose.yml
+
+## Integration Test Contract
+
+The integration test script must:
+- Exit 0 if all story-level checks pass
+- Exit non-zero if any check fails
+- Output clear descriptions of what passed and what failed
+- Be runnable from the shadow:integration CI job (curl-based, no browser)
+```
+
+## Notes
+
+- Sub-task IDs use alphabetic suffix: a, b, c, d (up to 26 components)
+- The root repo sub-task is always the LAST suffix (e.g. if 3 managed
+  components get a/b/c, root gets d). This is convention, not a hard rule.
+- PAT stubs are skeletons only — implementation happens in the repo
+- The enriched story in the workspace is the source of truth for subsequent
+  scaffolding steps
+- The readiness tracker is committed to the root repo under `stories/` — it
+  is the mechanism that tracks story progress through the Development phase.
+  Without it, there is no completeness gate for the merge transaction.
+- Run `m-power scaffold-repo` against each sub-task file to create the repo
+- The root repo sub-task is MANDATORY for every story. Shadow integration
+  will fail structurally (not logically) if no integration tests exist for
+  an in-flight story. This is by design — it forces the team to define
+  "done" before implementation begins.
+- Two failure modes in shadow integration:
+  - **Structural failure:** story has open MRs but no integration test
+    script exists at `scripts/integration-tests/<story-id>.sh`
+  - **Logical failure:** integration tests exist but fail because not
+    all components have implemented their part yet