lean-sdd 0.1.0__tar.gz

lean_sdd-0.1.0/.agents/.env.example

@@ -0,0 +1,15 @@
+# Copy to .agents/.env locally; never commit the populated file.
+# Skill invocations use: uv run --no-project --env-file .agents/.env -- bash ...
+# uv parses dotenv data; do not source this file or put shell commands in it.
+# Optional export prefixes are supported. Inherited environment values win.
+export GITHUB_MCP_URL="https://api.githubcopilot.com/mcp/"
+# Add your token privately here, or supply GITHUB_TOKEN from a secret manager.
+# export GITHUB_TOKEN=''
+export MCP_TOOLSETS=""
+export MCP_PROTOCOL_VERSION="2025-06-18"
+export MCP_CONNECT_TIMEOUT=10
+export MCP_TIMEOUT=30
+# Empty MCP_TOOLSETS uses endpoint defaults; verify current deployed capabilities.
+# Git SSH/HTTPS credentials are separate from the MCP token.
+# OWNER, REPO, WORKING_BRANCH, and issue/PR identities are explicit workflow
+# arguments. Bind them in the calling shell after selection/readback, not here.

lean_sdd-0.1.0/.agents/README.md

@@ -0,0 +1,139 @@
+# Lean-SDD workflow setup
+
+The complete orchestration is in [AGENTS.md](../AGENTS.md). Engineering rules
+live in [CONSTITUTION.md](../CONSTITUTION.md) and
+[CODING_STANDARDS.md](../CODING_STANDARDS.md). Read these before implementation.
+
+## Layout and prerequisites
+
+Paths are relative to the adopting project root. Six skills under `skills/`
+provide Bash entry points; shared helpers live in `lib/`. Scripts perform
+individual operations, while the agent owns sequencing and human approval.
+
+The workflow requires uv, Bash 4 or newer, Git, curl, jq, and standard shell tools
+including awk, grep, and mktemp. On systems shipping older Bash, install a
+compatible version and make it available as `bash`. Git uses separate SSH/HTTPS
+credentials. uv loads the local environment file for skill invocations, even
+when the application uses another language. Python projects also supply their
+declared validation tools; the Bash skills have no Python package dependencies.
+
+Supply an already provisioned GitHub repository and explicitly select its
+owner/repository and existing working/base branch. Both effective origin fetch
+and push URLs must identify that repository. No base defaults to `main`.
+Provisioning and remote replacement are outside this workflow.
+
+`lean-sdd doctor` performs local diagnostics without loading `.env`, contacting
+GitHub, running project code, or proving readiness. A missing credential is
+reported as a warning so installation can be inspected before credentials are
+configured. Local warnings still need resolution where relevant to live use.
+
+## Environment and capability verification
+
+Prepare an untracked `.agents/.env` from [.env.example](.env.example) without
+overwriting an existing file. Add `GITHUB_TOKEN` privately, or provide it through
+your environment/secret manager. The installer never creates or copies secrets.
+In a new worktree, provision this local file separately; untracked files do not
+arrive with a checkout. Keep it even when all settings are supplied externally,
+because the explicit `--env-file` path must exist.
+
+Invoke every skill from the project root with:
+
+```bash
+uv run --no-project --env-file .agents/.env -- \
+    bash .agents/skills/get-issue/scripts/get-issue.sh \
+        "$OWNER" "$REPO" "$ISSUE_NUMBER"
+```
+
+This example requires the actual retained issue identity, bound in the calling
+shell. uv loads dotenv data into the child process without executing it as shell
+code. The Bash scripts themselves do not auto-load configuration. `--no-project`
+prevents application project discovery/synchronization for these Bash commands.
+Existing environment variables take precedence over matching `.env` entries;
+remove a stale exported value explicitly if you intend to use the file's value.
+Do not source `.env`, print it, enable shell tracing, or place tokens in arguments.
+
+The calling shell expands `"$OWNER"`, paths, and other arguments **before** uv
+loads `.env`. Keep repository/base selection and retained issue/PR state out of
+that file and bind them explicitly before invocation. Loading secrets for one
+command does not export them into subsequent Codex shell commands; use the
+prefix on every invocation. A uv failure stops dependent work without bypassing
+the loader or retrying a write.
+
+Store result JSON in a private, durable directory outside the worktree; use
+`umask 077` and parse JSON with jq, never source or evaluate it.
+
+Before live operations, verify the deployed complete schemas, both phase
+contracts, and identity through the actual Bash libraries. Bind `AGENT_DIR` to
+this project's absolute `.agents` path and `EVIDENCE_DIR` to an existing private
+directory outside the worktree in the calling shell. This example performs MCP
+reads only and passes those paths as data into a single uv-managed Bash process:
+
+```bash
+uv run --no-project --env-file .agents/.env -- \
+    bash -s -- "$AGENT_DIR" "$EVIDENCE_DIR" <<'BASH'
+set -euo pipefail
+umask 077
+AGENT_DIR=$1
+EVIDENCE_DIR=$2
+source "$AGENT_DIR/lib/github-mcp.sh"
+source "$AGENT_DIR/lib/github-pr.sh"
+mcp_connect "$GITHUB_MCP_URL" "$GITHUB_TOKEN" > "$EVIDENCE_DIR/initialize.json"
+mcp_list_tools > "$EVIDENCE_DIR/tools.json"
+github_mcp_check_capabilities "$EVIDENCE_DIR/tools.json"
+c_phase=publication
+c_capabilities "$EVIDENCE_DIR/tools.json"
+c_phase=merge
+c_capabilities "$EVIDENCE_DIR/tools.json"
+mcp_call get_me '{}' > "$EVIDENCE_DIR/identity.json"
+BASH
+```
+
+To check the loaded configuration locally without printing values or contacting
+GitHub, use the installed CLI through the same loader:
+
+```bash
+uv run --no-project --env-file .agents/.env -- lean-sdd doctor .
+```
+
+Plain `lean-sdd doctor` still inspects only its inherited environment; it does
+not parse `.env` itself. Neither form proves credential validity or permission.
+
+The foundation and phase checks require the actual tools and fields consumed by
+the scripts, including `expectedHeadSha` protection and merge-commit support.
+Unsupported capabilities stop dependent work without a direct API or CLI
+fallback. Identity access alone does not establish write, merge, or Git push
+permission. Do not publish personal identity or session evidence.
+
+## Using the workflow
+
+Read the corresponding `SKILL.md` before each operation and require exit 0 before
+advancing. `AGENTS.md` defines three distinct approval gates:
+
+1. Create and verify the full issue; stop for implementation approval. Retrieve
+   it again after approval, recheck the engineering rules, and prepare its branch.
+2. Implement, validate, commit, and record the implementation checkpoint; stop
+   for publication approval.
+3. Publish and verify the PR, retain the complete successful JSON result, and
+   record the PR checkpoint; stop for separate merge approval.
+4. Merge only the retained approved source, verify remote results and local base
+   synchronization, record finalization, then separately close/read back the issue.
+
+A failed operation stops dependent work. Preserve known remote effects and
+uncertainty, following the failure checkpoint rules in `AGENTS.md`. Do not
+blindly retry uncertain writes or substitute new observations for approved state.
+
+## Validation and readiness
+
+The adopting Python project supplies its own source, tests, `pyproject.toml`,
+and `uv.lock`. Required commands are defined in `AGENTS.md`: pytest, Ruff linting
+and formatting, and mypy through `uv run`. The installer does not create an
+application scaffold or execute those commands in the target project.
+
+Verify current server capabilities and repository permissions before live use.
+Installer tests and local diagnostics do not establish those permissions.
+
+Operational references:
+
+- [MCP transport contract](github-mcp-contract.md)
+- [Issue and branch contract](github-issue-contract.md)
+- [Publication and merge contracts](skills/finalize-implementation/references/phase-contracts.md)

lean_sdd-0.1.0/.agents/github-issue-contract.md

@@ -0,0 +1,83 @@
+# GitHub issue and branch contract
+
+## Inputs and entry points
+
+Paths below are relative to the adopting project root. Every
+entry point is Bash, exits nonzero on failure with concise stderr, and emits one
+JSON object on stdout only for success. Require uv for environment loading,
+Bash, jq, and curl for MCP, and Git for branch preparation. From the project root,
+prefix each entry point below with
+`uv run --no-project --env-file .agents/.env -- bash .agents/skills/`.
+uv loads `GITHUB_MCP_URL` and `GITHUB_TOKEN` from the untracked environment file,
+preserving values already exported. Bind explicit arguments before invoking uv;
+do not source `.env` or returned data as arbitrary code. See
+[environment setup](README.md#environment-and-capability-verification).
+The shared transport owns MCP sessions, requests, timeouts, and cleanup. Issue
+scripts use owning-shell calls with output redirected to private temporary files.
+
+| Operation | Invocation after the uv/Bash prefix above | Success contract |
+| --- | --- | --- |
+| Discovery | `list-repositories/scripts/list-repositories.sh "$QUERY"` | query, normalized repositories, total_count, pages, incomplete_results/reasons |
+| Create | `create-issue/scripts/create-issue.sh "$OWNER" "$REPO" "$TITLE" "$BODY"` | full normalized issue and returned database issue_id |
+| Read | `get-issue/scripts/get-issue.sh "$OWNER" "$REPO" "$ISSUE_NUMBER"` | full normalized issue |
+| Comment | `update-issue/scripts/comment-issue.sh "$OWNER" "$REPO" "$ISSUE_NUMBER" "$COMMENT"` | explicit issue identity, returned comment_id/comment_url |
+| Close | `update-issue/scripts/close-issue.sh "$OWNER" "$REPO" "$ISSUE_NUMBER"` | explicit issue identity, returned issue_url, verified state=closed |
+| Branch | `git-change-workflow/scripts/prepare-change-branch.sh "$OWNER" "$REPO" "$ISSUE_NUMBER" "$WORKING_BRANCH"` | owner, repo, issue_number, issue_reference, BRANCH, WORKING_BRANCH, starting SOURCE_COMMIT |
+
+A normalized issue has `owner`, `repo`, positive numeric `issue_number`, returned
+`issue_url`, complete `title`/`body`, observed `state`, optional observed
+`updated_at`, `issue_reference=owner/repo#number`, and `BRANCH=gh-number`.
+Numbers must be canonical positive decimal integers of at most 15 digits, within
+jq's exact numeric range. Database issue/comment IDs remain strings. Missing or
+null bodies fail; an actual empty string is preserved. GitHub URL identity is
+checked case-insensitively against the explicitly selected repository.
+
+`lib/github-identity.sh` contains lexical identity and canonical Git remote
+validation. `lib/github-issues.sh` contains the narrow shared MCP domain decoder
+and issue identity checks. Structured content must match the expected type
+(object by default; pull-request helpers request arrays for PR/review lists).
+Accompanying text, if present, must decode to that same value. Otherwise require
+exactly one text JSON value of that type. Ambiguous representations are errors.
+
+Discovery calls `get_me` then `search_repositories` with the exact caller query,
+`minimal_output=false`, `perPage=100`, and successive pages. GitHub documents a
+[1,000-result search boundary](https://github.com/github/docs/blob/main/content/rest/search/search.md).
+Repeated results, changed totals, premature endings, server incomplete flags,
+and that boundary are explicit reasons for incompleteness. Empty results are
+valid. Repository records preserve owner/name/URL and optional visibility,
+private, and archived metadata; they never assert write access or select a repo.
+
+Branch preparation checks both effective fetch and push destinations using
+`git remote get-url --all origin` and `git remote get-url --push --all origin`,
+including Git's URL rewriting. Exactly one supported canonical GitHub URL each
+must match the selected repository. SSH host aliases and local remotes are not
+identity proof. The script never rewrites remotes or injects MCP credentials.
+It requires attached HEAD, writable Git metadata, a clean worktree (including
+untracked files), an existing local explicit base, and an absent issue branch.
+It synchronizes only with `pull --ff-only`, rejects a local-ahead result, then
+creates the branch at the fetched commit. Failures preserve and report actual
+state, including when switching or fetching already happened. Git transport
+errors are summarized because raw errors can expose credential-bearing URLs.
+
+## Workflow gates
+
+- After creation, stop for implementation approval; read the current issue anew
+  and recheck the constitution before branch preparation. Preserve the full
+  current plan and explicit owner/repo/number throughout.
+- Use `update-issue/SKILL.md` templates for implementation, pull-request,
+  finalization, and failure checkpoints, populated only with actual facts.
+- Implementation checkpoint success precedes separate publication approval.
+  Successful publication and PR checkpoint precede separate merge approval.
+  Retain actual publication values, including the full implementation
+  source SHA and explicit working branch, across the merge gate. The branch
+  preparation SOURCE_COMMIT is only its starting commit.
+- The merge script must use the schema-verified `expectedHeadSha` for the
+  approved merge and verify the remote merge and local synchronization before
+  finalization.
+- Use non-closing `owner/repo#number` references in commits/PR descriptions.
+  Closure remains a separate `update-issue` operation, invoked only after
+  the finalization comment succeeds. A confirmed update alone is insufficient;
+  targeted readback must confirm the same issue closed.
+- A failed comment stops without recursive audit. Unconfirmed closure stops
+  without assuming open/closed or adding a failure comment. Unknown create/write
+  outcomes must be reconciled, never automatically retried.

lean_sdd-0.1.0/.agents/github-mcp-contract.md

@@ -0,0 +1,152 @@
+# GitHub MCP transport contract
+
+## Required server capabilities
+
+Verify the deployed tool schemas and authenticated identity before live
+operations. Follow [setup](README.md) for verification commands. Input schemas
+alone do not establish response fields or repository permissions.
+
+| Required operation | Advertised tool and input contract |
+| --- | --- |
+| Repository discovery | `search_repositories`: `query`, `page`, `perPage` |
+| Authenticated identity | `get_me`: empty arguments |
+| Issue create/update | `issue_write`: `method` enum includes `create`, `update`; `owner`, `repo`, `issue_number`, `title`, `body` |
+| Issue read | `issue_read`: `method=get`, `owner`, `repo`, `issue_number` |
+| Issue close | `issue_write`: `method=update`, `state=closed`, `state_reason=completed`; verify afterward with `issue_read` |
+| Audit comment | `add_issue_comment`: `owner`, `repo`, `issue_number`, `body` (do not use the reaction alternatives) |
+| PR create | `create_pull_request`: `owner`, `repo`, `title`, `body`, `head`, `base` |
+| PR read | `pull_request_read`: `method=get`, `owner`, `repo`, `pullNumber` |
+| PR list | `list_pull_requests`: `owner`, `repo`, `head`, `base`, `state`, `page`, `perPage` |
+| PR merge | `merge_pull_request`: `owner`, `repo`, `pullNumber`, `merge_method=merge`, `expectedHeadSha` |
+
+`issue_write.method` advertises `create` and `update`. `issue_read.method`
+advertises `get`, `get_comments`, `get_sub_issues`, `get_parent`, `get_labels`.
+`pull_request_read.method` advertises `get`, `get_diff`, `get_status`,
+`get_files`, `get_commits`, `get_review_comments`, `get_reviews`,
+`get_comments`, `get_check_runs`.
+
+`expectedHeadSha` is a string property in the actual merge input schema.
+Although the server marks it optional, **the merge script must require the
+retained approved SOURCE_COMMIT and always send it**. A preceding read cannot
+replace that atomic expected-head safeguard.
+
+## Transport interface
+
+Source `lib/mcp.sh` once in the shell that owns the session. Public functions
+return one JSON success object on stdout, concise diagnostics on stderr, and a
+nonzero status on failure. Capture their stdout with redirection; do not put
+public calls in command substitutions, pipelines, or background subshells.
+The library checks the owning Bash process and rejects that misuse.
+
+Bind `output_dir` to an existing private directory in the calling shell, then
+load configuration into the Bash process that will own the MCP session:
+
+```bash
+uv run --no-project --env-file .agents/.env -- \
+    bash -s -- "$output_dir" <<'BASH'
+set -euo pipefail
+output_dir=$1
+source .agents/lib/mcp.sh
+source .agents/lib/github-mcp.sh
+umask 077
+mcp_connect "$GITHUB_MCP_URL" "$GITHUB_TOKEN" > "$output_dir/initialize.json"
+mcp_list_tools > "$output_dir/tools.json"
+github_mcp_check_capabilities "$output_dir/tools.json"
+mcp_call get_me '{}' > "$output_dir/identity.json"
+# Reading completed output with $(jq ...) is safe: it changes no session state.
+BASH
+```
+
+- `mcp_connect <endpoint> <token>` resets connection state, initializes, verifies
+  the negotiated version and server metadata/tools capability, sends the
+  initialized notification, then returns the complete initialize result.
+- `mcp_list_tools` follows every cursor and returns `{"tools":[...]}` only after
+  complete discovery. Repeated cursors, duplicate names, malformed pages and
+  more than 100 pages fail; no partial list is emitted.
+- `mcp_call <tool-name> <arguments-json>` accepts one JSON object, returns the
+  **complete MCP tool result**, and does not parse text into domain data.
+- `github_mcp_check_capabilities <tools-json-file>` checks the narrow input
+  contract above. Its success object explicitly says write access is unverified.
+  Missing tools, methods or fields block dependent operations. The integrated
+  setup also runs `c_capabilities` for publication and merge from
+  `lib/github-pr.sh` to check PR diagnostics/pagination and `get_commit`.
+
+IDs are allocated before the HTTP subprocess runs, in the owning shell:
+initialize uses 1; subsequent requests use 2, 3, etc. Notifications have no ID.
+Each connection owns its optional session ID and negotiated protocol.
+
+The supported protocol versions are `2025-06-18` (default) and `2025-03-26`.
+An unknown or absent negotiated version is an error. The implementation follows
+[MCP Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
+and [initialization](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle).
+It supports plain JSON and terminated SSE message/default events, including
+multiline data and CRLF. It validates one JSON-RPC envelope per message,
+correlates responses, ignores unrelated events/notifications, and rejects
+malformed/incomplete messages, duplicate matching responses, or server requests
+for capabilities it does not advertise. It does not implement stream replay,
+background listening, sampling, elicitation, or a general MCP SDK.
+
+Requests use only the supplied HTTPS endpoint. Redirects and retries are
+disabled, and curl's configuration file is disabled. `MCP_CONNECT_TIMEOUT`
+(default 10) and `MCP_TIMEOUT` (default 30) accept integer seconds from 1 to 300.
+`MCP_TOOLSETS`, when nonempty, is sent as `X-MCP-Toolsets`; any selection must
+be verified again rather than assumed available. The verified configuration
+uses the endpoint defaults. A GitHub MCP hostname is not a direct REST API.
+
+Each HTTP subprocess owns a mode-0700 temporary directory and mode-0600
+credential/payload files. Success, failure and handled interrupts clean those
+files without replacing caller traps. As with any process, SIGKILL cannot run
+cleanup. Callers must keep shell tracing off and protect their own success
+output files, which can contain issue text. Tokens are not placed in curl's
+argument vector; raw error bodies and curl diagnostics are never printed.
+
+Network/HTTP, protocol, session, parsing and application errors propagate.
+Failures invalidate the usable connection. An HTTP 404 requires an explicit
+new connection before any later request. A write whose response is lost has
+an **unconfirmed outcome**: no automatic retry or replay is attempted. The
+error identifies the method/tool and request ID, without arguments or server
+body. The orchestrator must stop and reconcile under its explicit policy.
+
+## Shared domain contracts
+
+These are **required normalized outputs**, not invented GitHub response schemas.
+The issue and pull-request helpers map observed MCP results, including text
+JSON or structured content, and must retain evidence for any newly consumed
+server fields. Parse JSON as data with jq; never source or eval it. GitHub
+service operations use only the configured official GitHub MCP server.
+
+Identity inputs are explicit `owner`, `repo` and a positive integer
+`issue_number`. Retain the returned issue URL. The human reference is
+`owner/repo#number`; the issue branch is `gh-<issue-number>`. GitHub opaque IDs,
+issue numbers and PR numbers are distinct. Never infer the repository from a
+search hit, the issue from a branch, or `WORKING_BRANCH` from a default.
+
+| Result | Fields the domain implementation must supply and validate |
+| --- | --- |
+| Issue | `owner`, `repo`, `issue_number`, `issue_url`, complete `title`, complete `body`, observed `state` |
+| Comment | `owner`, `repo`, `issue_number`, returned `comment_id` |
+| Discovery | `repositories` with returned identities/URLs; actual pagination and incomplete-result indication; never silently present partial results as complete |
+| Publication | `owner`, `repo`, `issue_number`, `issue_url`, `PR_ID` (PR number), `PR_URL`, `SOURCE_COMMIT`, `BRANCH`, `WORKING_BRANCH` |
+| Finalization | retained publication identity, verified `merged` result, actual `merge_commit`, actual local synchronization result and working-branch commit |
+| Closure | explicit repository/issue identity and observed `state=closed`; otherwise an explicit unconfirmed outcome with nonzero exit |
+
+Validate actual identities against requested/retained inputs, required field
+presence and types, positive integer numbers, full specification text, returned
+URLs and observed state before emitting success. Absent fields, `isError`,
+wrong identity, malformed data or ambiguous output cannot become success.
+Transport success alone does not establish domain success. Preserve approved
+publication values literally across approval gates. Finalization must verify
+both the remote merge and the actual local synchronization outcome; successful
+write submission is insufficient to claim merge or closure.
+
+## Validation and deployment prerequisites
+
+Run `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .`,
+`uv run mypy .`, and `bash -n` on the two library scripts. Production never
+loads the fixtures or Python test code.
+
+Remaining deployment prerequisites: explicitly selected GitHub repository,
+appropriate token/policy access to that repository, separately working Git
+SSH/HTTPS credentials, the applicable approvals and
+verification of live operations. Repository provisioning and remote replacement
+are outside this workflow.

lean_sdd-0.1.0/.agents/lib/github-identity.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Shared lexical identity checks. No network, Git, or shell evaluation of data.
+github_error() {
+    printf 'ERROR: GitHub %s\n' "$1" >&2
+    return 1
+}
+
+github_repository_input() {
+    [[ $# == 2 && "$1" =~ ^[A-Za-z0-9][A-Za-z0-9-]{0,38}$ && "$1" != *- && "$1" != *--* &&
+       "$2" =~ ^[A-Za-z0-9_.-]{1,100}$ && "$2" != . && "$2" != .. ]] || {
+        github_error 'explicit valid owner and repository are required'; return 1;
+    }
+}
+
+github_issue_input() {
+    [[ $# == 3 ]] || { github_error 'owner, repository and issue number are required'; return 1; }
+    github_repository_input "$1" "$2" || return 1
+    # Bound integers to exact jq/JSON numeric representation; no leading zeros.
+    [[ "$3" =~ ^[1-9][0-9]{0,14}$ ]] || {
+        github_error 'issue number must be a positive integer of at most 15 digits'; return 1;
+    }
+}
+
+github_text_input() {
+    [[ $# == 1 && "$1" =~ [^[:space:]] ]] || {
+        github_error 'nonempty meaningful text is required'; return 1;
+    }
+}
+
+# Output canonical owner/repo only. Credential-bearing URLs are never printed.
+# get-url callers must supply Git's expanded effective URL, not raw config.
+github_remote_identity() {
+    local url="$1" path='' authority=''
+    case "$url" in
+        https://*)
+            path="${url#https://}"; authority="${path%%/*}"
+            [[ "${authority##*@}" == github.com ]] || return 1
+            [[ "$path" == */* ]] || return 1
+            path="${path#*/}"
+            ;;
+        git@github.com:*) path="${url#git@github.com:}" ;;
+        ssh://git@github.com/*) path="${url#ssh://git@github.com/}" ;;
+        ssh://git@github.com:22/*) path="${url#ssh://git@github.com:22/}" ;;
+        *) return 1 ;;
+    esac
+    path="${path%.git}"
+    [[ "$path" == */* && "${path#*/}" != */* ]] || return 1
+    github_repository_input "${path%%/*}" "${path#*/}" 2>/dev/null || return 1
+    printf '%s\n' "${path,,}"
+}

lean_sdd-0.1.0/.agents/lib/github-issues.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Helpers for the B executable entry points. Each entry point owns this scratch
+# directory and EXIT trap; A's HTTP library preserves these caller traps.
+source "$(dirname -- "${BASH_SOURCE[0]}")/github-identity.sh"
+source "$(dirname -- "${BASH_SOURCE[0]}")/mcp.sh"
+
+_GITHUB_SCRATCH=''
+
+github_connect() {
+    [[ -n "${GITHUB_MCP_URL:-}" && -n "${GITHUB_TOKEN:-}" ]] || {
+        github_error 'GITHUB_MCP_URL and GITHUB_TOKEN are required'; return 1;
+    }
+    umask 077
+    _GITHUB_SCRATCH=$(mktemp -d "${TMPDIR:-/tmp}/lean-sdd-github.XXXXXXXX") || return 1
+    trap 'rm -rf -- "$_GITHUB_SCRATCH"' EXIT
+    trap 'exit 130' INT
+    trap 'exit 143' TERM
+    trap 'exit 129' HUP
+    mcp_connect "$GITHUB_MCP_URL" "$GITHUB_TOKEN" > "$_GITHUB_SCRATCH/initialize.json"
+}
+
+# Decode exactly one value of the requested object/array type (object default).
+# Conflicting structured/text output is ambiguous; C consumes PR/review arrays.
+github_call() {
+    local result_type="${3:-object}"
+    [[ "$result_type" == object || "$result_type" == array ]] || return 2
+    mcp_call "$1" "$2" > "$_GITHUB_SCRATCH/result.json" || return 1
+    if ! jq -e --arg expected_type "$result_type" '
+        def text_object:
+            if (.content | length) != 1 or .content[0].type != "text" then error("content")
+            else .content[0].text | fromjson | if type == $expected_type then . else error("type") end end;
+        if has("structuredContent") then
+            .structuredContent as $data |
+            if ($data | type) != $expected_type then error("type")
+            elif (.content | length) == 0 then $data
+            elif text_object == $data then $data else error("conflict") end
+        else text_object end
+    ' "$_GITHUB_SCRATCH/result.json" > "$_GITHUB_SCRATCH/data.json" 2>/dev/null; then
+        github_error 'malformed or ambiguous tool data'
+        return 1
+    fi
+}
+
+# Full issue_read shape, verified through MCP. A missing/null body is not an
+# empty body: callers must not invent an authoritative specification.
+github_normalize_issue() {
+    local owner="$1" repo="$2" number="$3"
+    if ! jq -ce --arg owner "$owner" --arg repo "$repo" --argjson number "$number" '
+        select(.number == $number and (.number | type == "number" and floor == . and . > 0)) |
+        select(.html_url | type == "string") |
+        select((.html_url | ascii_downcase) == ("https://github.com/" + $owner + "/" + $repo + "/issues/" + ($number|tostring) | ascii_downcase)) |
+        select((has("pull_request")|not) and ((has("__typename")|not) or .__typename == "Issue")) |
+        select((.title | type == "string" and test("\\S")) and (.body | type == "string")) |
+        select(.state == "open" or .state == "closed") |
+        select((has("repository_url")|not) or
+            (.repository_url | ascii_downcase) == ("https://api.github.com/repos/" + $owner + "/" + $repo | ascii_downcase)) |
+        select((has("updated_at")|not) or (.updated_at | type == "string" and length > 0)) |
+        {owner:$owner,repo:$repo,issue_number:.number,issue_url:.html_url,title,body,state,
+         issue_reference:($owner + "/" + $repo + "#" + ($number|tostring)),BRANCH:("gh-" + ($number|tostring))}
+    ' "$_GITHUB_SCRATCH/data.json" > "$_GITHUB_SCRATCH/issue.json" 2>/dev/null; then
+        github_error 'issue identity, entity type, specification or state is invalid'
+        return 1
+    fi
+    # Preserve optional observed modification metadata; never infer a timestamp.
+    jq --slurpfile raw "$_GITHUB_SCRATCH/data.json" '
+        if $raw[0] | has("updated_at") then . + {updated_at:$raw[0].updated_at} else . end
+    ' "$_GITHUB_SCRATCH/issue.json"
+}
+
+github_read_issue() {
+    local arguments=''
+    arguments=$(jq -cn --arg owner "$1" --arg repo "$2" --argjson number "$3" \
+        '{owner:$owner,repo:$repo,issue_number:$number,method:"get"}') || return 1
+    github_call issue_read "$arguments" || return 1
+    github_normalize_issue "$1" "$2" "$3"
+}
+
+# Write results currently return id (database ID as text) and url, not an issue
+# number. Extract the number only from a returned, repository-validated issue URL.
+github_write_identity() {
+    local owner="$1" repo="$2" expected="${3:-}"
+    if ! jq -ce --arg owner "$owner" --arg repo "$repo" --arg expected "$expected" '
+        select((.id | type == "string" and test("^[1-9][0-9]*$")) and (.url | type == "string")) |
+        select((has("pull_request")|not) and ((has("__typename")|not) or .__typename == "Issue")) |
+        . as $raw | .url | capture("^https://github.com/(?<owner>[A-Za-z0-9-]+)/(?<repo>[A-Za-z0-9_.-]+)/issues/(?<number>[1-9][0-9]{0,14})$") |
+        select((.owner|ascii_downcase) == ($owner|ascii_downcase) and (.repo|ascii_downcase) == ($repo|ascii_downcase)) |
+        select($expected == "" or .number == $expected) |
+        select(($raw|has("number")|not) or $raw.number == (.number|tonumber)) |
+        {owner:$owner,repo:$repo,issue_number:(.number|tonumber),issue_url:$raw.url,issue_id:$raw.id}
+    ' "$_GITHUB_SCRATCH/data.json" 2>/dev/null; then
+        github_error 'write returned no reliable issue identity; outcome unconfirmed; do not retry'
+        return 1
+    fi
+}

lean_sdd-0.1.0/.agents/lib/github-mcp.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Validate the narrow B/C capability contract against actual mcp_list_tools JSON.
+# Does not establish permissions, call tools, normalize domain data, or load tests.
+# Usage: github_mcp_check_capabilities <tools-json-file>
+
+github_mcp_check_capabilities() {
+    [[ $# == 1 && -r "$1" ]] || {
+        printf 'ERROR: GitHub MCP capability check requires a readable tools JSON file\n' >&2
+        return 2
+    }
+    local missing=''
+    if ! missing=$(jq -ers '
+        if length != 1 or (.[0].tools | type) != "array" then error("invalid") else .[0] end |
+        .tools as $tools |
+        def schema($name):
+            [$tools[] | select(.name == $name)] |
+            if length == 1 then .[0].inputSchema else null end;
+        def fields($name; $fields):
+            schema($name) as $schema |
+            if $schema.type != "object" then [$name + ": missing/duplicate tool or invalid schema"]
+            else [$fields | to_entries[] | . as $field |
+                select($schema.properties[$field.key].type != $field.value) |
+                $name + "." + $field.key + ": missing/incompatible field"] end;
+        def enum($name; $field; $values):
+            (schema($name).properties[$field].enum // []) as $actual |
+            [$values[] | select(. as $value | $actual | index($value) == null) |
+             $name + "." + $field + ": missing enum " + .];
+        [fields("get_me"; {}),
+         fields("search_repositories"; {query:"string",page:"number",perPage:"number"}),
+         fields("issue_write"; {owner:"string",repo:"string",method:"string",issue_number:"number",title:"string",body:"string",state:"string",state_reason:"string"}),
+         fields("issue_read"; {owner:"string",repo:"string",method:"string",issue_number:"number"}),
+         fields("add_issue_comment"; {owner:"string",repo:"string",issue_number:"number",body:"string"}),
+         fields("create_pull_request"; {owner:"string",repo:"string",title:"string",body:"string",head:"string",base:"string"}),
+         fields("pull_request_read"; {owner:"string",repo:"string",method:"string",pullNumber:"number"}),
+         fields("list_pull_requests"; {owner:"string",repo:"string",head:"string",base:"string",state:"string",page:"number",perPage:"number"}),
+         fields("merge_pull_request"; {owner:"string",repo:"string",pullNumber:"number",expectedHeadSha:"string",merge_method:"string"}),
+         enum("issue_write"; "method"; ["create","update"]),
+         enum("issue_write"; "state"; ["open","closed"]),
+         enum("issue_write"; "state_reason"; ["completed"]),
+         enum("issue_read"; "method"; ["get"]),
+         enum("pull_request_read"; "method"; ["get"]),
+         enum("merge_pull_request"; "merge_method"; ["merge"])] | add | join("; ")
+    ' "$1" 2>/dev/null); then
+        printf 'ERROR: malformed GitHub MCP capability data\n' >&2
+        return 1
+    fi
+    if [[ -n "$missing" ]]; then
+        printf 'ERROR: GitHub MCP capability unavailable: %s; dependent B/C/D blocked\n' "$missing" >&2
+        return 1
+    fi
+    printf '{"schema_verified":true,"write_access_verified":false}\n'
+}