agentme 0.35.2 → 0.37.0

package/.xdrs/agentme/edrs/operations/403-dora-deployment-frequency.md

@@ -0,0 +1,37 @@
+---
+name: agentme-edr-policy-403-dora-deployment-frequency
+description: Defines calculation, examples, and challenges for DORA's Deployment Frequency metric and its deploys-per-week, batch-size, and automation-ratio sub-metrics. Use when instrumenting or reviewing deployment frequency measurement.
+apply-to: Teams and organizations measuring, reporting, or improving software delivery performance using DORA's four key metrics
+valid-from: 2026-09-18
+---
+
+# agentme-edr-policy-403: DORA deployment frequency
+
+## Context and Problem Statement
+
+Deployment Frequency is the easiest of DORA's four metrics to start measuring, but teams need a concrete, per-service calculation method rather than just the concept. How should deploys-per-week, batch size, and automation ratio be calculated, and in what order should a team adopt them?
+
+## Decision Outcome
+
+**Measure three complementary, non-summing sub-metrics per deployable service, adopted in order of increasing data-source complexity.**
+
+Each sub-metric MUST be scoped per [agentme-edr-402](402-dora-metrics-framework.md)'s `02-per-service-and-team-accounting` and rolled up per team; none of the three sum to a single formula.
+
+### Details
+
+#### 01-deploys-per-week
+
+Deploys-per-week MUST be calculated by counting successful deploy-workflow runs on the service's default or release branch per week, using CODEOWNERS to attribute each run to its service. Example: a service with 12 successful deploy runs over 4 weeks has a Deployment Frequency of 3/week. Challenges: a change touching multiple services MUST be counted independently against each service's own timeline; the measurement window MUST span the service's own release-train or freeze-window cadence rather than a fixed calendar snapshot; "one deploy event" for canary, staged, or multi-region rollouts MUST be defined consistently per service (for example, pipeline-run start); re-run or retry executions of the same release MUST NOT inflate the count. This is the first sub-metric to adopt: it needs only deploy-workflow history as a single data source, and gives the fastest, most direct throughput signal.
+
+#### 02-batch-size
+
+Batch size MUST be calculated by counting commits or PRs merged between two consecutive deploys of the same service. Example: 8 PRs merged between deploy N and deploy N+1 gives a batch size of 8. Challenges: squash-merge collapses commit history, so the count MUST be based on merged PRs rather than raw commits. Teams SHOULD adopt this second: it needs no data source beyond `01`'s deploy history, and is a leading indicator for both Lead Time and Change Failure Rate risk (see [agentme-edr-402](402-dora-metrics-framework.md)'s `07-adoption-order`).
+
+#### 03-automation-ratio
+
+Automation ratio MUST be calculated by dividing automated deploy-workflow runs (triggered by merge, tag, or schedule) by all deploy-workflow runs for the service. Example: 18 automated of 20 total runs gives a 90% automation ratio. Challenges: a mandatory regulatory or manual QA approval gate MUST NOT be conflated with an ad-hoc manual deploy; only the latter counts against automation ratio. Teams SHOULD adopt this third, since it requires classifying trigger type per run and is most useful once volume and batch size are already understood.
+
+## References
+
+- [agentme-edr-402](402-dora-metrics-framework.md) — DORA metrics framework
+- [DORA's software delivery performance metrics](https://dora.dev/guides/dora-metrics-four-keys/)

package/.xdrs/agentme/edrs/operations/404-dora-lead-time-for-changes.md

@@ -0,0 +1,41 @@
+---
+name: agentme-edr-policy-404-dora-lead-time-for-changes
+description: Defines calculation, examples, and challenges for DORA's Lead Time for Changes metric and its PR-cycle-time, review-latency, deploy-pipeline-time, and total-lead-time sub-metrics. Use when instrumenting or reviewing lead time measurement.
+apply-to: Teams and organizations measuring, reporting, or improving software delivery performance using DORA's four key metrics
+valid-from: 2026-09-18
+---
+
+# agentme-edr-policy-404: DORA lead time for changes
+
+## Context and Problem Statement
+
+Lead Time for Changes is often reduced to one number that hides whether delay lives in review or in deployment. How should its phases be calculated so a team can see where time is actually spent, and how do the phases combine into a total?
+
+## Decision Outcome
+
+**Measure four additive sub-metrics per deployable service that sum to a total lead time, using the median (p50) as the headline statistic.**
+
+Review latency is a phase inside PR cycle time; PR cycle time plus deploy-pipeline time MUST equal total lead time.
+
+### Details
+
+#### 01-pr-cycle-time
+
+PR cycle time MUST be measured from a PR's first commit to its `merged_at` timestamp. Example: first commit at day 0, merged at day 2 gives a 2-day PR cycle time. Challenges: squash-merge loses the first-commit timestamp, so the PR's `created_at` SHOULD be used as a proxy; stacked PRs and long-lived branches with rebases distort the start time. Teams SHOULD adopt this first, since it uses a single data source (GitHub PRs) and is usually the dominant contributor to total lead time.
+
+#### 02-review-latency
+
+Review latency MUST be measured from a PR's `created_at` to its first review `submitted_at`, as a drill-down inside `01`. Example: PR opened at hour 0, first review at hour 20, gives 20 hours of review latency. Challenges: this is the sub-metric most at risk of being gamed by rubber-stamping; an unusually fast review latency MUST be read jointly with [agentme-edr-405](405-dora-change-failure-rate.md)'s Change Failure Rate rather than treated as a win on its own. Teams SHOULD adopt this second: it reuses `01`'s data source with one extra timestamp, and is usually the most common, most actionable bottleneck.
+
+#### 03-deploy-pipeline-time
+
+Deploy-pipeline time MUST be measured from merge to deploy completion for the affected service, covering any merge-to-deploy gate whether automated or manual (including mandatory regulatory or QA approval gates). Example: merged at hour 0, service deployed at hour 6, gives 6 hours of deploy-pipeline time. Challenges: a PR shipping to multiple services MUST have this computed once per affected service, since deploy timing differs by service; flaky CI re-runs inflate the measurement. Teams SHOULD adopt this third: it requires a second data source (deploy-workflow runs) correlated with PR data, and isolates exactly how much delay sits outside the team's own review process.
+
+#### 04-total-lead-time
+
+Total lead time MUST equal `01` plus `03` (with `02` already counted inside `01`), computed once per PR-and-affected-service pair and rolled up per team. Example: 2-day PR cycle time plus 6-hour deploy-pipeline time gives a total of roughly 2.25 days. Challenges: a handful of extreme outliers can skew a mean, which is why the median MUST be the headline statistic. Teams SHOULD adopt this last: it requires correlating both data sources together, the hardest sub-metric to compute reliably, but it is the single clearest measure of overall delivery speed.
+
+## References
+
+- [agentme-edr-402](402-dora-metrics-framework.md) — DORA metrics framework
+- [DORA's software delivery performance metrics](https://dora.dev/guides/dora-metrics-four-keys/)

package/.xdrs/agentme/edrs/operations/405-dora-change-failure-rate.md

@@ -0,0 +1,42 @@
+---
+name: agentme-edr-policy-405-dora-change-failure-rate
+description: Defines calculation, examples, and challenges for DORA's Change Failure Rate metric and its hotfix/revert-rate, incident-linked-deploy-rate, and escaped-defect-rate sub-metrics, including cross-team root-cause attribution. Use when instrumenting or reviewing change failure rate measurement.
+apply-to: Teams and organizations measuring, reporting, or improving software delivery performance using DORA's four key metrics
+valid-from: 2026-09-18
+---
+
+# agentme-edr-policy-405: DORA change failure rate
+
+## Context and Problem Statement
+
+Failure shows up in different ways — an immediate rollback, an incident without a rollback, a defect found later — and no single detection method catches all of them. How should each be calculated, and how should a failure whose root cause spans multiple teams be attributed?
+
+## Decision Outcome
+
+**Measure three complementary, non-summing detection signals per deployable service, and attribute cross-team-caused incidents to both the root-cause team and the impacted team.**
+
+The three sub-metrics MUST NOT be summed; a team MAY treat one as primary as it matures, but all three remain independent signals.
+
+### Details
+
+#### 01-hotfix-revert-rate
+
+Hotfix/revert rate MUST be calculated by dividing PRs titled or labeled `revert` merged shortly after a deploy by total deploys for the service, using CODEOWNERS for attribution. Example: 2 reverts following 40 deploys gives a 5% hotfix/revert rate. Challenges: a hotfix that itself gets reverted MUST NOT be double-counted as two separate failures. Teams SHOULD adopt this first, since it catches the most severe, most obvious failures using a single data source.
+
+#### 02-incident-linked-deploy-rate
+
+Incident-linked deploy rate MUST be calculated by dividing GH Issues labeled `incident` that reference a deploy by total deploys for the service, using the issue-label/component convention from [agentme-edr-402](402-dora-metrics-framework.md)'s `03-artifact-to-service-mapping` (CODEOWNERS does not apply to Issues). Example: 3 incident-linked issues following 40 deploys gives 7.5%. Challenges: deploy-to-incident attribution lag, and label-discipline under-reporting when incidents go untagged. Teams SHOULD adopt this second: it reuses `01`'s deploy count with one additional label convention, and catches real failures that did not need a rollback but still affected users.
+
+#### 03-escaped-defect-rate
+
+Escaped defect rate MUST be calculated by dividing GH Issues labeled `bug` and `production`, opened after a release and attributed to the service, by total deploys. Example: 4 escaped defects following 40 deploys gives 10%. Challenges: attribution lag across period boundaries when a defect surfaces well after the causing deploy. Teams SHOULD adopt this third: it reuses the same issue-label convention as `02`, and catches slower-to-surface failures the first two signals miss.
+
+#### 04-cross-team-and-shared-root-cause-attribution
+
+When an incident's root cause is a different team's change, it MUST be counted against the root-cause team's numerator here, per [agentme-edr-402](402-dora-metrics-framework.md)'s `04-cross-team-incident-attribution`; the impacted team MUST instead receive a separate, non-tiered visibility tag rather than a numerator hit. An incident traced to one shared root cause but manifesting across several teams' trackers MUST be linked to a single root-cause record and MUST NOT be counted independently as multiple failures.
+
+## References
+
+- [agentme-edr-402](402-dora-metrics-framework.md) — DORA metrics framework
+- [agentme-bdr-405](../../bdrs/operations/405-digital-product-roles-raci.md) — Digital product roles: RACI (root-cause tracing methodology)
+- [DORA's software delivery performance metrics](https://dora.dev/guides/dora-metrics-four-keys/)

package/.xdrs/agentme/edrs/operations/406-dora-time-to-restore-service.md

@@ -0,0 +1,42 @@
+---
+name: agentme-edr-policy-406-dora-time-to-restore-service
+description: Defines calculation, examples, and challenges for DORA's Time to Restore Service metric and its total-restore-time, detection-time, acknowledgement-time, and resolution-time sub-metrics, using GitHub Issues as the worked example. Use when instrumenting or reviewing incident restore-time measurement.
+apply-to: Teams and organizations measuring, reporting, or improving software delivery performance using DORA's four key metrics
+valid-from: 2026-09-18
+---
+
+# agentme-edr-policy-406: DORA time to restore service
+
+## Context and Problem Statement
+
+Restoring service after a failed deployment is DORA's safety-net metric (DORA's current term is "Failed Deployment Recovery Time"), but a single total-time figure hides whether delay lives in detection, response, or the fix itself. How should the total and its phases be calculated in a tool-agnostic way?
+
+## Decision Outcome
+
+**Measure a total restore time plus three additive phase sub-metrics per impacted service, using any incident-management tool with equivalent timestamps; GitHub Issues is the worked example.**
+
+The total MUST be tracked standalone, and the three phases decompose it, always attributed to the impacted or owning service regardless of where the root cause is traced.
+
+### Details
+
+#### 01-total-restore-time
+
+Total restore time MUST be measured from an incident's opened timestamp to its closed timestamp, attributed via the issue-label/component convention from [agentme-edr-402](402-dora-metrics-framework.md)'s `03-artifact-to-service-mapping` to the service that was down or degraded. Example: opened at 10:00, closed at 11:30, gives 90 minutes. Challenges: partial-vs-full restores and reopened incidents. Teams SHOULD adopt this first: it needs only two timestamps on one incident record, no extra tracked event, and gives an immediate, if coarse, restore-time signal.
+
+#### 02-detection-time
+
+Detection time MUST be measured from the underlying failure's occurrence to the incident's detected timestamp, a tracked event distinct from "opened." Example: failure at 10:00, detected at 10:05, gives 5 minutes. Challenges: without paging or monitoring, detection relies on user reports and is easy to under-track. Teams SHOULD adopt this second: it requires one additional tracked "detected" event, and exposes how much time is lost before anyone notices, a leading indicator for monitoring coverage gaps.
+
+#### 03-acknowledgement-time
+
+Acknowledgement time MUST be measured from detected to acknowledged or assigned. Example: detected at 10:05, acknowledged at 10:10, gives 5 minutes. Challenges: on-call handoff and timezone gaps. Teams SHOULD adopt this third: it requires one additional tracked "acknowledged" event, and exposes on-call responsiveness separately from the fix itself.
+
+#### 04-resolution-time
+
+Resolution time MUST be measured from acknowledged to actually-fixed, not merely issue-closed. Example: acknowledged at 10:10, fixed at 11:30, gives 80 minutes. Challenges: extensive or mandatory manual rollout testing can gate the fix itself, extending this phase. Rules `02`, `03`, and `04` MUST sum to the total measured in `01`. Teams SHOULD adopt this last: it requires a reliable "fixed" event, the hardest to track consistently, but it isolates how long the actual fix takes once someone is engaged.
+
+## References
+
+- [agentme-edr-402](402-dora-metrics-framework.md) — DORA metrics framework
+- [agentme-bdr-405](../../bdrs/operations/405-digital-product-roles-raci.md) — Digital product roles: RACI (incident-response accountability)
+- [DORA's software delivery performance metrics](https://dora.dev/guides/dora-metrics-four-keys/)

package/.xdrs/agentme/edrs/platform/301-monorepo-structure.md

@@ -17,7 +17,7 @@ What monorepo structure, naming conventions, tooling, and build standards should
 
 **Adopt a standardized monorepo layout with top-level application folders that aggregate independent module roots, shared parent-level example and test areas, Mise-managed tooling, and Makefiles at every level.**
 
-For step-by-step scaffolding instructions see [skill 053-monorepo-setup](skills/053-monorepo-setup/SKILL.md).
+For step-by-step scaffolding instructions see [skill monorepo-setup](skills/monorepo-setup/SKILL.md).
 Module folder responsibilities, artifact locations, and test-folder conventions follow [agentme-edr-016](../principles/016-cross-language-module-structure.md).
 
 ### Details

package/.xdrs/agentme/edrs/platform/skills/{053-monorepo-setup → monorepo-setup}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 053-monorepo-setup
+name: monorepo-setup
 description: >
   Step-by-step instructions for setting up and scaffolding a new monorepo following the standard
   layout, naming conventions, Makefiles, Mise tooling, and README requirements defined in
@@ -67,8 +67,8 @@ test:
 	$(foreach app,$(APPS),$(MAKE) -C $(app) test &&) true
 
 clean:
-   $(foreach app,$(APPS),$(MAKE) -C $(app) clean &&) true
-   rm -rf .cache
+	$(foreach app,$(APPS),$(MAKE) -C $(app) clean &&) true
+	rm -rf .cache
 
 setup:
 	@echo "Install Mise: https://mise.jdx.dev/getting-started.html"
@@ -220,16 +220,16 @@ For each module inside an application:
    all: build lint test
 
    build:
-   mise exec -- go build ./...
+   	mise exec -- go build ./...
 
    lint:
-   mise exec -- golangci-lint run ./...
+   	mise exec -- golangci-lint run ./...
 
    test:
-   mise exec -- go test ./... -cover
+   	mise exec -- go test ./... -cover
 
    clean:
-	rm -rf dist .cache
+   	rm -rf dist .cache
    ```
 
    **Node.js / TypeScript:**
@@ -239,16 +239,16 @@ For each module inside an application:
    all: build lint test
 
    build:
-   mise exec -- pnpm exec tsc --project tsconfig.json
+   	mise exec -- pnpm exec tsc --project tsconfig.json
 
    lint:
-   mise exec -- pnpm exec eslint ./src
+   	mise exec -- pnpm exec eslint ./src
 
    test:
-   mise exec -- pnpm exec jest --verbose
+   	mise exec -- pnpm exec jest --verbose
 
    clean:
-	rm -rf dist .cache
+   	rm -rf dist .cache
    ```
 
    **Python:**
@@ -258,16 +258,16 @@ For each module inside an application:
    all: build lint test
 
    build:
-   mise exec -- uv build --project . --out-dir dist
+   	mise exec -- uv build --project . --out-dir dist
 
    lint:
-   mise exec -- uv run --project . ruff check .
+   	mise exec -- uv run --project . ruff check .
 
    test:
-   mise exec -- uv run --project . pytest
+   	mise exec -- uv run --project . pytest
 
    clean:
-	rm -rf dist .cache
+   	rm -rf dist .cache
    ```
 
 4. **Add source files** appropriate to the language, placing them inside the module folder.

package/.xdrs/agentme/edrs/platform/skills/monorepo-setup/SKILL.test.md

@@ -0,0 +1,80 @@
+---
+skill: monorepo-setup
+skill-version: "1.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: Scaffold a two-application monorepo, happy path
+
+**Trigger / Input**
+
+"Set up a new monorepo called `platform-tools` with two applications: `ingest` (Go, one module
+named `collector`) and `dashboard` (Node.js/TypeScript, one module named `web`)."
+
+**Expected Behaviour**
+
+1. Phase 1 gathers or infers applications, modules, primary languages, and tool versions.
+2. Phase 2 creates the root `.mise.toml`, root `Makefile` (delegating `build`/`lint`/`test`/`clean`
+   to every application via `$(MAKE) -C $(app) $@`), root `.gitignore` ignoring `dist/` and
+   `.cache/`, root `README.md` with Overview/Machine setup/Quickstart/Repository map, and root
+   `CONTRIBUTING.md`.
+3. Phase 3 creates the `shared/` area (`libs/`, `scripts/`).
+4. Phase 4 scaffolds `ingest/` and `dashboard/` each with a `README.md` and a `Makefile` that
+   delegates to their modules.
+5. Phase 5 scaffolds `ingest/collector/Makefile` using the Go recipe (`mise exec -- go build
+   ./...`, `golangci-lint run ./...`, `go test ./... -cover`) and `dashboard/web/Makefile` using
+   the Node.js/TypeScript recipe (`mise exec -- pnpm exec tsc`, `eslint`, `jest`).
+6. Phase 6 verifies root `make build`, `make lint`, and `make test` succeed and reports the
+   Phase 6 checklist before finishing.
+
+**Assertions**
+
+- [ ] Output creates a root `Makefile` whose `build`, `lint`, and `test` targets delegate to each
+      application with `$(MAKE) -C $(app) $@`.
+- [ ] Output generates `ingest/collector/Makefile` with Go recipe commands and
+      `dashboard/web/Makefile` with Node.js/TypeScript recipe commands, each matching the
+      language-specific block for that module.
+- [ ] Output reports that root `make build`, `make lint`, and `make test` succeed before declaring
+      the scaffold complete.
+- [ ] Output includes a root `CONTRIBUTING.md` covering bugs, feature discussion, pull requests,
+      Conventional Comments, and small focused changes.
+
+### Scenario 2: Cross-application dependency request is refused
+
+**Trigger / Input**
+
+"Make the `web` module in `dashboard` import a function directly from the `collector` module in
+`ingest`."
+
+**Expected Behaviour**
+
+Per the Edge Cases entry for cross-application dependencies, the skill refuses to wire a direct
+import between two different applications' modules and instead proposes extracting the shared
+code into `shared/libs/` as a published library that both applications can depend on.
+
+**Assertions**
+
+- [ ] Output refuses to create a direct import from `dashboard/web` into `ingest/collector`.
+- [ ] Output proposes moving the shared logic into `shared/libs/` instead of a cross-application
+      import.
+
+### Scenario 3: Existing root Makefile is never silently overwritten
+
+**Trigger / Input**
+
+"Add a new application called `reports` to this monorepo." The repository already has a root
+`Makefile` with custom targets not generated by this skill.
+
+**Expected Behaviour**
+
+Per the Edge Cases entry for existing files, the skill does not overwrite the existing root
+`Makefile` (or `README.md`/`CONTRIBUTING.md`) without explicit user confirmation. It diffs the
+existing file against the standard layout and proposes additions instead.
+
+**Assertions**
+
+- [ ] Output does not overwrite the existing root `Makefile` without first asking for explicit
+      user confirmation.
+- [ ] Output presents a diff or a proposed set of additions rather than replacing the file
+      silently.

package/.xdrs/agentme/edrs/principles/012-continuous-xdr-enrichment.md

@@ -61,4 +61,4 @@ In SDD, specifications describe the feature being built; XDRs describe reusable
 - [_core-adr-001](../../../_core/adrs/principles/001-xdrs-standards.md)
 - [_core-article-001](../../../_core/adrs/principles/articles/001-xdrs-overview.md)
 - [agentme-article-001](articles/001-continuous-xdr-improvement.md)
-- [002-write-policy skill](../../../_core/adrs/principles/skills/002-write-policy/SKILL.md)
+- [write-policy skill](../../../_core/adrs/principles/skills/write-policy/SKILL.md)

package/.xdrs/agentme/edrs/principles/017-skill-testing.md

@@ -2,7 +2,7 @@
 name: agentme-edr-policy-017-skill-testing
 description: >
   Mandates a SKILL.test.md test file co-located with every skill, defines the test file format (scenarios with trigger, expected behaviour, and assertions), and requires execution before merging any change to the skill. Use when creating, updating, or reviewing skills.
-apply-to: contributors working in any scope that directly or transitively follows or extends agentme
+apply-to: the agentme scope itself, and any scope that directly or transitively follows or extends agentme
 valid-from: 2026-08-06
 ---
 
@@ -16,7 +16,7 @@ How should skill correctness be verified after every change, in a way that is co
 
 ## Decision Outcome
 
-**Every skill MUST have a `SKILL.test.md` file in the same directory as its `SKILL.md`. The file defines test scenarios with explicit input triggers and falsifiable assertions. It MUST be executed — using the `200-run-skill-tests` skill or manually — before merging any PR that modifies the skill or its test file.**
+**Every skill MUST have a `SKILL.test.md` file in the same directory as its `SKILL.md`. The file defines test scenarios with explicit input triggers and falsifiable assertions. It MUST be executed — using the `run-skill-tests` skill or manually — before merging any PR that modifies the skill or its test file.**
 
 ### Details
 
@@ -57,6 +57,9 @@ specific enough that two independent agents produce comparable outputs.]
 
 Rules:
 - MUST contain at least two scenarios: one happy path and one edge or failure case.
+- MUST default to the 3 most relevant scenarios (typically the happy path plus the
+  highest-value edge/failure cases) and MUST NOT exceed 3 unless the user explicitly requests
+  more — larger suites cost more to execute and slow down verification.
 - Each scenario MUST have at least two assertions.
 - Assertions MUST be falsifiable (a pass/fail determination must be possible without ambiguity).
 - Assertion text MUST start with a verb ("Output contains …", "Skill asks …", "Review reports …").
@@ -68,7 +71,7 @@ Rules:
 
 `SKILL.test.md` MUST be executed before merging any PR that modifies the skill or its test file. Execution means running each scenario and verifying all assertions pass.
 
-Use the `200-run-skill-tests` skill to execute the file, or run each scenario manually when automation is not available.
+Use the `run-skill-tests` skill to execute the file, or run each scenario manually when automation is not available.
 
 
 ## Considered Options
@@ -80,4 +83,4 @@ Use the `200-run-skill-tests` skill to execute the file, or run each scenario ma
 ## References
 
 - [`_core-adr-policy-003`](../../../_core/adrs/principles/003-skill-standards.md) — Skill package standards and folder layout
-- [`200-run-skill-tests`](../application/skills/200-run-skill-tests/SKILL.md) — Runner skill that executes `SKILL.test.md` scenarios
+- [`run-skill-tests`](../application/skills/run-skill-tests/SKILL.md) — Runner skill that executes `SKILL.test.md` scenarios

package/.xdrs/agentme/edrs/principles/articles/001-continuous-xdr-improvement.md

@@ -90,4 +90,4 @@ If the same clarification would likely be needed in another feature, by another
 - [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-standards.md) - XDR structure, numbering, and mandatory template
 - [_core-article-001](../../../../_core/adrs/principles/articles/001-xdrs-overview.md) - XDR introduction and general adoption guidance
 - [agentme-edr-012](../012-continuous-xdr-enrichment.md) - Shared-first XDR enrichment policy and 80% coverage target
-- [002-write-policy skill](../../../../_core/adrs/principles/skills/002-write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs
+- [write-policy skill](../../../../_core/adrs/principles/skills/write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs

package/.xdrs/agentme/edrs/principles/skills/{150-refine-plan-mode → refine-plan-mode}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 150-refine-plan-mode
+name: refine-plan-mode
 description: >
   MANDATORY for ANY planning activity. Read and follow this skill in full whenever the user asks
   to plan, design, propose, outline, draft, brainstorm, architect, or think through anything —
@@ -8,7 +8,7 @@ description: >
   the XDRS repository even when not directly exposed in the .agents skills folder.
 metadata:
   author: flaviostutz
-  version: "2.9"
+  version: "3.0"
 ---
 
 ## Overview
@@ -27,6 +27,21 @@ Ensures that every plan is deeply validated through iterative consistency checks
 
 **Phase gate UI rule**: At every point where the skill requires human confirmation before advancing to the next phase — any instruction that says "Wait for the answer before continuing" or requires the human to confirm convergence — use `vscode_askQuestions` to present the gate. Always include a clearly labeled recommended option such as "Continue to Phase N — [phase name]" and allow free text so the human can provide corrections, ask follow-up questions, or redirect instead. Do not present a text prompt alone and wait for freeform input — the human must always have a visible, labeled UI option to advance.
 
+**Artifact rule**: The plan is a single continuously-edited final artifact, not an append-only log. Process detail — Q&A rounds, phase-gate confirmations, todo-list tracking — never enters the deliverable; todos stay in the agent's todo-list tool. When a later phase reverses an earlier decision or section, edit it in place — never leave the superseded content beside the replacement. The final artifact's structure follows the **Final Plan Artifact Template** below.
+
+## Final Plan Artifact Template
+
+The **final artifact** (Phase 7 handoff) uses this exact section order, no competing top-level sections — matching GitHub Copilot's native Plan Mode output shape:
+
+1. **Title/TL;DR** — `## Plan: <title>` plus a short what/why/approach paragraph; embed confirmed Phase 5 diagrams inline here, no separate heading.
+2. **Steps** — ordered, numbered; group into phases (`*Phase A: ...*`) at 5+ steps; annotate `*(depends on step N)*` / `*(parallel with step N)*`; always include the Phase 3 Step 3 test step.
+3. **Relevant files** — flat list: path plus what changes (if not obvious).
+4. **Quality Verification Strategy** — existing checks that must keep passing; new checks (code: tests, linting, type checking, dead code, security/dependency audit, schema/contract validation; documents: proofreading, fact-checking, citation/link validation, policy compliance, peer review, readability) with exact commands and what each verifies; named test scenarios (Phase 6 Scenario-to-test rule) as `<scenario> (<category>)`; an **Unverified References** sub-list, each *"unverified — must verify before use"* with a first-step verification.
+5. **Decisions** — final facts only; edit a reversed decision in place, never append a contradiction; a Phase 2 Step 5 split adds one bullet naming the chosen part (full detail stays in `TODO.md`).
+6. **Further Considerations** — optional, 1-3 out-of-scope or deferred items.
+
+Not in the artifact: round-by-round narrative, a session log, superseded drafts left beside replacements, meta-tags like "(updated in round 3)", or todo-list tracking (stays in the todo-list tool).
+
 ## Instructions
 
 ### Phase 1: Activate Plan Mode
@@ -94,9 +109,7 @@ Present a brief feature summary — a short bullet list of what will be built or
 
 1. Research the existing context: relevant files, prior decisions, established conventions, and analogous patterns already in place.
 2. For each contextual input, constraint, or dependency found (existing files, prior decisions, external systems, in-progress work by others), ask questions about all non-trivial items. For each dependency or context item, apply the Phase navigation rule: loop asking questions until that item converges before moving to the next. Only skip asking for trivially obvious or deterministic context items with no decision weight.
-3. Draft a plan with ordered steps, items to create or modify, and a verification step at the end. The plan MUST include a dedicated phase for test generation and execution whenever applicable — this phase must appear as an explicit step in the ordered plan, not only in the verification section. It must specify: (a) what tests to create or extend (unit, integration, end-to-end, or manual); (b) the exact commands or manual steps to run them; (c) the expected outcome for each. Examples: "Generate unit tests for X and run `npm test` — expect all pass", "Run integration tests with `make test-integration` — verify no regressions", "Manually open the generated document and verify sections Y and Z look correct". If no automated or manual tests apply, explicitly state why and mark the phase N/A. The plan MUST also include two dedicated sections:
-   - **Quality Verification Strategy**: (a) existing checks that must continue to pass; (b) new checks required for the task — for code: unit tests, integration tests, linting, type checking, dead code detection, security/dependency audit, schema/contract validation; for documents, analyses, and policies: proofreading, fact-checking, citation and link validation, policy compliance review, peer review, readability check; (c) exact executable steps or commands for each check; (d) what each check verifies. A plan without this section is incomplete.
-   - **Unverified References**: any resource referenced in the plan but not verified during planning must be listed here as *"unverified — must verify before use"* with a concrete first-step verification. For code: file paths, function names, CLIs, library APIs (e.g., `which cmd`, `npm list pkg`). For documents and analyses: statistics, quotes, cited studies, named organizations or people, URLs, legal or regulatory references. This section is the primary defense against fabricated claims surfacing only at execution time.
+3. Draft a plan with ordered steps, items to create or modify, and a dedicated test generation/execution step — this MUST appear as an explicit step in the ordered plan, not only in Quality Verification Strategy. Specify: (a) what tests to create or extend (unit, integration, end-to-end, or manual); (b) the exact commands or manual steps to run them; (c) the expected outcome for each. Example: "Generate unit tests for X and run `npm test` — expect all pass". If no automated or manual tests apply, explicitly state why and mark the phase N/A. The plan MUST also populate the **Final Plan Artifact Template**'s Quality Verification Strategy and Unverified References content — this is the primary defense against fabricated claims surfacing only at execution time.
 4. Present the draft and use `vscode_askQuestions` (per Phase gate UI rule) to ask: "Does this draft match your intent? What verification checks exist today, and what new checks will confirm the key outcomes?" Present at least these options:
    - **"Continue to Phase 4 — Consistency Checks"** (recommended when no gaps remain) — advance.
    - **"Re-run Phase 3: Research, Dependencies & Draft Plan — explore deeper"** — repeat the research and drafting pass looking for context, dependencies, or constraints not yet surfaced, then re-present the gate.
@@ -116,7 +129,7 @@ Checks to run in order:
 - **(e) Feasibility**: Is each step actually achievable given the current context, constraints, and available resources?
 - **(f) Completeness**: Is anything missing that would leave the task half-done or the outcome broken for its consumer?
 - **(g) Scope creep check**: Has the plan grown beyond the original request? Flag any additions and ask the human to confirm or reject each one explicitly before continuing. For large plans (more than approximately 10 steps), verify that each step traces to a requirement, user request, or policy — untraceable steps must be explicitly confirmed by the human.
-- **(h) Verification coverage and executability**: Are verification checks defined for each changed or new outcome, with exact executable steps or commands? Do they cover the applicable strategies for the context — for code: unit tests, integration tests, linting, type checking, dead code detection, security audit, schema/contract validation; for documents and analyses: proofreading, fact-checking, link and citation validation, policy compliance review, peer review, readability check? Can a reviewer independently confirm correctness by executing them without setup friction?
+- **(h) Verification coverage and executability**: Are verification checks defined for each changed or new outcome, with exact executable steps or commands, covering the applicable strategies from the **Final Plan Artifact Template**'s Quality Verification Strategy? Can a reviewer independently confirm correctness by executing them without setup friction?
 - **(i) Unverified claims audit**: Scan the plan for any factual claim, reference, or resource that the agent did not verify with a tool call or direct inspection — for code: file paths, function names, CLIs, library APIs; for documents and analyses: cited statistics, quoted sources, URLs, named people or organizations, legal references. Either verify each one immediately (preferred) or add it to the Unverified References section with a mandatory first-step verification before use. This check MUST NOT be skipped even when the agent is confident.
 
 **Human prompt examples** — these are effective ways to drive a round:
@@ -124,16 +137,10 @@ Checks to run in order:
 - `"Check for more features I would probably need but that are not part of the plan. Ask questions."`
 - `"What happens if the file doesn't exist? Ask questions."`
 - `"Dry run if I send a file with 10GB in size"`
-- `"What happens if we have 10 million files?"`
 - `"Explore if all types of input would work with this utility"`
-- `"Is the plan doing everything we asked in the beginning?"`
-- `"How are you making sure those things are implemented correctly?"`
 - `"Verify all references in the plan. Ask questions."`
 - `"Check for edge cases we didn't discuss yet. Ask questions."`
-- `"Check for consistency and ask questions"`
 - `"Show me a diagram explaining the overall feature structure"`
-- `"Explain to me what this utility does"`
-- `"How could I distribute this utility?"`
 
 After all checks (a–i) converge, use `vscode_askQuestions` (per Phase gate UI rule) to present the Phase 4 gate with at least these options:
 - **"Continue to Phase 5 — Visual Consistency Validation"** (recommended when all checks have converged) — advance.
@@ -237,6 +244,8 @@ After all 9 angles are complete, use `vscode_askQuestions` (per Phase gate UI ru
 
 ### Phase 7: Pre-Execution Readiness
 
+**Final Artifact Compaction pass** (run before the checklist below): (a) Template conformance — confirm the plan document matches the **Final Plan Artifact Template** exactly, with no other top-level sections; a safety net, not normally a large rewrite, since the Artifact rule already mandates in-place editing throughout. (b) Coherence-with-source check — compare the compacted plan against the full raw process history of this session (all phase outputs, questions and answers, research findings, and decisions actually made) and confirm no decision, requirement, or finding was lost, weakened, or contradicted by compaction. Fix any drift by correcting the plan directly, never by re-inserting raw process narrative.
+
 Before approving execution, verify ALL items in the checklist below. If any item cannot be checked, return to the relevant phase and resolve it first.
 
 - [ ] Consistency rounds converged (convergence signals met — last 2 rounds produced only single-sentence answers with no new issues) (per Phase navigation rule)
@@ -245,11 +254,12 @@ Before approving execution, verify ALL items in the checklist below. If any item
 - [ ] No unresolved human questions outstanding
 - [ ] Scope confirmed by the human with no silent expansions
 - [ ] Any irreversible or high-impact steps have a mitigation or fallback noted
-- [ ] Quality Verification Strategy defined in the plan with exact executable steps for all applicable check types (code: unit tests, integration tests, linting, static analysis; documents/analyses: fact-checking, link and citation validation, peer review, etc.)
+- [ ] Quality Verification Strategy defined in the plan with exact executable steps, per the **Final Plan Artifact Template**
 - [ ] A dedicated test generation and execution phase is present in the ordered plan steps (or explicitly marked N/A with a reason)
 - [ ] Verification checks executed during dry run and results reviewed — failures and coverage gaps resolved
 - [ ] All high-risk unverified references (code or factual) listed in the Unverified References section with explicit first-step verification in the execution plan
-- [ ] All scenarios from any phase or angle that revealed gaps, raised model doubt, or qualified for any category in the Scenario-to-test table have been added as named test cases to the plan's Quality Verification Strategy
+- [ ] All scenarios that revealed gaps, raised model doubt, or matched a Scenario-to-test category have been added as named test cases to Quality Verification Strategy
+- [ ] Final Artifact Compaction pass complete: the plan matches the template structure and has been checked for coherence against the full raw process history
 
 Once all items are checked or explicitly marked N/A, present a **brief scenario summary** — a short bulleted list of the most significant scenarios discovered across all phases (aim for 5–10 entries), each showing: the angle or check that surfaced it, what it revealed, and what test case was added to the plan. This makes the depth of analysis visible before handoff.
 
@@ -260,7 +270,7 @@ If any features were placed in the **Deferred Features** list during Phase 2 Ste
 This step is skipped if no features were deferred.
 
 **Deferred Features entry template** — always append a new `### Group:` section per split (never merge with a same-titled prior group); a group can have as few as 1 part:
-- `### Group: [original request title] — deferred [YYYY-MM-DD]` — with **Origin:** `150-refine-plan-mode — Phase 2 Step 5`, **Original objective:** the one-sentence value of the whole request before splitting, and **Split rationale:** why it was split.
+- `### Group: [original request title] — deferred [YYYY-MM-DD]` — with **Origin:** `refine-plan-mode — Phase 2 Step 5`, **Original objective:** the one-sentence value of the whole request before splitting, and **Split rationale:** why it was split.
 - One `#### [part title]` subsection per deferred part, each with **Objective:** (this part's specific value), **Scope:** (bullet list of what's included), **Context captured so far:** (bullet list of key decisions/answers/constraints already gathered before deferral), and **Suggested prompt to resume:** (a ready-to-paste prompt naming plan mode and summarizing the objective and known constraints so a future session can resume without re-reading the whole conversation).
 
 Before the final gate, add a step to the implementation plan to produce a concise feature documentation file. Use `vscode_askQuestions` to ask:
@@ -284,7 +294,7 @@ Do not start execution to escape planning discomfort — only start when confide
 
 **Test execution rule**: After implementation is complete, all tests defined in the Quality Verification Strategy must be run before the work is considered done:
 - **Automated tests** (unit tests, integration tests, linting, type checking, coverage): run them directly using the exact commands defined in the plan. If any fail, fix the issue and re-run before proceeding.
-- **Manual tests**: for each manual test step in the plan, guide the human explicitly — state what command to run or action to take, what to look at, and what the expected output or behaviour is. Wait for the human to confirm the result before moving to the next step. If the result doesn’t match, treat it as a failure and investigate before continuing.
+- **Manual tests**: for each manual step, guide the human explicitly — state the action, what to look at, and the expected result. Wait for confirmation before the next step; treat a mismatch as a failure and investigate before continuing.
 - Do not mark the work done until every test — automated and manual — has a confirmed passing result.
 
 ---
@@ -298,6 +308,7 @@ Avoid these common failure modes:
 - **Agent self-validation**: the agent answers its own questions on subjective, domain, or intent-based decisions and proceeds without asking the human. The human is the oracle for domain knowledge, intent, and subjective decisions — the agent must not self-resolve those unilaterally.
 - **Confidence as a proxy for correctness**: an agent expressing certainty does not mean the plan is correct. Run all checks regardless of how confident the agent sounds.
 - **Treating unverified references as facts**: the agent references files, CLIs, statistics, library APIs, quoted sources, or named organizations without a tool call or direct inspection to confirm they exist. All high-risk references must be verified immediately or explicitly listed in the Unverified References section with a mandatory first-step check before use.
+- **Artifact bloat**: the final plan accretes process narrative (Q&A rounds, phase-gate confirmations, todo-list tracking, superseded drafts) instead of converging to the **Final Plan Artifact Template**. It's a continuously-edited deliverable, not an append-only log.
 
 ## Re-Plan Triggers
 

package/.xdrs/agentme/edrs/principles/skills/{150-refine-plan-mode → refine-plan-mode}/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
-skill: 150-refine-plan-mode
-skill-version: "2.9"
+skill: refine-plan-mode
+skill-version: "3.0"
 ---
 
 ## Test Scenarios
@@ -13,7 +13,7 @@ skill-version: "2.9"
 
 **Expected Behaviour**
 
-The skill activates plan mode immediately. Before writing any code or editing any file, it: (1) states the goal and scope in Phase 1; (2) runs Phase 2 (Requirements Qualification) — restates understanding, scans the 6 areas for missing information, loops asking follow-up questions until convergence, then runs the scope item 3-check review; (3) per the Phase navigation rule, loops on each dependency or context item in Phase 3 (Research, Dependencies, and Draft Plan) until it converges before moving to the next; (4) runs iterative consistency checks in Phase 4, each round asking 1–5 questions across one or more checks (a–i), applying the Phase navigation rule convergence signal to stop; (5) generates a diagram in Phase 5 and loops until the human explicitly confirms it; (6) analyzes all 18 challenge angles in Phase 6 applying the Phase navigation rule per angle; (7) verifies the Phase 7 Pre-Execution Readiness checklist before approving execution.
+The skill activates plan mode immediately. Before writing any code or editing any file, it: (1) states the goal and scope in Phase 1; (2) runs Phase 2 (Requirements Qualification) — restates understanding, scans the 6 areas for missing information, loops asking follow-up questions until convergence, then runs the scope item 3-check review; (3) per the Phase navigation rule, loops on each dependency or context item in Phase 3 (Research, Dependencies, and Draft Plan) until it converges before moving to the next; (4) runs iterative consistency checks in Phase 4, each round asking 1–5 questions across one or more checks (a–i), applying the Phase navigation rule convergence signal to stop; (5) generates a diagram in Phase 5 and loops until the human explicitly confirms it; (6) analyzes all 9 challenge angles in Phase 6 applying the Phase navigation rule per angle; (7) verifies the Phase 7 Pre-Execution Readiness checklist before approving execution.
 
 **Simulated Human Responses**
 1. "Yes, goal and scope match exactly."
@@ -33,7 +33,7 @@ The skill activates plan mode immediately. Before writing any code or editing an
 - [ ] Each human interaction round across all phases contains 1–5 questions grouped together.
 - [ ] Skill applies the Phase navigation rule convergence signal rather than a fixed round cap.
 - [ ] Skill generates a diagram in Phase 5 (Visual Consistency Validation) and loops until the human explicitly confirms it.
-- [ ] All 18 challenge angles in Phase 6 are analyzed; related angles may share a round.
+- [ ] All 9 challenge angles in Phase 6 are analyzed; related angles may share a round.
 - [ ] Phase 7 Pre-Execution Readiness checklist is verified before execution is approved.
 
 ### Scenario 2: Well-structured input still triggers full Phase 2 Requirements Qualification
@@ -113,3 +113,27 @@ Phase 2 Step 4 surfaces roughly 24 distinct in-scope items across the three subs
 - [ ] TODO.md is created (or appended to) at the workspace root with a `## Deferred Features` heading.
 - [ ] A single `### Group:` heading covers both deferred parts, recording Origin, Original objective, and Split rationale.
 - [ ] Each deferred part appears as its own `#### ` subsection with Objective, Scope, Context captured so far, and a Suggested prompt to resume.
+
+### Scenario 6: Final plan artifact contains no process narrative
+
+**Trigger / Input**
+
+A user runs the full refine-plan-mode workflow across multiple rounds — including at least one re-run of a phase gate (e.g., "Re-run Phase 4: Consistency Checks — deeper pass") and one Phase 2 Step 5 scope split with a deferred part — before reaching Phase 7 and confirming "Hand off to implementation".
+
+**Expected Behaviour**
+
+Throughout every phase, the plan document is maintained as a single continuously-edited artifact per the Artifact rule. When Phase 4 is re-run, the consistency-check findings from the first pass are merged or replaced in place — not appended as a second "round 2" narrative block. When a decision is revisited, the earlier entry is edited, not left beside a newer contradicting one. The final plan handed off at Phase 7 follows the structure in SKILL.md's Final Plan Artifact Template section: Title/TL;DR, Steps, Relevant files, Quality Verification Strategy (including Unverified References), Decisions, Further Considerations — with no additional top-level sections such as a session log, round-by-round history, or Q&A transcript.
+
+**Simulated Human Responses**
+1. "Accept split — start planning [Part 1 name]" (Phase 2 Step 5 scope split)
+2. "Re-run Phase 4: Consistency Checks — deeper pass"
+3. "Continue to Phase 5 — Visual Consistency Validation" (after the re-run converges)
+4. "Hand off to implementation" (Phase 7 final gate)
+
+**Assertions**
+
+- [ ] The final plan document contains no section narrating the planning process itself (e.g. "Round 1", "Round 2", phase-gate Q&A transcripts, a session status log).
+- [ ] No decision or section appears twice with one marked as superseding the other — reversed decisions are edited in place.
+- [ ] The final plan's top-level sections match SKILL.md's Final Plan Artifact Template section exactly, with zero additional top-level sections.
+- [ ] Todo-list tracking used during the workflow (per the Task tracking rule) does not appear inside the final plan document.
+- [ ] The Deferred Features entry from the Phase 2 Step 5 split appears only in `TODO.md` (per the existing template), not duplicated inside the main plan body.