| name | implement-milestone |
| description | Use to execute a single milestone (or GitHub Project phase) of work — feature branch off main, commits per enumerated task, PR review with gov-infra verifiers, merge to main. Runs one milestone at a time. Deploys themselves (CDK lab/live, on-chain Sepolia/mainnet, managed-instance rollout) are handled separately. |
Implement a milestone
This skill moves host work through code, review (with CI-enforced gov-infra verifiers), and merge to main. host uses a single-main branch model with feature branches. Once merged, stage deploys (theory app up --stage <stage>), on-chain deploys (Sepolia → Safe-ready mainnet), and managed-instance rollouts follow per the roadmap.
Hard preconditions
Do not start without all of the following:
- A specific milestone named, from
plan-roadmap or a GitHub Project phase
- Clean working tree on
main at a known-green commit
- MCP tools healthy. Call
memory_recent first.
go test ./... passes on maingo vet ./... passesgofmt -l . returns emptycdk synth --context stage=lab succeeds if the milestone touches CDKhardhat test passes in contracts/ if the milestone touches Solidity- Slither + solhint clean if Solidity touched
web/ build + CSP validation pass if web/ touched- gov-infra verifiers pass (current evidence state aligned with pack.json)
- Enumerated tasks are in-mission — not scope growth
- Specialist walks complete for governance / provisioning / soul / trust / framework / advisor-brief work
- Advisor-dispatched milestones have Aron's authorization from
review-advisor-brief recorded
If any precondition fails, stop and surface.
Branch and PR setup
One feature branch per milestone. One PR per milestone. One commit per task.
- Branch name: observed patterns —
aron/issue-<N>-<topic>, codex/<topic>, issue/<N>-<topic>, chore/<maintenance>
- Branched from:
main at a known-green commit
- PR target:
main
- PR title: clear, Conventional Commits style encouraged
- Open PR as draft
PR description template:
## Milestone
<short-name> — <goal from roadmap or project README>
## Classification
<security / tenant-isolation / on-chain-integrity / governance / provisioning / managed-update / soul-registry / trust-API / CSP / operational-reliability / AGPL / framework-feedback / bug-fix / test-coverage / dependency-maintenance / docs>
## Surfaces affected
<enumerated>
## Specialist walks referenced
- Governance rubric: <...>
- Provisioning / managed-update / release verification: <...>
- Soul registry: <...>
- Trust API / CSP / instance-auth: <...>
- Framework: <idiomatic / reported upstream>
## Multi-tenant isolation impact
<none / elevated scrutiny>
## On-chain impact
<none / Sepolia / mainnet Safe-ready>
## Consumer impact
<managed operators / customers / sibling repos / on-chain actors / external vendors>
## Tasks
- [ ] <issue 1 title>
- [ ] <issue 2 title>
## Validation
- `go test ./...`
- `go vet ./...`
- `gofmt -l .` (empty)
- `cdk synth --context stage=lab` (if CDK changed)
- `hardhat test` (if Solidity changed)
- Slither + solhint (if Solidity changed)
- `web/` build + CSP validation (if web/ changed)
- gov-infra verifiers (CI)
## Stage rollout plan (handoff after merge)
- [ ] Merged to main
- [ ] Deployed to lab
- [ ] Lab soak complete
- [ ] Deployed to live
- [ ] Post-deploy monitoring verified
- [ ] (If on-chain) Sepolia deploy + Etherscan verification
- [ ] (If on-chain) Safe-ready payload prepared
- [ ] (If on-chain) Mainnet multisig execution
- [ ] (If provisioning) Canary customer stable
- [ ] (If provisioning) Broader rollout
## Cross-repo coordination
<required / none>
## Advisor-brief authorization (if applicable)
<summary from review-advisor-brief>
The per-task loop
For each issue in order:
- Read the issue. Confirm acceptance and planned commit subject. If drifted, stop.
memory_recent — refresh context.- For bug fixes: add regression test first. Especially for multi-tenant, trust-API-auth, on-chain-adjacent, provisioning, governance-verifier bugs.
- Make the change. Only files in enumerated paths.
- Run validation.
go test ./... (or targeted go test ./internal/<pkg>/...).go vet ./..., gofmt -l . empty.- For Solidity:
hardhat test, Slither, solhint.
- For
web/: build + CSP validation (dev server + automated check).
- For CDK:
cdk synth --context stage=lab.
- For gov-infra: run the relevant verifier locally where possible.
- For on-chain-adjacent changes: confirm transaction-preparation code paths are idempotent / dry-run-capable / explicit-confirmation.
- For multi-tenant-adjacent changes: confirm no cross-tenant read / write leaks.
- For governance-rubric changes: confirm pack.json version bumps, evidence-policy updates, verifier documentation.
- For consumer-release-verification changes: confirm
scripts/managed-release-certification/* and scripts/managed-release-readiness/* pass end-to-end against a test release.
- Commit. Planned subject. First line under 72 chars. Explain why for governance / multi-tenant / on-chain / release-verification / trust-API / AGPL / framework-adjacent changes.
- Push. Never force-push.
- Check task off in PR; update GitHub Project item status.
memory_append only when worth remembering — governance evolution, on-chain coordination, multi-tenant edge case, release-verification subtlety, trust-API pattern, framework awkwardness, advisor pattern. Five meaningful entries beat fifty log-shaped ones.
The mission rule enforced at commit time
Inside a milestone:
- Every commit must be in-mission. Scope growth →
scope-need.
- Bug-fix commits follow test-first pattern.
- Solidity commits isolated; Slither + hardhat + solhint evidence in commit body.
- Dependency bumps isolated for bisect.
- CDK commits isolated from Go code.
web/ commits isolated; CSP validation runs.gov-infra/pack.json commits isolated; documentation explains the rubric shift.- Consumer-release-verification commits isolated; elevated scrutiny noted.
- No hardcoded secrets, wallet keys, mint-signer keys, raw instance keys, partner credentials,
.env files.
- No raw-key / seed-phrase / full-signed-tx / PII / full-recipient logging.
- No changes to
AGENTS.md, branch protection, CODEOWNERS, or governance policies without explicit governance authorization.
- No on-chain Ethereum mainnet deploy single-signer.
- No multi-tenant isolation traversal.
- No framework patches to AppTheory / TableTheory / FaceTheory locally.
- No AGPL-incompatible dependencies or proprietary blobs.
- No consumer-release-verification bypass.
- No trust-API auth loosening or CSP loosening silently.
If tests or verifiers go red mid-milestone
- Do not add a "fix tests" or "fix verifier" commit touching unrelated code.
- Do stop, investigate, surface.
- Do not weaken a test or verifier.
- If failure is caused by your most recent commit, revert with a new revert commit and re-plan.
- If a verifier reveals a gov-infra issue, route through
maintain-governance-rubric.
Finishing the milestone (PR side)
When all tasks committed and pushed:
- Run
go test ./... on the tip.
- Run
go vet ./..., gofmt -l ..
- Run
cdk synth --context stage=lab if CDK changed.
- Run
hardhat test + Slither + solhint if Solidity changed.
- Run
web/ build + CSP validation if web/ changed.
- Confirm gov-infra verifiers pass (CI will re-run).
- Promote PR out of draft.
- Request required review.
- Leave merging to a reviewer who confirms CI including gov-infra verifiers is green.
Hand off after merge
Once merged to main, downstream flows take over per the roadmap:
theory app up --stage lab deploy (operator-run)- Lab soak
theory app up --stage live deploy (operator-authorized)- Live post-deploy monitoring
- On-chain Sepolia deploy (if contracts changed)
- On-chain mainnet Safe-ready execution (if contracts changed, after signer coordination)
- Managed-instance rollout (if provisioning changed, canary customer → broader)
- Release artifact publication (if relevant)
implement-milestone does not run these. Its output is a merged PR + handoff.
What this skill will not do
- Will not implement more than one milestone per run.
- Will not accept scope growth as a task.
- Will not merge PRs — required review (with gov-infra verifiers green).
- Will not skip review or verifiers.
- Will not run
theory app up commands — separate step.
- Will not run
hardhat deploy to Sepolia or mainnet — separate step; mainnet requires Safe multisig.
- Will not run managed-instance rollout — separate step.
- Will not skip specialist walks.
- Will not delete Lambda versions, DynamoDB tables, S3 buckets with RETAIN, Route53 zones, SSM, Secrets Manager entries, or CloudFormation stacks.
- Will not force-push, amend pushed commits, rewrite history.
- Will not bump Go runtime version in ordinary milestone.
- Will not add unsanitized logging or raw-credential logging.
- Will not set timeouts on CDK commands.
- Will not patch AppTheory / TableTheory / FaceTheory locally.
- Will not introduce AGPL-incompatible dependencies.
- Will not act on advisor briefs without
review-advisor-brief authorization.
- Will not weaken a gov-infra verifier.
