agentme 0.36.0 → 0.37.0

package/.xdrs/agentme/edrs/index.md

@@ -8,12 +8,12 @@ Propose changes via pull request. All changes must be verified for clarity and n
 
 Foundational standards, principles, and guidelines.
 
-- [150-refine-plan-mode](principles/skills/150-refine-plan-mode/SKILL.md) - **Refine plan mode** — MANDATORY skill for ANY planning activity (plan, design, propose, outline, draft, brainstorm, architect). Read and follow in full before any execution begins. Must be read from XDRS even when not in `.agents/skills`. *(skill)*
-- [151-refine-user-story](principles/skills/151-refine-user-story/SKILL.md) - **Refine user stories** — Refine, elaborate, study or develop the contents of a user story used to create a unit of work for an agile team. Runs a structured 10-phase refinement process: understand the request, qualify requirements, research context, review consistency, validate visually, challenge from 9 user-perspective angles (Phase 6), challenge from 8 implementer-perspective angles (Phase 7), produce a ready-to-implement story (Phase 8), and run a final readiness double-check (Phase 9). *(skill)*
-- [400-pr-owner-assistant](principles/skills/400-pr-owner-assistant/SKILL.md) - **PR owner assistant** — Helps the OWNER of a pull request work through comments left by others: fetches every comment (GitHub or Azure DevOps) from its URL, tracks them in a local file, and walks through triaging each one (reply-question, won't-fix, work-on-a-fix) with explicit human confirmation at every step. A hands-on, mutating workflow to answer feedback and land fixes -- not a code-review skill. Delegates provider-specific reads/writes to `250-github-connector` or `251-azure-devops-connector`. *(skill)*
+- [refine-plan-mode](principles/skills/refine-plan-mode/SKILL.md) - **Refine plan mode** — MANDATORY skill for ANY planning activity (plan, design, propose, outline, draft, brainstorm, architect). Read and follow in full before any execution begins. Must be read from XDRS even when not in `.agents/skills`. *(skill)*
+- [refine-user-story](principles/skills/refine-user-story/SKILL.md) - **Refine user stories** — Refine, elaborate, study or develop the contents of a user story used to create a unit of work for an agile team. Runs a structured 10-phase refinement process: understand the request, qualify requirements, research context, review consistency, validate visually, challenge from 9 user-perspective angles (Phase 6), challenge from 8 implementer-perspective angles (Phase 7), produce a ready-to-implement story (Phase 8), and run a final readiness double-check (Phase 9). *(skill)*
+- [resolve-pr-comments](principles/skills/resolve-pr-comments/SKILL.md) - **Resolve PR comments** — Helps the OWNER of a pull request work through comments left by others: fetches every comment (GitHub or Azure DevOps) from its URL, tracks them in a local file, and walks through triaging each one (reply, won't-fix, fix) at a human-chosen automation level -- from fully automatic to fully guided, with fine-grained free-text control over the mix -- while syncing back to the provider always stays its own explicitly confirmed step. A hands-on, mutating workflow to answer feedback and land fixes -- not a code-review skill. Delegates provider-specific reads/writes to `github-connector` or `azure-devops-connector`. *(skill)*
 - [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy** - Promote recurring delivery lessons into reusable XDRs
 - [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure** - Organize modules consistently across supported languages
-- [agentme-edr-017](principles/017-skill-testing.md) - **skill testing** - Mandates a `SKILL.test.md` co-located with every skill in scopes that follow agentme; defines test scenario format (trigger, expected behaviour, assertions) and requires execution before merging any skill change *(includes skill: [200-run-skill-tests](application/skills/200-run-skill-tests/SKILL.md))*
+- [agentme-edr-017](principles/017-skill-testing.md) - **skill testing** - Mandates a `SKILL.test.md` co-located with every skill in scopes that follow agentme; defines test scenario format (trigger, expected behaviour, assertions) and requires execution before merging any skill change *(includes skill: [run-skill-tests](application/skills/run-skill-tests/SKILL.md))*
 
 ## Articles
 
@@ -31,17 +31,17 @@ Language and framework-specific tooling and project structure.
 - [agentme-edr-124](application/124-secrets-management.md) - **Secrets management** - Handle secrets securely using native keychains and cloud secret managers
 - [agentme-edr-125](application/125-coding-abstraction-practices.md) - **Coding abstraction practices** - Define when abstractions are justified and when they must be inlined
 - [agentme-edr-127](application/127-external-system-adapter-skills.md) - **External system adapter skills** - Priority-ordered approach and adapter skill authoring standards for automating interactions with external systems
-- [250-github-connector](application/skills/250-github-connector/SKILL.md) - **GitHub connector** — Base connector providing authentication, read access, and write access to GitHub pull requests and their comments via the `gh` CLI. *(skill)*
-- [251-azure-devops-connector](application/skills/251-azure-devops-connector/SKILL.md) - **Azure DevOps connector** — Base connector providing authentication, read access, and write access to Azure DevOps pull requests and their comment threads via the `az` CLI. *(skill)*
+- [github-connector](application/skills/github-connector/SKILL.md) - **GitHub connector** — Base connector providing authentication, read access, and write access to GitHub pull requests and their comments via the `gh` CLI. *(skill)*
+- [azure-devops-connector](application/skills/azure-devops-connector/SKILL.md) - **Azure DevOps connector** — Base connector providing authentication, read access, and write access to Azure DevOps pull requests and their comment threads via the `az` CLI. *(skill)*
 
 ### Language and framework tooling
 
-- [agentme-edr-101](application/101-javascript-project-tooling.md) - **JavaScript project tooling and structure** - Scaffold JavaScript libraries with the standard toolchain *(includes skill: [050-create-javascript-project](application/skills/050-create-javascript-project/SKILL.md))*
-- [agentme-edr-102](application/102-golang-project-tooling.md) - **Go project tooling and structure** - Scaffold Go CLIs and libraries with the standard layout *(includes skill: [051-create-golang-project](application/skills/051-create-golang-project/SKILL.md))*
-- [agentme-edr-103](application/103-python-project-tooling.md) - **Python project tooling and structure** - Scaffold Python packages and CLIs with the standard layout *(includes skill: [052-create-python-project](application/skills/052-create-python-project/SKILL.md))*
+- [agentme-edr-101](application/101-javascript-project-tooling.md) - **JavaScript project tooling and structure** - Scaffold JavaScript libraries with the standard toolchain *(includes skill: [create-javascript-project](application/skills/create-javascript-project/SKILL.md))*
+- [agentme-edr-102](application/102-golang-project-tooling.md) - **Go project tooling and structure** - Scaffold Go CLIs and libraries with the standard layout *(includes skill: [create-golang-project](application/skills/create-golang-project/SKILL.md))*
+- [agentme-edr-103](application/103-python-project-tooling.md) - **Python project tooling and structure** - Scaffold Python packages and CLIs with the standard layout *(includes skill: [create-python-project](application/skills/create-python-project/SKILL.md))*
 - [agentme-edr-104](application/104-cli-tool-standards.md) - **CLI tool standards** - Define command UX and behavior for CLI tools
 - [agentme-edr-126](application/126-pragmatic-hexagonal-architecture.md) - **Pragmatic hexagonal architecture** - Organize application layers as External/Adapters/Application with practical coupling rules
-- [010-select-relevant-xdrs](application/skills/010-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
+- [select-relevant-xdrs](application/skills/select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
 
 ### AI development
 
@@ -75,7 +75,7 @@ Data layer implementation and data management decisions.
 
 Infrastructure implementation, delivery pipeline, and developer environment decisions.
 
-- [agentme-edr-301](platform/301-monorepo-structure.md) - **Monorepo structure** - Standardize monorepo layout, tooling, and package boundaries *(includes skill: [053-monorepo-setup](platform/skills/053-monorepo-setup/SKILL.md))*
+- [agentme-edr-301](platform/301-monorepo-structure.md) - **Monorepo structure** - Standardize monorepo layout, tooling, and package boundaries *(includes skill: [monorepo-setup](platform/skills/monorepo-setup/SKILL.md))*
 - [agentme-edr-302](platform/302-github-pipelines.md) - **GitHub CI/CD pipelines** - Define required CI stages and workflow structure
 - [agentme-edr-303](platform/303-common-targets.md) - **Common development script names** - Reuse standard build, lint, and test target names
 - [agentme-edr-304](platform/304-tool-execution-and-scripting.md) - **Tool execution and scripting** - Run tools consistently across shells, Makefiles, and CI
@@ -93,3 +93,8 @@ Contribution and collaboration standards shared across projects.
 Production behavior and operational response decisions.
 
 - [agentme-edr-401](operations/401-service-health-check-endpoint.md) - **Service health check endpoint** - Expose a standard runtime health-check endpoint for services
+- [agentme-edr-402](operations/402-dora-metrics-framework.md) - **DORA metrics framework** - Per-service/team measurement, sub-metric composition, maturity tiers, and adoption order for DORA's four key metrics
+- [agentme-edr-403](operations/403-dora-deployment-frequency.md) - **DORA deployment frequency** - Calculation, examples, and challenges for deploys-per-week, batch size, and automation ratio
+- [agentme-edr-404](operations/404-dora-lead-time-for-changes.md) - **DORA lead time for changes** - Calculation, examples, and challenges for PR cycle time, review latency, deploy-pipeline time, and total lead time
+- [agentme-edr-405](operations/405-dora-change-failure-rate.md) - **DORA change failure rate** - Calculation, examples, and challenges for hotfix/revert rate, incident-linked deploy rate, and escaped defect rate, including cross-team attribution
+- [agentme-edr-406](operations/406-dora-time-to-restore-service.md) - **DORA time to restore service** - Calculation, examples, and challenges for total restore time, detection time, acknowledgement time, and resolution time

package/.xdrs/agentme/edrs/operations/402-dora-metrics-framework.md

@@ -0,0 +1,82 @@
+---
+name: agentme-edr-policy-402-dora-metrics-framework
+description: Defines the framework for measuring DORA's four software delivery metrics per team and service, including sub-metric composition, maturity-tier definition, distribution reporting, adoption order, and daily usage by role. Use when implementing or reviewing DORA metrics measurement, dashboards, or reporting.
+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-402: DORA metrics framework
+
+## Context and Problem Statement
+
+Teams need objective signals of software delivery performance, but without a shared framework, teams measure different things, blend unlike services together, or reduce delivery health to one misleading number. How should DORA's four key metrics be scoped, combined into a maturity signal, and used across teams so results stay comparable, actionable, and resistant to gaming?
+
+## Decision Outcome
+
+**Adopt DORA's four key metrics, each measured per service and rolled up per team, decomposed into incrementally-adoptable sub-metrics defined in one companion policy per metric.**
+
+Every team gets a maturity tier per metric plus one blended tier; company-wide reporting always shows a tier distribution, never a company-wide average.
+
+### Details
+
+#### 01-four-key-metrics
+
+This framework covers DORA's four key metrics: Deployment Frequency ([agentme-edr-403](403-dora-deployment-frequency.md)), Lead Time for Changes ([agentme-edr-404](404-dora-lead-time-for-changes.md)), Change Failure Rate ([agentme-edr-405](405-dora-change-failure-rate.md)), and Time to Restore Service ([agentme-edr-406](406-dora-time-to-restore-service.md); DORA's current term is "Failed Deployment Recovery Time"). Sub-metrics MUST follow a hybrid composition model: Lead Time and Time to Restore sub-metrics are additive and sum to the parent value, while Deployment Frequency and Change Failure Rate sub-metrics are complementary signals that MUST NOT be summed. All time-based sub-metrics MUST use the median (p50) as the headline statistic instead of the mean, to resist outlier skew; percentile bands (p85/p95) MAY be added for distribution visibility.
+
+#### 02-per-service-and-team-accounting
+
+Every metric and sub-metric MUST be measured and reported per team, never only as an org-wide aggregate. The atomic unit of attribution MUST be the deployable service, not the team directly: a team's figures MUST be a rollup of its owned services, per [agentme-bdr-402](../../bdrs/operations/402-digital-product-roles.md)'s `01-product-team-purpose`/`02-product-team-scope-of-work` (a team owns its product's full lifecycle end-to-end). A change touching multiple services MUST be measured independently against each affected service's own timeline; it MUST NOT be flagged as cross-team or assigned to one majority owner.
+
+#### 03-artifact-to-service-mapping
+
+Code-path-based artifacts (pull requests, commits, deploy-workflow runs) MUST be attributed to a service using the repository's CODEOWNERS file, with path patterns defined at service-directory granularity. CODEOWNERS MUST NOT be used for GH Issues, since issues have no file path; issue-based sub-metrics MUST instead use an explicit label or component convention (for example a `service:<name>` label) cross-walked to the owning service.
+
+#### 04-cross-team-incident-attribution
+
+When an incident's root cause is traced to a different team's change, it MUST be counted against the root-cause team's Change Failure Rate ([agentme-edr-405](405-dora-change-failure-rate.md)) and, separately, tagged as a non-tiered visibility signal for the impacted team. It MUST NOT be double-counted into the impacted team's own numerator. Root-cause determination MUST follow [agentme-bdr-405](../../bdrs/operations/405-digital-product-roles-raci.md)'s `04-accountability-network-and-root-cause-tracing` methodology rather than a separate one defined here.
+
+#### 05-maturity-level-definition
+
+Each team MUST be assigned a named maturity tier (Elite, High, Medium, or Low, per DORA's current published bands, cited and dated rather than hardcoded here) for each of the four metrics. Each team MUST also receive one blended maturity label equal to the floor (worst) of its four per-metric tiers. This floor combination is this framework's own practical proxy, since DORA does not publish an official per-team combination formula; it is grounded in DORA's own finding that top performers tend to do well across all metrics. A Low tier on a metric with a genuine regulatory floor MUST NOT be treated as an excuse to stop improving the rest of that metric or any other metric within the team's control.
+
+#### 06-maturity-level-distribution-reporting
+
+Maturity level MUST NOT be averaged across teams into one company-wide figure. Company-wide reporting MUST show the percentage of teams at each blended tier as the headline view, with the four per-metric tier distributions available as a supporting drill-down. Distributions MUST NOT be used to rank or compete teams against each other, and individual team results MUST NOT be reported in a way that isolates one team's metrics from the others' — both patterns are documented by DORA as pitfalls that fuel finger-pointing and gaming.
+
+#### 07-adoption-order
+
+Teams SHOULD adopt the four metrics in this order: Deployment Frequency, then Lead Time for Changes, then Change Failure Rate, then Time to Restore Service. Each step needs one more data source or organizational capability than the last (deploy-workflow history only; then PR data; then a failure-labeling convention; then incident-management timestamps), and DORA's research shows that improving batch size and frequency first cascades into better lead time and stability. Each companion policy defines its own internal sub-metric adoption order using the same ease-plus-impact rationale.
+
+#### 08-daily-usage-by-role
+
+Roles SHOULD consult these metrics at the cadence below when carrying out their accountabilities as defined in [agentme-bdr-402](../../bdrs/operations/402-digital-product-roles.md), [agentme-bdr-404](../../bdrs/operations/404-team-roles-and-specialists.md), and [agentme-bdr-405](../../bdrs/operations/405-digital-product-roles-raci.md):
+
+| Role | Cadence | Usage |
+|---|---|---|
+| Tech Lead / AI Lead | Daily | Primary consumer; accountable for CI/CD pipeline health and incident response; reads review latency ([agentme-edr-404](404-dora-lead-time-for-changes.md) `02`) jointly with Change Failure Rate to catch rubber-stamping |
+| PO | Weekly | Reads Deployment Frequency and Lead Time alongside Change Failure Rate before go-live approvals |
+| EM | Weekly/quarterly | Cross-checks a sustained Low tier against the team's `agentme-bdr-402` `03-workforce-allocation` operations-and-controls capacity |
+| PjM | As-needed | Investigates cross-team blockers when Lead Time or Change Failure Rate issues trace to cross-team dependencies |
+| PM / Leadership | Quarterly | Reads the tier distribution from rule `06`, never a company-wide average |
+
+## Considered Options
+
+* (REJECTED) **Single composite delivery score** — blend all four metrics into one number
+  * Reason: Hides which metric needs attention; contradicts DORA's own guidance against "one metric to rule them all"
+* (REJECTED) **Company-wide averaged maturity score** — one blended number across all teams
+  * Reason: Masks teams that need help; contradicts DORA's guidance against disparate comparisons and siloed competition
+* (REJECTED) **Strict-composition redesign for Deployment Frequency and Change Failure Rate** — force all sub-metrics to sum to the parent value
+  * Reason: Would require dropping batch size (an orthogonal dimension) and escaped-defect-rate (different attribution lag) to force a clean sum
+
+## References
+
+- [DORA's software delivery performance metrics](https://dora.dev/guides/dora-metrics-four-keys/)
+- [agentme-edr-403](403-dora-deployment-frequency.md) — Deployment Frequency
+- [agentme-edr-404](404-dora-lead-time-for-changes.md) — Lead Time for Changes
+- [agentme-edr-405](405-dora-change-failure-rate.md) — Change Failure Rate
+- [agentme-edr-406](406-dora-time-to-restore-service.md) — Time to Restore Service
+- [agentme-edr-401](401-service-health-check-endpoint.md) — Service health check endpoint
+- [agentme-edr-302](../platform/302-github-pipelines.md) — GitHub CI/CD pipelines
+- [agentme-bdr-402](../../bdrs/operations/402-digital-product-roles.md) — Digital product roles: org & cross-team
+- [agentme-bdr-404](../../bdrs/operations/404-team-roles-and-specialists.md) — Digital product roles: team & specialists
+- [agentme-bdr-405](../../bdrs/operations/405-digital-product-roles-raci.md) — Digital product roles: RACI

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
 
@@ -71,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
@@ -83,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 —
@@ -137,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.
@@ -276,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:

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

@@ -1,5 +1,5 @@
 ---
-skill: 150-refine-plan-mode
+skill: refine-plan-mode
 skill-version: "3.0"
 ---
 
@@ -118,7 +118,7 @@ Phase 2 Step 4 surfaces roughly 24 distinct in-scope items across the three subs
 
 **Trigger / Input**
 
-A user runs the full 150-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".
+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**