feat(ops): stepie-stepwise-ops skill — production planning surface (Stepie MCP)

.agents/skills/stepie-stepwise-ops/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: stepie-stepwise-ops
+description: Stepie AKA StepWise MCP as production planning surface for termux-monorepo. Load when planning milestones, expanding goal 2087, RECON-to-step mapping, dual-gate WAIT loops, or synchronizing Stepie with LANE-MATRIX and adaptive-wait. Triggers on Stepie, StepWise, stepwise planning, goal 2087, insert_steps, session pulse plan.
+---
+
+Canonical: master `.agents/skills/stepie-stepwise-ops/SKILL.md`.
+
+# Stepie Stepwise Ops
+
+Production planning surface for `timerloggedout-spec/termux-monorepo`. Stepie holds milestones; GitHub holds evidence; dual-gate holds promote.
+
+## Role in the stack
+
+| Surface | Owns | Does not own |
+|---------|------|--------------|
+| **Stepie (this skill)** | Goals, ordered milestones, completion criteria, trigger cues, session plan notes | Code, CI, merge authority |
+| **LANE-MATRIX.md** | Tip-first PR classification (PROMOTE / WAIT / HOLD / EXTRACT / OBSERVE / SUPERSEDE) | Personal task lists |
+| **adaptive-wait** | Dual-gate before promote; stay-busy disjoint work while CI runs | Goal hierarchy |
+| **evidence-led-monorepo-ops** | Session SSOT stamp, mega policy, co-load list | StepWise tool calls |
+| **help-wanted-lane** | Foreign PR claim → follow-up → dashboard receipts | Primary monorepo goal tree |
+
+Stepie is the **planning utility**. It does not replace dual-gate or LANE-MATRIX. It makes the operator plan queryable, ordered, and evidence-linked.
+
+## Primary goal (production)
+
+- **Goal ID 2087** — `termux-monorepo development` (isPrimary).
+- Anchor step title matches the goal; leave anchor description empty or minimal (repo URL only).
+- Expand with `insert_steps` before the anchor. Near-term milestones first; distant work thinner.
+- Milestone **description** = one short completion criterion only. Methods, links, and RECON go in **notes**.
+
+## Session bootstrap (every admin session)
+
+1. Load this skill + `evidence-led-monorepo-ops` + `adaptive-wait`.
+2. `get_overview` — confirm 2087 is primary; count pending steps.
+3. RECON via GitHub connector (open PRs, #175, LANE-MATRIX tip, dual-gate status).
+4. If plan is stale vs tip or missing near-term extracts, `insert_steps` or `update_step`.
+5. Write a RECON note on the session-pulse step (HTML, evidence bullets only).
+6. Rewrite `docs/ops/LANE-MATRIX.md` on a feature branch when the tip or lane map moved.
+7. Stay busy on disjoint SSOT / skill mirrors while dual-gate runs — do not idle-poll.
+
+## Milestone design rules
+
+- Title: verb + key noun (e.g. `Dual-gate #713 slim ML extract`).
+- Description: brief verifiable completion criteria. No how-to, no examples, no resource lists.
+- `triggerContext`: 2–4 words max, cue side only (e.g. `🧪 after CI`, `📊 session start`). Omit if no reliable cue.
+- Matrix category: use `urgent_important` for dual-gate and tip-blocking work; otherwise leave unset unless operator sets it.
+- Prefer EXTRACT children over mega parents (#713 over #682).
+- Never auto-complete a step from CI green alone — record the evidence in a note, then mark completed when the criterion is met.
+
+## Tool discipline (Stepie MCP)
+
+| Intent | Tool |
+|--------|------|
+| Orient | `get_overview` |
+| Read plan | `search_step` goalId=2087 responseFormat=detailed |
+| Expand plan | `insert_steps` before anchor |
+| Record evidence | `create_note` / replace note (merged HTML) |
+| Advance status | `update_step` status=completed only after criterion met |
+| Goal context | `update_goal` description = full merged replacement |
+| Standalone errands | `create_task` (Eisenhower) — not for goal milestones |
+
+Always pass a fresh `operationId` (UUID). For updates, pass accurate `expectedUpdatedAt` when known; use null only when the tool allows and conflict is acceptable risk.
+
+## Fit with other cadences
+
+- **Mayan 13-phase / concurrent lattice (#631)**: Stepie milestones map to phase outcomes; phase parallelism lives in Actions + LANE-MATRIX, not inside one Stepie goal.
+- **Help-wanted cadence**: separate goal or tasks; link via notes (PRIMARY/FALLBACK receipts). Do not fold foreign PR claims into 2087 milestones.
+- **MoneyBall / live_catalog / model-router**: OBSERVE or EXTRACT lanes in LANE-MATRIX; Stepie only tracks the operator decision milestone if it blocks promote.
+- **Codespace agent lane / Bifrost**: host preference documented in ops docs; Stepie does not own runtime hosts.
+- **refTemplates / smods / RinDig**: reference pins under CLAUDE.md; Stepie notes may cite them, never treat as promote gates.
+- **Session SSOT pulse**: every admin session rewrites LANE-MATRIX and refreshes the Stepie RECON note. Age alone does not promote.
+
+## Maximize utility surface (production)
+
+1. **Single primary goal** for monorepo admin — avoid parallel ops goals that fragment the plan.
+2. **Tip-first ordering** — first pending milestone should unblock the current preferred extract.
+3. **Evidence in notes** — SHA, PR number, dual-gate conclusion, non-gate rationale.
+4. **Co-load contract** — this skill never authorizes YOLO merge; adaptive-wait + dual-gate still gate promote.
+5. **Collaborator parity** — canonical path is `.agents/skills/stepie-stepwise-ops/SKILL.md`; local `.grok/skills/` is mirror only.
+6. **Inventory** — after land, add row to `docs/ops/SKILLS-INVENTORY.md` under `.agents/skills/` and Admin role load list.
+7. **No HITL YOLO YEET AUTOAPPROVE** — Stepie plans do not merge PRs.
+
+## Anti-patterns
+
+- Duplicating LANE-MATRIX tables inside Stepie descriptions.
+- Completing milestones because CI is green without recording the criterion evidence.
+- Creating new Stepie goals for every PR — use steps under 2087 or independent Matrix tasks.
+- Storing secrets, PATs, or raw credential values in goal/step/note content (#184 notes-only).
+- Treating Copilot / CodeRabbit / Vercel rate-limit as promote gates.
+
+## Quick references
+
+- Priority hub: Issue **#175**
+- Dual-gate: hygiene+portability + agentic termux smoke
+- Living lane SSOT: `docs/ops/LANE-MATRIX.md`
+- Agent entry: `CLAUDE.md`
+- Inventory: `docs/ops/SKILLS-INVENTORY.md`
+- Cadence detail: `references/cadence-map.md`
+
+Agent-Identity: Grok (Administrator)
+Session stamp: 2026-09-21 15:07 PDT — tip `abaad3da`; preferred extract #713 @ `4ec03d54`.

.agents/skills/stepie-stepwise-ops/references/cadence-map.md

@@ -0,0 +1,40 @@
+# Cadence map — Stepie vs other production loops
+
+## Stepie (planning)
+
+- Holds ordered milestones for goal 2087.
+- Completion criteria + trigger cues + RECON notes.
+- Does not run CI or merge.
+
+## LANE-MATRIX (classification SSOT)
+
+- Tip-first PROMOTE / WAIT / HOLD / EXTRACT / OBSERVE / SUPERSEDE.
+- Rewritten every admin session.
+- Source of truth for which PR is preferred extract.
+
+## adaptive-wait (execution discipline)
+
+- Dual-gate before promote.
+- Stay busy on disjoint work (skill mirrors, SSOT, triage).
+- No idle poll loops.
+
+## evidence-led-monorepo-ops (session stamp)
+
+- Session tip, mega policy, co-load list, Agent-Identity.
+- Load every admin session with adaptive-wait.
+
+## help-wanted-lane
+
+- Foreign claim → PR → follow-up poll → dashboard receipts.
+- Parallel to 2087; link by note, do not merge trees.
+
+## Mayan / concurrent lattice (#631)
+
+- Multi-phase parallel work in Actions + proposals.
+- Stepie milestones express outcomes; lattice expresses concurrency.
+
+## CI dual-gate
+
+- `repo_gate` / hygiene+portability + `termux_smoke`.
+- Only promote when both SUCCESS and extract (not mega) policy satisfied.
+- Vercel rate-limit is non-gate.

.github/workflows/ops-operator-matrix-project-sync.yml

@@ -0,0 +1,161 @@
+name: Operator Matrix Project Sync
+
+# Option A: GitHub Actions plane (not Grok connector).
+# Adds issues/PRs to the Operator Matrix Projects v2 board using a
+# Project-capable token from #184 inventory (names only).
+#
+# Prerequisites (Operator, once):
+# 1. Create user/org Project: "termux-monorepo — Operator Matrix (#175)"
+# 2. Repo variable or secret PROJECT_URL =
+#    https://github.com/users/timerloggedout-spec/projects/<N>
+#    (or orgs/<org>/projects/<N>)
+# 3. Token secret with project scope:
+#    OPERATOR_GITHUB_TOKEN | OPERATOR_TOKEN | ARCHWIZ_GITHUB_TOKEN
+#
+# Templates referenced:
+# - actions/add-to-project (GitHub-maintained)
+# - github/docs automating-projects-using-actions
+# - existing dependency-phase-project-sync.yml (OPERATOR_TOKEN chain)
+
+on:
+  issues:
+    types: [opened, reopened, transferred, labeled]
+  pull_request_target:
+    types: [opened, reopened, ready_for_review, labeled]
+  workflow_dispatch:
+    inputs:
+      seed_hub:
+        description: "Also ensure hub issues/PRs are on the board (175, 184, 713, 714, 682)"
+        required: false
+        default: true
+        type: boolean
+
+concurrency:
+  group: operator-matrix-project-sync-${{ github.repository }}-${{ github.event.issue.number || github.event.pull_request.number || 'dispatch' }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  add-current:
+    name: Add current issue/PR to Operator Matrix
+    if: ${{ github.event_name != 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Resolve project URL
+        id: project
+        env:
+          FROM_VAR: ${{ vars.OPERATOR_MATRIX_PROJECT_URL }}
+          FROM_SECRET: ${{ secrets.OPERATOR_MATRIX_PROJECT_URL }}
+        run: |
+          set -euo pipefail
+          url="${FROM_VAR:-}"
+          if [ -z "$url" ]; then url="${FROM_SECRET:-}"; fi
+          if [ -z "$url" ]; then
+            echo "::notice::OPERATOR_MATRIX_PROJECT_URL not set — skip add-to-project (create Project + set repo variable)"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+
+      - name: Add to Project (actions/add-to-project)
+        if: ${{ steps.project.outputs.skip != 'true' }}
+        uses: actions/add-to-project@v1.0.2
+        with:
+          project-url: ${{ steps.project.outputs.url }}
+          # Plane A: Project-capable PAT/App token by secret name only (#184).
+          github-token: ${{ secrets.OPERATOR_GITHUB_TOKEN || secrets.OPERATOR_TOKEN || secrets.ARCHWIZ_GITHUB_TOKEN }}
+
+  seed-hub:
+    name: Seed hub items (workflow_dispatch)
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.seed_hub }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      GH_TOKEN: ${{ secrets.OPERATOR_GITHUB_TOKEN || secrets.OPERATOR_TOKEN || secrets.ARCHWIZ_GITHUB_TOKEN }}
+      PROJECT_URL: ${{ vars.OPERATOR_MATRIX_PROJECT_URL || secrets.OPERATOR_MATRIX_PROJECT_URL }}
+    steps:
+      - name: Require token + project URL
+        run: |
+          set -euo pipefail
+          if [ -z "${GH_TOKEN:-}" ]; then
+            echo "::error::No OPERATOR_GITHUB_TOKEN / OPERATOR_TOKEN / ARCHWIZ_GITHUB_TOKEN"
+            exit 1
+          fi
+          if [ -z "${PROJECT_URL:-}" ]; then
+            echo "::error::Set repo variable OPERATOR_MATRIX_PROJECT_URL to the Projects v2 URL"
+            exit 1
+          fi
+          echo "Project URL: $PROJECT_URL"
+
+      - name: Resolve project node id
+        id: proj
+        run: |
+          set -euo pipefail
+          # Accept user or org project URL forms.
+          if [[ "$PROJECT_URL" =~ /users/([^/]+)/projects/([0-9]+) ]]; then
+            OWNER="${BASH_REMATCH[1]}"
+            NUMBER="${BASH_REMATCH[2]}"
+            KIND=user
+          elif [[ "$PROJECT_URL" =~ /orgs/([^/]+)/projects/([0-9]+) ]]; then
+            OWNER="${BASH_REMATCH[1]}"
+            NUMBER="${BASH_REMATCH[2]}"
+            KIND=org
+          else
+            echo "::error::Unrecognized project URL: $PROJECT_URL"
+            exit 1
+          fi
+          if [ "$KIND" = user ]; then
+            QUERY='query($login:String!,$n:Int!){ user(login:$login){ projectV2(number:$n){ id title } } }'
+            PROJECT_ID=$(gh api graphql -f query="$QUERY" -f login="$OWNER" -F n="$NUMBER" --jq '.data.user.projectV2.id')
+            TITLE=$(gh api graphql -f query="$QUERY" -f login="$OWNER" -F n="$NUMBER" --jq '.data.user.projectV2.title')
+          else
+            QUERY='query($login:String!,$n:Int!){ organization(login:$login){ projectV2(number:$n){ id title } } }'
+            PROJECT_ID=$(gh api graphql -f query="$QUERY" -f login="$OWNER" -F n="$NUMBER" --jq '.data.organization.projectV2.id')
+            TITLE=$(gh api graphql -f query="$QUERY" -f login="$OWNER" -F n="$NUMBER" --jq '.data.organization.projectV2.title')
+          fi
+          if [ -z "$PROJECT_ID" ] || [ "$PROJECT_ID" = null ]; then
+            echo "::error::Could not resolve project id (token missing project scope or wrong number)"
+            exit 1
+          fi
+          echo "project_id=$PROJECT_ID" >> "$GITHUB_OUTPUT"
+          echo "Resolved: $TITLE ($PROJECT_ID)"
+
+      - name: Seed hub content ids
+        env:
+          PROJECT_ID: ${{ steps.proj.outputs.project_id }}
+          OWNER: ${{ github.repository_owner }}
+          REPO: ${{ github.event.repository.name }}
+        run: |
+          set -euo pipefail
+          # Hub issues + preferred extract PRs (numbers stable; node ids resolved live).
+          SEED_ISSUES=(175 184)
+          SEED_PRS=(713 714 682)
+
+          add_content() {
+            local content_id="$1"
+            local label="$2"
+            gh api graphql -f query='mutation($project:ID!,$content:ID!){
+              addProjectV2ItemById(input:{projectId:$project,contentId:$content}){
+                item { id }
+              }
+            }' -f project="$PROJECT_ID" -f content="$content_id" >/dev/null \
+              && echo "OK $label" \
+              || echo "::warning::Failed $label (may already be on board or ACL)"
+          }
+
+          for n in "${SEED_ISSUES[@]}"; do
+            nid=$(gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){
+              repository(owner:$o,name:$r){ issue(number:$n){ id title } }
+            }' -f o="$OWNER" -f r="$REPO" -F n="$n" --jq '.data.repository.issue.id // empty')
+            if [ -n "$nid" ]; then add_content "$nid" "issue #$n"; else echo "::warning::Missing issue #$n"; fi
+          done
+
+          for n in "${SEED_PRS[@]}"; do
+            nid=$(gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){
+              repository(owner:$o,name:$r){ pullRequest(number:$n){ id title } }
+            }' -f o="$OWNER" -f r="$REPO" -F n="$n" --jq '.data.repository.pullRequest.id // empty')
+            if [ -n "$nid" ]; then add_content "$nid" "PR #$n"; else echo "::warning::Missing PR #$n"; fi
+          done

docs/ops/PROJECTS-MILESTONES-WIRING.md

@@ -0,0 +1,67 @@
+# Projects & Milestones Wiring (SSOT)
+
+**Session:** 2026-09-21 15:21 PDT  
+**Agent-Identity:** Grok (Administrator)  
+**Priority hub:** Issue #175 · Credentials: Issue **#184** (names/scopes only)
+
+## Decision: Option A — GitHub Actions plane
+
+Interactive Grok connector Projects API remains 403. **Wiring is Actions-only** using Project-capable secrets by **name** (`OPERATOR_GITHUB_TOKEN` || `OPERATOR_TOKEN` || `ARCHWIZ_GITHUB_TOKEN`).
+
+| Surface | Role | Status |
+|---------|------|--------|
+| **Stepie goal 2087** | Planning utility | LIVE |
+| **Linear P-TER-1** | Execution track M1–M6 | LIVE |
+| **GHA `ops-operator-matrix-project-sync.yml`** | Add issue/PR → Operator Matrix board | **ADDED** (this PR) |
+| **GHA `dependency-phase-project-sync.yml`** | Dependency-phase Project reconcile | Existing (master-only) |
+| **Grok connector Projects** | Chat-time board ops | BLOCKED 403 — non-path |
+
+## Operator one-time setup
+
+1. Create Projects v2 board titled **termux-monorepo — Operator Matrix (#175)** (user or org).
+2. Set repo **variable** (preferred) or secret:
+   - `OPERATOR_MATRIX_PROJECT_URL` = `https://github.com/users/timerloggedout-spec/projects/<N>`
+3. Confirm Actions secret exists with **project** scope (names from #184 / ARCHWIZ doc):
+   - `OPERATOR_GITHUB_TOKEN` or `OPERATOR_TOKEN` or `ARCHWIZ_GITHUB_TOKEN`
+4. On master (after land): Actions → **Operator Matrix Project Sync** → Run workflow → seed hub.
+
+## Workflow behavior
+
+**Event path:** issue/PR opened|reopened|labeled|ready_for_review → `actions/add-to-project@v1.0.2`  
+**Dispatch path:** resolve project node id via GraphQL → `addProjectV2ItemById` for hub set `#175` `#184` `#713` `#714` `#682` (idempotent).
+
+No YOLO merge. No raw PAT in logs (secrets masking). Skip with notice if URL unset.
+
+## Vendor / template references (not vendored)
+
+| Source | Use |
+|--------|-----|
+| [actions/add-to-project](https://github.com/actions/add-to-project) | Official GitHub-maintained add issue/PR to Projects v2 |
+| [github/docs — Automating Projects using Actions](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions) | GraphQL field updates pattern |
+| [paritytech/github-issue-sync](https://github.com/paritytech/github-issue-sync) | Issue→project sync action (PROJECT_TOKEN) |
+| [suzuki-shunsuke/ghproj](https://github.com/suzuki-shunsuke/ghproj) / DEV write-up | Cross-repo gather into Projects |
+| shader-slang `pr-board-sync.yml` / `issue-board-onboard.yml` | JS GraphQL `addProjectV2ItemById` idempotent pattern |
+| In-repo `dependency-phase-project-sync.yml` | Established OPERATOR_TOKEN chain for ProjectV2 writes |
+
+Do not invent a second sync plane. Prefer official `actions/add-to-project` for the event path; keep GraphQL seed thin.
+
+## Stepie ↔ Linear map
+
+| Stepie (2087) | Linear |
+|---------------|--------|
+| RECON, Dual-gate #713, Stay-busy, HOLD, #630 | **M5 Operator Matrix + Stepie** |
+| Help-wanted, #184 | **M6 Help-wanted + Credential Hygiene** |
+
+## Events policy
+
+- Unposted chat ≠ consensus.
+- Age alone does not promote.
+- Vercel rate-limit non-gate.
+- No HITL YOLO YEET AUTOAPPROVE.
+
+## Links
+
+- Workflow: `.github/workflows/ops-operator-matrix-project-sync.yml`
+- Token SSOT: `docs/ops/ARCHWIZ-ADMIN-TOKEN.md`
+- Skill: `.agents/skills/stepie-stepwise-ops/SKILL.md`
+- Linear: https://linear.app/termux-monorepo-linear/project/termux-monorepo-hardening-dbbb30646612