M1 foundation: strategy + roadmap + research docs + 20 refined issues

.github/workflows/pm-auto-archive-closed-pr.yml

@@ -0,0 +1,84 @@
+name: pm — auto-archive closed PRs in project
+
+# When a PR closes (merged or not), archive its project board item immediately.
+# Built-in "Auto-archive items" workflow only archives by age (30+ days closed),
+# which leaves the active views cluttered with freshly-closed PRs. This Action
+# archives on close so the board stays focused on in-flight + open work.
+#
+# Required repo secret: PM_PROJECT_TOKEN (same as the other pm-* workflows)
+
+on:
+  pull_request:
+    types: [closed]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to archive (for manual re-runs)'
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  archive:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.PM_PROJECT_TOKEN }}
+      PROJECT_OWNER: litentry
+      PROJECT_NUMBER: '19'
+    steps:
+      - name: Install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
+
+      - name: Determine PR number
+        id: pr
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "number=${{ github.event.inputs.pr_number }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Resolve project ID + PR item ID
+        id: resolve
+        run: |
+          project_id=$(gh project view "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --format json | jq -r '.id')
+          echo "project_id=$project_id" >> "$GITHUB_OUTPUT"
+
+          pr_num="${{ steps.pr.outputs.number }}"
+          item_id=$(gh api graphql -f query='
+            query($owner: String!, $number: Int!) {
+              organization(login: $owner) {
+                projectV2(number: $number) {
+                  items(first: 100, orderBy: {field: POSITION, direction: ASC}) {
+                    nodes {
+                      id
+                      content { ... on PullRequest { number } }
+                    }
+                  }
+                }
+              }
+            }
+          ' -F "owner=$PROJECT_OWNER" -F "number=$PROJECT_NUMBER" \
+            | jq -r --arg n "$pr_num" '.data.organization.projectV2.items.nodes[] | select(.content.number == ($n|tonumber)) | .id' \
+            | head -n1)
+
+          if [ -z "$item_id" ] || [ "$item_id" = "null" ]; then
+            echo "info PR #$pr_num is not on the project board — nothing to archive"
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "item_id=$item_id" >> "$GITHUB_OUTPUT"
+            echo "found=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Archive the PR's project item
+        if: steps.resolve.outputs.found == 'true'
+        run: |
+          gh api graphql -f query='
+            mutation($project: ID!, $item: ID!) {
+              archiveProjectV2Item(input: { projectId: $project, itemId: $item }) {
+                item { id }
+              }
+            }
+          ' -F "project=${{ steps.resolve.outputs.project_id }}" -F "item=${{ steps.resolve.outputs.item_id }}" \
+            >/dev/null && echo "ok archived PR #${{ steps.pr.outputs.number }} from project board"

CLAUDE.md

@@ -3,7 +3,7 @@
 ## Architecture
 Rust monorepo with Cargo workspace. See `docs/arch.md` for component inventory.
 See `docs/spec/credential-backend-interface.md` for the CredentialBackend trait contract (15 methods).
-See `docs/spec/plans/development-stages.md` for the 8-stage build plan.
+See `docs/spec/plans/milestones-roadmap.md` for the M1–M7 milestone roadmap (replaces the archived v1/v2 staged plan).
 See `docs/spec/plans/execution-plan.md` for the orchestration runbook (ralph, team, ultraqa).
 Do not read folder `docs/archived`
 
@@ -48,7 +48,7 @@ Before changing any file in response to a reported failure, **reproduce the fail
 Once a local repro proves a fix is correct, **land it the same turn**: edit every affected file (search repo-wide — never assume one file), commit, push to `origin/evm`. Do not stop at "verified locally" or "fixed in one place" — the next operator running the docs will hit the same bug if the fix isn't on `origin/evm`. Pair this with the diagnosis-before-edit policy: diagnose once, fix everywhere, push immediately.
 
 ## Runbook-fix-fold-back policy
-When the user is walking through a runbook (`docs/cloud-setup.md`, `docs/stage7-demo-and-verification.md`, `docs/operator-runbook-stage7.md`, etc.) and hits a step that fails, **two things must land in the same turn**:
+When the user is walking through a runbook (`docs/cloud-setup.md`, `docs/v2-stage1-migration-and-demo.md`, `scripts/setup-broker-host.sh`, etc.) and hits a step that fails, **two things must land in the same turn**:
 
 1. The targeted fix to whatever broke (script default, env var, doc command, code).
 2. **A revision to the runbook itself** so the next operator running it top-to-bottom will not hit the same failure. The fix lives wherever the bug was; the runbook revision lives wherever the operator first encounters the broken step.
@@ -191,7 +191,7 @@ Verified live:
 
 On every session start:
 1. `jj log --limit 10 && cat harness/progress.json && bash harness/init.sh $(jq -r .current_stage harness/progress.json)`
-2. Read the stage contract for your current stage in `docs/spec/plans/development-stages.md`
+2. Read the milestone scope for the current milestone in `docs/spec/plans/milestones-roadmap.md` (the v1/v2 stage framing is archived at `docs/archived/development-stages-v2-2026-04.md`)
 3. Pick the HIGHEST-PRIORITY incomplete deliverable from `harness/features.json`
 4. Implement ONE deliverable
 5. Run tests: `cargo test -p <crate>` for the affected crate

docs/arch.md

@@ -1986,7 +1986,7 @@ flowchart TB
 - Signer host is TEE-attested. Brokers and workers pin the signer's attestation hash; mTLS handshake fails if measurement drifts.
 - Daemons reach broker + workers over public TLS. Caller authentication at workers is by cap-token, not by IP.
 
-The full bring-up runbook lives in [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) (idempotent). Operator-facing commentary in [`operator-runbook.md`](operator-runbook-stage7.md).
+The full bring-up runbook lives in [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) (idempotent; the single entry point per CLAUDE.md "Remote broker host" rule). Historical stage-7 operator commentary is archived at [`docs/archived/operator-runbook-stage7-2026-04.md`](archived/operator-runbook-stage7-2026-04.md) for reference only.
 
 ---
 
@@ -1999,7 +1999,8 @@ The full bring-up runbook lives in [`scripts/setup-broker-host.sh`](../scripts/s
 - **Stage 2 deliverable inventory** — [`spec/plans/v2-issues/issue-v2-stage-2-hardening.md`](spec/plans/v2-issues/issue-v2-stage-2-hardening.md)
 - **Payment-service design** — [`spec/plans/v2-issues/issue-payment-service-deferred.md`](spec/plans/v2-issues/issue-payment-service-deferred.md)
 - **Migration from pre-v2** — [`v2-stage1-migration-and-demo.md`](../v2-stage1-migration-and-demo.md) (historical; the migration window closed when stage 1 shipped)
-- **Operator runbook** — [`operator-runbook-stage7.md`](operator-runbook-stage7.md)
+- **Operator runbook** — [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) (idempotent). Historical: [`docs/archived/operator-runbook-stage7-2026-04.md`](archived/operator-runbook-stage7-2026-04.md).
+- **Milestone roadmap (M1-M7)** — [`spec/plans/milestones-roadmap.md`](spec/plans/milestones-roadmap.md)
 - **Cloud-side IAM + DNS + cert** — [`../cloud-setup.md`](../cloud-setup.md)
 - **Per-actor reference (agent role)** — [`wiki/agent-role-and-usage-hdkd-per-agent-omni.md`](wiki/agent-role-and-usage-hdkd-per-agent-omni.md)
 - **Upstream backend classes (per-upstream design)** — [`wiki/upstream-backend-classes-exercise-vs-distribution.md`](wiki/upstream-backend-classes-exercise-vs-distribution.md)

docs/dev-setup.md

@@ -145,7 +145,7 @@ Run through [`cloud-bootstrap.md`](./cloud-bootstrap.md) §1–§3 once per AWS
 - S3 bucket `agentkeys-mail-<ACCOUNT_ID>` with receipt rule writing inbound to `inbound/`
 - Route 53 records: three DKIM CNAMEs, MX, SPF, DMARC
 
-Manage the daemon user's long-lived AWS keys via a **named profile** in `~/.aws/credentials` (mode 0600). The broker uses the AWS SDK's default credential chain — `AWS_PROFILE` (set by `awsp` or your shell), the shared credentials file, or an EC2 instance profile via IMDS. **No long-lived AWS keys live in env vars.** See [`operator-runbook-stage7.md`](./operator-runbook-stage7.md) for the full credential story.
+Manage the daemon user's long-lived AWS keys via a **named profile** in `~/.aws/credentials` (mode 0600). The broker uses the AWS SDK's default credential chain — `AWS_PROFILE` (set by `awsp` or your shell), the shared credentials file, or an EC2 instance profile via IMDS. **No long-lived AWS keys live in env vars.** See [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) for the bring-up + credential wiring; historical credential commentary archived at [`archived/operator-runbook-stage7-2026-04.md`](./archived/operator-runbook-stage7-2026-04.md).
 
 ### 5.2 Run the broker server
 
@@ -173,7 +173,7 @@ The broker:
 3. Returns 1-hour temp creds to the caller.
 4. Logs every mint to `BROKER_AUDIT_DB_PATH` (SQLite, one row per mint).
 
-For runbook detail (start / supervise / rotate / monitor / migrate to hosted), see [`docs/operator-runbook-stage7.md`](./operator-runbook-stage7.md).
+For runbook detail (start / supervise / rotate / monitor / migrate to hosted), see [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) (idempotent; the canonical entry point).
 For the automated remote-host bootstrap, see [`scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh).
 
 ### 5.3 Hand off bearer tokens to your developers
@@ -249,14 +249,13 @@ The stage-done script is the authoritative evaluator — never self-grade. If it
 
 Providers add, remove, and reorder signup steps. When a deterministic scraper breaks, diagnose with the `/agentkeys-workflow-collection` skill — it drives a real Chrome session via `chrome-devtools-mcp` to produce a diff-ready transcript. That transcript is what feeds back into the scraper's pattern library.
 
-The longer-term plan (Stage 5b) is to detect drift automatically from telemetry and hand MCP-capable callers a fallback that their own LLM can drive — details in [`spec/plans/development-stages.md`](./spec/plans/development-stages.md) § Active.
+The longer-term plan (Stage 5b → folded into M2 vendor wedge) is to detect drift automatically from telemetry and hand MCP-capable callers a fallback that their own LLM can drive — details in [`spec/plans/milestones-roadmap.md`](./spec/plans/milestones-roadmap.md) § M2.
 
 ## 10. Further reading
 
-- [`spec/plans/development-stages.md`](./spec/plans/development-stages.md) — Shipped / Active / Planned roadmap
+- [`spec/plans/milestones-roadmap.md`](./spec/plans/milestones-roadmap.md) — M1-M7 roadmap (replaces the archived v1/v2 stage plan)
 - [`cloud-bootstrap.md`](./cloud-bootstrap.md) — one-time AWS infra (DNS, SES, S3, IAM, OIDC federation)
-- [`stage7-wip.md`](./stage7-wip.md) — broker server design + acceptance test
-- [`operator-runbook-stage7.md`](./operator-runbook-stage7.md) — start, supervise, rotate, monitor the broker
+- [`../scripts/setup-broker-host.sh`](../scripts/setup-broker-host.sh) — idempotent broker bring-up + supervise + rotate
 - [`spec/credential-backend-interface.md`](./spec/credential-backend-interface.md) — 15-method trait contract
 - [`spec/ses-email-architecture.md`](./spec/ses-email-architecture.md) — Stage 6 email pipeline deep-dive
 - [`spec/threat-model-key-custody.md`](./spec/threat-model-key-custody.md) — what the broker is defending against