agentme 0.35.2 → 0.37.0

package/.xdrs/agentme/edrs/application/skills/github-connector/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: github-connector
+description: >
+  Base connector providing authentication, read access, and write access to GitHub pull
+  requests and their comments via the gh CLI. Pure I/O -- no triage logic, no business
+  decisions. Activate when an agent or skill (such as resolve-pr-comments) needs to fetch or
+  post PR comments, resolve review threads, or check out a PR branch on GitHub.
+metadata:
+  author: flaviostutz
+  version: "1.1"
+---
+
+## Overview
+
+Reusable authentication and connection skill for GitHub pull requests, per
+[agentme-edr-127](../../127-external-system-adapter-skills.md) rule 06 (connector naming).
+Wraps the `gh` CLI -- GitHub's own supported API client -- so callers never construct raw
+REST/GraphQL calls or handle GitHub-specific auth themselves. Contains no business logic (per
+rule 05): it does not decide what a comment means, what action to take, or when to reply --
+it only reads and writes data and normalizes it to the shape consumed by
+[`resolve-pr-comments`](../../../principles/skills/resolve-pr-comments/SKILL.md).
+
+## Instructions
+
+### Authentication check
+
+1. Verify the `gh` CLI is installed (`gh --version`); if missing, ask the human whether to
+   install it now via the appropriate package manager for their OS (e.g. `brew install gh`
+   on macOS). Only run the install command after explicit confirmation; if the human
+   declines or the install fails, report the install requirement and stop.
+2. Run `gh auth status`. If authenticated, proceed -- this is the preferred path since `gh`
+   manages its own session token securely (per agentme-edr-124's least-exposure principle)
+   and needs no secret handling here.
+3. If not authenticated, run
+   `gh auth login --hostname github.com --git-protocol https --web` instead of bare
+   `gh auth login` -- these flags answer the "Where do you use GitHub?", "preferred
+   protocol?", and "how would you like to authenticate?" prompts non-interactively so the
+   human is never asked them. `gh` still asks one local yes/no question ("Authenticate Git
+   with your GitHub credentials?"); accept its default (`Y`) automatically, since it only
+   wires the existing `gh` credential helper into git and needs no human input. The only
+   step that still requires the human is the one-time code / "Press Enter to open ... in
+   your browser" prompt that follows -- `gh` stores the resulting token in its own secure
+   storage once that completes. Never ask the human for a raw PAT and never read, request,
+   or feed a token to `gh` directly. Do not proceed with a write operation until
+   `gh auth status` reports an authenticated session.
+4. Never substitute `gh` with a direct HTTP call (`curl`, `fetch`, or any other HTTP client)
+   against the GitHub REST/GraphQL API, and never scrape the PR's rendered HTML page as a
+   workaround -- this applies to reads as much as writes, and applies even when the target
+   data is public. If `gh` is missing or unauthenticated, stop and resolve that first (steps
+   1-3 above); do not degrade to an alternative retrieval method to route around it.
+
+### Reading data
+
+All read commands are plain `gh` invocations; none require confirmation (per
+agentme-edr-127 rule 04, read-only operations are exempt from the HITL confirmation step
+only -- they are not exempt from the CLI-only channel). Every read below MUST go through
+`gh`; never construct the equivalent call with `curl`/another HTTP client, and never fetch
+or scrape the PR's rendered web page as a substitute. When running `gh` from an automated
+or non-interactive shell, prefix calls with `GH_PAGER=cat` (see Known Issues) so output is
+never lost to a pager.
+
+- PR metadata: `gh pr view <n> --json title,body,baseRefName,headRefName,url,state,isCrossRepository,headRepositoryOwner,headRepository`
+- Issue-level (top) comments: `gh api repos/{owner}/{repo}/issues/{n}/comments`
+- Review (file/line) comments: `gh api repos/{owner}/{repo}/pulls/{n}/comments`
+- Review summaries: `gh api repos/{owner}/{repo}/pulls/{n}/reviews`
+- Thread resolution state (REST does not expose this): `gh api graphql` with a
+  `reviewThreads` query on the PR, reading `isResolved` and each thread's comment node ids.
+
+Normalize every fetched item to the shared record shape (`id`, `kind`, `status`, `can_reply`,
+`can_resolve`, `path`, `line`, `content`, `author`, `in_reply_to`, `diff_hunk`, `url`):
+- `kind` is `"issue-comment"`, `"review-comment"`, or `"review-summary"`.
+- `status` is `"resolved"` when the GraphQL thread lookup marks it resolved, else `"open"`.
+  GitHub has no `wontfix`/`closed` state of its own -- `resolve-pr-comments` tracks those
+  locally.
+- `can_resolve` is `true` only for `"review-comment"` items belonging to a resolvable
+  thread; `"issue-comment"` and `"review-summary"` are never resolvable -- set `false`.
+- `in_reply_to` is resolved to the thread's top-level/root comment id, never an intermediate
+  reply, so replies always thread correctly.
+- If the reply target is a reply-to-a-reply, resolve `in_reply_to` up to the root comment id
+  first (GitHub only allows replying to the root of a review thread).
+- `diff_hunk` is taken verbatim from the `diff_hunk` field already present on each
+  `"review-comment"` item returned by the review-comments read command above -- no extra
+  fetch needed. Null for `"issue-comment"` and `"review-summary"` items, since neither is
+  file/line-scoped.
+- `url` is taken verbatim from the `html_url` field already present on every issue-comment,
+  review-comment, and review object returned by the read commands above -- no extra fetch
+  needed for any `kind`.
+
+### Writing data
+
+Before any write below, show the mandatory confirmation (per agentme-edr-127 rule 04):
+**System** (`owner/repo` + PR number), **Operation**, **Fields** (exact verbatim text to
+post), **Estimated impact** (visible to PR participants, triggers notifications). Wait for
+explicit confirmation; never proceed on an assumed "yes."
+
+- Reply to an issue-level comment: `gh api repos/{owner}/{repo}/issues/{n}/comments -f body="..."`
+- Reply to a review thread: `gh api repos/{owner}/{repo}/pulls/{n}/comments -f body="..." -F in_reply_to=<root-comment-id>`
+- Post a new general PR comment: `gh pr comment <n> --body "..."`
+- Resolve a review thread: `gh api graphql` with a `resolveReviewThread` mutation, passing
+  the thread's GraphQL node id (not the REST numeric id -- these are different identifier
+  spaces; see Known Issues).
+- Check out the PR branch: `gh pr checkout <n>`.
+
+### Constraints
+
+- MUST use the `gh` CLI for every read and write handled by this connector -- never fall
+  back to `curl`, another raw HTTP client, or scraping the PR's HTML page, even when `gh` is
+  missing, unauthenticated, rate-limited, or erroring, and even when the target data is
+  public.
+- MUST stop and follow the Authentication check steps above when `gh` cannot complete a
+  request, instead of silently degrading to an alternative retrieval method.
+
+## Examples
+
+**Input**: fetch all comments for `https://github.com/acme/widgets/pull/482`
+
+Runs `gh pr view 482 --json ...` for metadata, then the three read commands above for
+issue-comments, review-comments, and reviews, then one `gh api graphql` call for thread
+resolution state, and returns a single normalized list.
+
+**Input**: reply to review comment id `review-comment/91234` and mark it resolved
+
+Shows the mandatory confirmation summary first. On explicit "yes," posts the reply via
+`gh api repos/{owner}/{repo}/pulls/{n}/comments -F in_reply_to=91234`, then resolves the
+thread via the GraphQL mutation using that comment's thread node id.
+
+## Edge Cases
+
+- **PR from a fork**: `headRepositoryOwner`/`headRepository` differ from the base repo;
+  checkout and branch comparisons must use the fork's remote, not the base repo's.
+- **Review-summary comments**: never resolvable and never file/line-scoped; `path`/`line`
+  are always null and `can_resolve` is always `false`.
+- **Reply-to-a-reply**: GitHub only supports replying to a thread's root comment; always
+  resolve `in_reply_to` up to the root before posting.
+
+## Known Issues
+
+- **Symptom:** `resolveReviewThread` mutation fails with a "could not resolve to a node"
+  error even though the comment id is valid.
+  **Cause:** the mutation requires the review thread's GraphQL node id, not the numeric
+  REST comment id or the numeric review id -- these are three different identifier spaces.
+  **Fix:** always fetch the thread's node id via the `reviewThreads` GraphQL query first,
+  and cache the numeric-id-to-node-id mapping per PR fetch. Verify the exact mutation shape
+  via `gh api graphql` introspection before first use in a new environment.
+- **Symptom:** posting a reply or resolving a thread returns HTTP 403 despite `gh auth
+  status` showing a valid session.
+  **Cause:** the authenticated account lacks write/triage permission on the repository (for
+  example, an outside collaborator with read-only access).
+  **Fix:** degrade to reply-only where permitted, report the permission gap plainly, and
+  never retry the same call silently.
+- **Symptom:** any `gh api` call returns HTTP 404 for a repo the human insists exists.
+  **Cause:** the authenticated token lacks the `repo` (or fine-grained equivalent) scope, so
+  GitHub reports a private resource as not found rather than as forbidden.
+  **Fix:** report this distinction explicitly and ask the human to re-run
+  `gh auth refresh -s repo` rather than assuming the PR truly does not exist.
+- **Symptom:** repeated calls start failing with HTTP 403 and a rate-limit message.
+  **Cause:** GitHub's REST/GraphQL rate limits were exceeded, often from re-fetching the
+  full comment list too frequently in one session.
+  **Fix:** space out calls and reuse the already-fetched result within a session; never
+  silently retry in a tight loop.
+- **Symptom:** an agent fetched PR metadata, comments, or diffs via `curl`/`api.github.com`
+  or by scraping the PR's rendered HTML page instead of using `gh`.
+  **Cause:** `gh` was missing or unauthenticated (e.g. `gh auth status` reported not logged
+  in), and the agent treated the unauthenticated public REST API or the rendered PR page as
+  an acceptable substitute since the target data was technically public.
+  **Fix:** never substitute `gh` with a direct HTTP call or a page scrape, regardless of
+  whether the data is public. Stop at the Authentication check step, report the missing or
+  failed `gh` session plainly, and wait for the human to install or authenticate `gh` before
+  retrying the same read or write through `gh`.
+- **Symptom:** a `gh api`/`gh pr view` read command run from an automated shell appears to
+  hang or return no captured output at all, even though `gh` itself succeeded.
+  **Cause:** `gh` falls back to `$PAGER` (commonly `less`) for output it thinks may be
+  interactive; this switches the terminal to its alternate screen buffer, and content shown
+  there is not part of normal scrollback, so an automated caller never sees it -- piping
+  through `| cat` alone does not reliably prevent this.
+  **Fix:** prefix every `gh` invocation with `GH_PAGER=cat` (e.g.
+  `GH_PAGER=cat gh api repos/{owner}/{repo}/issues/{n}/comments`) when running non-
+  interactively, which disables `gh`'s pager unconditionally.
+
+## References
+
+- [`resolve-pr-comments`](../../../principles/skills/resolve-pr-comments/SKILL.md) -- consumes this connector's normalized output.
+- [`agentme-edr-127`](../../127-external-system-adapter-skills.md) -- external system adapter skill rules (connector naming, Known Issues format, HITL-before-write).
+- [`agentme-edr-124`](../../124-secrets-management.md) -- credential storage and retrieval.

package/.xdrs/agentme/edrs/application/skills/github-connector/SKILL.test.md

@@ -0,0 +1,118 @@
+---
+skill: github-connector
+skill-version: "1.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: Fetch and normalize all comment kinds for a PR, happy path
+
+**Trigger / Input**
+
+Fetch all comments for `https://github.com/acme/widgets/pull/482`, a PR with one issue-level
+comment, two review (file/line) comments in one resolved thread, and one review-summary.
+
+**Expected Behaviour**
+
+The connector: (1) confirms `gh auth status` is authenticated; (2) runs the PR metadata
+read; (3) runs the issue-comments, review-comments, and reviews read commands; (4) runs one
+`gh api graphql` call to read thread resolution state; (5) returns a single normalized list
+where the issue-level comment has `kind: "issue-comment"` and `can_resolve: false`, the two
+review comments have `kind: "review-comment"`, `status: "resolved"`, and `can_resolve:
+true`, and the review-summary has `kind: "review-summary"` and `can_resolve: false`.
+
+**Assertions**
+
+- [ ] Output normalizes every fetched item to the shared record shape (id, kind, status,
+      can_reply, can_resolve, path, line, content, author, in_reply_to).
+- [ ] Output sets `can_resolve: false` for the issue-comment and the review-summary items.
+- [ ] Output sets `status: "resolved"` for the two review comments in the resolved thread,
+      derived from the GraphQL thread lookup rather than the REST response alone.
+- [ ] Connector never branches its own logic on business meaning of comment content.
+
+### Scenario 2: Reply-to-a-reply resolves to the thread root before posting
+
+**Trigger / Input**
+
+Post a reply targeting a review comment that is itself a reply (not the root) within its
+thread.
+
+**Expected Behaviour**
+
+Before posting, the connector resolves `in_reply_to` up to the thread's root comment id
+(GitHub only accepts replies anchored to the root), shows the mandatory System/Operation/
+Fields/Estimated impact confirmation using the resolved root id, and only posts via
+`gh api repos/{owner}/{repo}/pulls/{n}/comments -F in_reply_to=<root-id>` after explicit
+confirmation.
+
+**Assertions**
+
+- [ ] Connector resolves `in_reply_to` to the thread's root comment id, not the intermediate
+      reply id, before constructing the write call.
+- [ ] Connector shows the mandatory confirmation (System, Operation, Fields, Estimated
+      impact) before posting.
+- [ ] Connector does not post before receiving explicit human confirmation.
+
+### Scenario 3: Permission-denied write degrades to reply-only, no silent retry
+
+**Trigger / Input**
+
+A resolve-thread write (`gh api graphql` `resolveReviewThread` mutation) returns HTTP 403
+because the authenticated account lacks triage permission on the repository.
+
+**Expected Behaviour**
+
+Per the Known Issues entry for this symptom, the connector reports the permission gap
+plainly to the caller, does not retry the same call, and continues to allow a reply-only
+write path for that comment (an already-successful or subsequent reply post is unaffected).
+
+**Assertions**
+
+- [ ] Connector reports the permission error explicitly rather than failing silently.
+- [ ] Connector does not silently retry the failed resolve call.
+- [ ] Connector still allows a reply-only write for the same comment.
+
+### Scenario 4: No GitHub session available halts before any write
+
+**Trigger / Input**
+
+`gh auth status` reports not logged in.
+
+**Expected Behaviour**
+
+The connector runs `gh auth login --hostname github.com --git-protocol https --web`
+(non-interactive except for the one local git-credential yes/no, which the connector
+auto-accepts on its default) so the human is only asked to complete the browser/device-code
+step, and does not attempt any write operation until `gh auth status` reports an
+authenticated session. Read-only operations that do not require authentication (if any) are
+unaffected.
+
+**Assertions**
+
+- [ ] Connector does not attempt a write operation without an authenticated `gh` session.
+- [ ] Connector runs `gh auth login` with `--hostname`/`--git-protocol`/`--web` rather than
+      bare `gh auth login`, so the human is not asked the host/protocol/method questions.
+- [ ] Connector never asks for, reads, or feeds `gh` a raw PAT/token directly.
+
+### Scenario 5: gh unavailable or unauthenticated never triggers a curl/scrape fallback
+
+**Trigger / Input**
+
+Fetch PR metadata, comments, and diff for `https://github.com/acme/widgets/pull/482` while
+`gh auth status` reports not logged in (or `gh` is not installed).
+
+**Expected Behaviour**
+
+The connector does not issue any direct `curl`/HTTP request to `api.github.com`,
+`github.com`, or a `.diff`/`.patch` endpoint, and does not fetch or parse the PR's rendered
+HTML page as a substitute -- even though the target repository and PR are public. Instead it
+follows the Authentication check steps, reports the missing/failed `gh` session plainly, and
+halts every read and write until `gh auth status` reports an authenticated session.
+
+**Assertions**
+
+- [ ] Connector does not issue a `curl` or other raw HTTP request to any GitHub endpoint as
+      a substitute for `gh`.
+- [ ] Connector does not fetch or parse the PR's HTML page as a scraping fallback.
+- [ ] Connector halts reads and writes and prompts for `gh` installation/`gh auth login`
+      rather than degrading to an alternative retrieval method.

package/.xdrs/agentme/edrs/application/skills/{200-run-skill-tests → run-skill-tests}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 200-run-skill-tests
+name: run-skill-tests
 description: >
   Executes the SKILL.test.md test scenarios for a given skill, evaluates each assertion against the skill's
   actual output, and reports a pass/fail result per scenario. Activate when the user asks to test, verify,
@@ -17,7 +17,7 @@ Loads `SKILL.test.md` from a skill directory, runs each scenario by invoking the
 
 ### Phase 1: Locate and Validate SKILL.test.md
 
-1. Accept the skill path from the user (e.g., `.agents/skills/001-review` or `.xdrs/_local/adrs/principles/skills/005-my-skill`). If no path is given, ask: *"Which skill do you want to test? Provide the path to the skill directory."*
+1. Accept the skill path from the user (e.g., `.agents/skills/review` or `.xdrs/_local/adrs/principles/skills/005-my-skill`). If no path is given, ask: *"Which skill do you want to test? Provide the path to the skill directory."*
 2. Resolve the path to the directory containing `SKILL.md`. If the path is a symlink, follow it to the real directory.
 3. Check that `SKILL.test.md` exists in the same directory as `SKILL.md`. If it is missing, output:
 
@@ -91,9 +91,9 @@ A scenario passes only when every one of its assertions passes. The overall outc
 
 ## Examples
 
-**Input**: "Test the skill at `.agents/skills/001-review`"
+**Input**: "Test the skill at `.agents/skills/review`"
 
-- Phase 1 resolves the symlink → `.xdrs/_core/adrs/principles/skills/001-review/`
+- Phase 1 resolves the symlink → `.xdrs/_core/adrs/principles/skills/review/`
 - Reads `SKILL.test.md`, parses 3 scenarios
 - Executes each scenario with the target skill loaded
 - Reports per-assertion PASS/FAIL and an overall outcome

package/.xdrs/agentme/edrs/application/skills/{200-run-skill-tests → run-skill-tests}/SKILL.test.md

@@ -1,5 +1,5 @@
 ---
-skill: 200-run-skill-tests
+skill: run-skill-tests
 skill-version: "1.0"
 ---
 
@@ -8,9 +8,9 @@ skill-version: "1.0"
 ### Scenario 1: Successfully executes scenarios and reports results
 
 **Trigger / Input**
-You are an agent with the `200-run-skill-tests` skill loaded. The workspace has a skill at `.agents/skills/001-review` with both `SKILL.md` and `SKILL.test.md` present. The user says:
+You are an agent with the `run-skill-tests` skill loaded. The workspace has a skill at `.agents/skills/review` with both `SKILL.md` and `SKILL.test.md` present. The user says:
 
-"Test the skill at `.agents/skills/001-review`"
+"Test the skill at `.agents/skills/review`"
 
 **Expected Behaviour**
 1. Skill resolves the path to the real directory (following the symlink).
@@ -22,7 +22,7 @@ You are an agent with the `200-run-skill-tests` skill loaded. The workspace has
 7. Skill outputs a structured report using the mandated template with a final Outcome line.
 
 **Assertions**
-- [ ] Output contains `## Skill Test Report: 001-review`.
+- [ ] Output contains `## Skill Test Report: review`.
 - [ ] Output contains a `### Scenario` section for each scenario in `SKILL.test.md`.
 - [ ] Each scenario section lists individual assertion results as `PASS` or `FAIL`.
 - [ ] Output ends with a `## Summary` block containing `Scenarios:`, `Passed:`, `Failed:`, and `Outcome:`.
@@ -30,9 +30,9 @@ You are an agent with the `200-run-skill-tests` skill loaded. The workspace has
 ### Scenario 2: Halts with ERROR when SKILL.test.md is missing
 
 **Trigger / Input**
-You are an agent with the `200-run-skill-tests` skill loaded. The workspace has a skill directory `.xdrs/agentme/edrs/application/skills/050-create-javascript-project` that contains `SKILL.md` but no `SKILL.test.md`. The user says:
+You are an agent with the `run-skill-tests` skill loaded. The workspace has a skill directory `.xdrs/agentme/edrs/application/skills/create-javascript-project` that contains `SKILL.md` but no `SKILL.test.md`. The user says:
 
-"Run tests for `.xdrs/agentme/edrs/application/skills/050-create-javascript-project`"
+"Run tests for `.xdrs/agentme/edrs/application/skills/create-javascript-project`"
 
 **Expected Behaviour**
 1. Skill resolves the path to the directory.
@@ -49,7 +49,7 @@ You are an agent with the `200-run-skill-tests` skill loaded. The workspace has
 ### Scenario 3: Injects simulated human responses when present
 
 **Trigger / Input**
-You are an agent with the `200-run-skill-tests` skill loaded. The workspace has a skill at `.xdrs/agentme/edrs/principles/skills/refine-plan-mode` with both `SKILL.md` and `SKILL.test.md` present. Scenario 1 in that `SKILL.test.md` includes a `**Simulated Human Responses**` section with 9 ordered responses. The user says:
+You are an agent with the `run-skill-tests` skill loaded. The workspace has a skill at `.xdrs/agentme/edrs/principles/skills/refine-plan-mode` with both `SKILL.md` and `SKILL.test.md` present. Scenario 1 in that `SKILL.test.md` includes a `**Simulated Human Responses**` section with 9 ordered responses. The user says:
 
 "Test the skill at `.xdrs/agentme/edrs/principles/skills/refine-plan-mode`"
 

package/.xdrs/agentme/edrs/application/skills/{010-select-relevant-xdrs → select-relevant-xdrs}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 010-select-relevant-xdrs
+name: select-relevant-xdrs
 description: >
    Analyzes a client repository, extracts the full agentme XDR set, and excludes the records that do
    not fit the project's structure and workflow needs. Activate this skill when the user asks to

package/.xdrs/agentme/edrs/application/skills/select-relevant-xdrs/SKILL.test.md

@@ -0,0 +1,73 @@
+---
+skill: select-relevant-xdrs
+skill-version: "1.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: Install presets for a single-package Node.js library, happy path
+
+**Trigger / Input**
+
+"Install the right agentme XDR presets for this Node.js library." The repository is a single npm
+package with a Makefile and no Go code, no monorepo layout, and no deployed/long-running service.
+
+**Expected Behaviour**
+
+1. Phase 1 inventories the shipped agentme XDR files.
+2. Phase 2 analyzes the repository and detects a JavaScript/TypeScript single-package library with
+   Makefiles, no Go tooling, no monorepo structure, and no service surface.
+3. Phase 3 selects exclusions with one-line rationale each — at minimum the Go project tooling XDR
+   and the service health-check XDR — while keeping baseline/broadly applicable guidance.
+4. Phase 4 runs `npx -y agentme extract --output . --all --exclude <path> --exclude <path>` with
+   one `--exclude` flag per excluded XDR, then verifies `.xdrs/index.md`, `.xdrs/agentme/`, and
+   `AGENTS.md` exist and that every excluded path is absent from the output.
+
+**Assertions**
+
+- [ ] Output excludes `.xdrs/agentme/edrs/application/102-golang-project-tooling.md` and
+      `.xdrs/agentme/edrs/operations/401-service-health-check-endpoint.md` with a one-line
+      rationale for each.
+- [ ] Output runs `agentme extract` with `--all` plus one `--exclude` flag per excluded XDR path,
+      rather than a hand-picked include list.
+- [ ] Output verifies after extraction that `.xdrs/index.md`, `.xdrs/agentme/`, and `AGENTS.md`
+      exist and that the excluded paths are absent from the result.
+
+### Scenario 2: Extraction blocked when the package exposes no inventory metadata
+
+**Trigger / Input**
+
+Run the skill in an environment where the CLI cannot enumerate the shipped XDRs, and the package
+metadata and repository documentation also do not describe the shipped XDR set.
+
+**Expected Behaviour**
+
+Per Phase 1 step 4, since even the fallback inventory sources fail, the skill stops before
+attempting any extraction and reports that automatic selection is blocked because the package does
+not expose enough metadata in the current environment, rather than guessing an exclude list or
+forcing a full installation.
+
+**Assertions**
+
+- [ ] Output stops before running any `agentme extract` command.
+- [ ] Output reports that automatic selection is blocked due to insufficient package metadata,
+      rather than silently falling back to a default guess.
+
+### Scenario 3: Debatable exclusion is kept, not excluded
+
+**Trigger / Input**
+
+Analyzing a currently single-package repository whose README states the team is planning to split
+it into multiple applications "sometime in the future." Whether the monorepo-structure XDR still
+applies is debatable.
+
+**Expected Behaviour**
+
+Per the Edge Cases entry on debatable exclusions, since the mismatch is not concrete today, the
+skill keeps the monorepo-structure XDR in the installed set rather than excluding it on the basis
+of a possible future restructuring.
+
+**Assertions**
+
+- [ ] Output keeps `.xdrs/agentme/edrs/platform/301-monorepo-structure.md` in the installed set.
+- [ ] Output does not add it to the exclude list on the basis of a future, not-yet-concrete plan.

package/.xdrs/agentme/edrs/governance/502-contributing-guide-requirements.md

@@ -67,4 +67,4 @@ The content SHOULD stay concise and practical; do not turn `CONTRIBUTING.md` int
 ## References
 
 - [agentme-edr-301 - Monorepo structure](../platform/301-monorepo-structure.md)
-- [053-monorepo-setup skill](../platform/skills/053-monorepo-setup/SKILL.md)
+- [monorepo-setup skill](../platform/skills/monorepo-setup/SKILL.md)

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

@@ -8,11 +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)*
+- [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
 
@@ -30,15 +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
+- [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
 
@@ -72,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
@@ -90,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