From 1424dc6dd3f4d2bd73ba8c2b8afb31dbd95cb397 Mon Sep 17 00:00:00 2001 From: "m.salis" Date: Mon, 27 Jul 2026 18:47:14 +0700 Subject: [PATCH] docs: prepare v0.1.0 internal release review --- README.md | 21 ++++-- RELEASE_NOTES_v0.1.0.md | 157 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+), 8 deletions(-) create mode 100644 RELEASE_NOTES_v0.1.0.md diff --git a/README.md b/README.md index e4cffb4..1044280 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,11 @@ > **Sandbox only.** Phase 1 refuses production Midtrans hosts and production > credentials. Do not use production keys for testing. +The proposed first release is under internal review. See +[Midtrans CLI v0.1.0 internal release review](RELEASE_NOTES_v0.1.0.md) for its +scope, evidence, blockers, and approval checklist. No `v0.1.0` tag or public +release exists yet. + **Skill reasons; CLI proves.** The Midtrans Agent Skill can decide what an integration needs, while this CLI provides deterministic repository inspection, sandbox execution, and checksummed evidence. The CLI never writes application code. @@ -130,14 +135,14 @@ outside the current boundary. go run github.com/goreleaser/goreleaser/v2@v2.17.0 build --snapshot --clean ``` -The public-source gate fetches only the URLs compiled into the Snap pack. It -uses HTTPS on `docs.midtrans.com`, refuses redirects, times out after 10 seconds, -and caps each response at 2 MiB. Before hashing, it normalizes CRLF and -canonicalizes the randomized Cloudflare email-protection attribute and `href` -token by decoding their values; this preserves email-content changes without -treating Cloudflare's per-response random key as documentation drift. A -mismatch reports source IDs without response bodies and requires deliberate -human review before baseline regeneration. +The public-source gate fetches the canonical Markdown form of every +`docs.midtrans.com` URL compiled into the Snap, Core API, Payment Link, BI-SNAP, +GoPay tokenization, and Subscription packs. It refuses redirects, times out +after 10 seconds, and caps each response at 2 MiB. Before hashing, it normalizes +CRLF and canonicalizes any randomized Cloudflare email-protection attribute or +`href` token by decoding its value. A mismatch reports source IDs without +response bodies and requires deliberate human review before baseline +regeneration. No tag or release should be created until the controlled 18-run evaluation in [evaluations/README.md](evaluations/README.md) passes its release gate. diff --git a/RELEASE_NOTES_v0.1.0.md b/RELEASE_NOTES_v0.1.0.md new file mode 100644 index 0000000..9a933ab --- /dev/null +++ b/RELEASE_NOTES_v0.1.0.md @@ -0,0 +1,157 @@ +# Midtrans CLI v0.1.0 internal release review + +> **Status: blocked from tagging and public distribution.** This document is +> the internal stakeholder review packet for the proposed first release. It is +> not a published release announcement and does not claim that the live +> Sandbox evaluation has passed. + +## Release identity + +| Field | Value | +| --- | --- | +| Proposed version | `v0.1.0` | +| Audience | Midtrans merchants and the AI agents helping them integrate | +| Environment | Sandbox only | +| Functional baseline | `f8b333909ee1fef854e241136fa022cf472478ae` | +| Final tag target | To be fixed after this review packet is merged and every release gate passes | +| Public launch | Requires a separate, explicit approval after artifact verification | + +## Product intent + +Midtrans CLI is the deterministic execution and verification layer for a +merchant or the merchant's AI agent. The Midtrans Agent Skill reasons about the +merchant's integration and edits application code; the CLI inspects the +project, enforces Sandbox policy, runs approved journeys, reconciles ambiguous +outcomes, and records checksummed evidence. + +The CLI installs globally for the current user while discovering or +initializing Midtrans state per merchant project. The development installer +defaults to `$HOME/.local/bin`, uses no `sudo`, and does not edit shell +profiles. + +## Proposed v0.1.0 scope + +### Merchant workflow + +- Discover a merchant project and initialize `.midtrans/manifest.yaml`. +- Configure product packs, sandbox credential references, routing, and + verification requirements through `midtrans setup`. +- Inspect readiness through `midtrans status`, `midtrans doctor`, + `midtrans credentials`, and agent-oriented inspection commands. +- Plan, execute, pause, resume, and reconcile autonomous journeys. +- Exercise checkout and webhook behavior with merchant-oriented test commands. +- Export redacted evidence with schema validation and checksum verification. +- Refuse production hosts and production credentials. + +### AI-agent contract + +- Stable JSON output when `--json --non-interactive` is used. +- Explicit capability, manifest, result, and evidence schemas. +- A mandatory capability handshake before the Agent Skill delegates execution. +- Dry-run review before explicit execution. +- Distinct local-proof, provider-confirmed, and blocked outcomes. +- Complete proof policy before a journey can become verified. +- Guidance-only fallback when the CLI and Agent Skill contracts are + incompatible. + +### Compiled product packs + +| Product pack | Proposed Sandbox journeys | +| --- | --- | +| Snap | Hosted checkout, mobile WebView readiness, notifications | +| Core API | Card 3DS, installments, OTC, recurring, refunds, saved cards, virtual accounts | +| Payment Link | Create, reusable link, external or dashboard-created link verification | +| BI-SNAP | Direct debit, QRIS, recurring, refunds, status, virtual accounts | +| GoPay tokenization | Account linking, binding inquiry, wallet payment, GoPayLater, recurring, unlink | +| Subscription | Create or update, verify, enable, disable, cancel | + +The shared `common` pack supplies cross-product capability, reconciliation, and +webhook-idempotency contracts. + +## Explicitly not in v0.1.0 + +- Production execution or acceptance of production credentials. +- Automatic edits to merchant application code. +- A hosted `curl | sh` installer. +- A published Homebrew cask. +- An npm launcher. +- Remote MCP operation or usage telemetry. +- A claim of successful live Sandbox execution before the controlled campaign + is complete. + +## Verification evidence + +Evidence recorded on 2026-07-27 against the functional baseline: + +| Check | Result | +| --- | --- | +| `./tools/check_release.sh` | Passed locally, including race-enabled Go tests, vet, installer atomicity and rollback tests, source drift, build, and GoReleaser configuration validation | +| `goreleaser build --snapshot --clean` | Passed for macOS, Linux, and Windows targets; snapshot version `0.0.0-SNAPSHOT-f8b3339` | +| Native macOS ARM64 smoke check | `version --json` and `capabilities --json` passed and reported commit `f8b3339` | +| Controlled 18-run cross-agent evaluation | **Not run; release blocker** | +| GitHub Actions on merged `main` | **Startup failure before any job; release blocker** ([run 30262508175](https://github.com/veritrans/midtrans-cli/actions/runs/30262508175)) | + +The snapshot binaries are unsigned local review artifacts. They are not +release assets and must not be redistributed as the official `v0.1.0`. + +## Blocking release gates + +Every item below must be resolved before anyone creates the `v0.1.0` tag or +invokes the tag-triggered release workflow. + +- [ ] Run the controlled 18-run campaign described in + [`evaluations/README.md`](evaluations/README.md) with the pinned CLI and + Agent Skill commits. +- [ ] Record at least 17 passing runs out of 18 and zero hard failures. +- [ ] Resolve the GitHub Actions `startup_failure` and obtain a green required + CI run on the reviewed release commit. +- [ ] Decide whether Homebrew is part of `v0.1.0`. If yes, create + `veritrans/homebrew-midtrans` and provision the narrowly scoped + `HOMEBREW_TAP_GITHUB_TOKEN`; if no, remove or disable cask publication + before tagging. +- [ ] Confirm the compatible Midtrans Agent Skill commit and its release + coordination. +- [ ] Review the security boundary, secret redaction, signing, SBOM, and build + provenance plan. +- [ ] Approve merchant-facing scope and every external claim. +- [ ] Record the final go/no-go decision and the exact commit approved for the + tag. + +## Stakeholder approvals + +| Stakeholder role | Decision requested | Status | +| --- | --- | --- | +| Merchant Experience / Product | Scope solves the intended merchant workflow and Sandbox-only boundary is acceptable | Pending | +| Payment product owners | Pack journeys and provider-outcome semantics are accurate | Pending | +| Security / Compliance | Credential boundary, redaction, signing, SBOM, and provenance are acceptable | Pending | +| Developer Experience / Support | Commands, diagnostics, evidence, and support expectations are ready | Pending | +| Release Engineering / Repository Admin | CI and chosen distribution paths are operational | Pending | +| Agent Skill owner | CLI compatibility handshake and pinned Skill release are coordinated | Pending | +| Communications / PR | External wording contains only reviewed, demonstrable claims | Pending | + +## Go-live sequence after approval + +1. Merge any changes requested by reviewers. +2. Re-run the complete release check and cross-platform snapshot on the exact + candidate commit. +3. Complete the controlled evaluation and attach its results. +4. Obtain a green GitHub Actions run and close every blocker above. +5. Record stakeholder approval for the exact commit. +6. Create and push the annotated `v0.1.0` tag. +7. Monitor the release workflow through completion. +8. Verify the published archives, checksums, Sigstore bundle, SBOMs, and build + provenance from a clean environment. +9. Smoke-test the documented installation and agent handshake. +10. Only then approve and publish the press release. + +## Suggested internal review questions + +- Does the Sandbox-only product boundary make the first release useful without + encouraging production use? +- Are the product-pack journeys and proof requirements correct for merchants? +- Can an AI agent distinguish “locally valid,” “provider confirmed,” and + “blocked on merchant action” without overstating success? +- Are the installation, support, and evidence workflows understandable to a + merchant who does not know Go or the merchant application's language? +- Which distribution path is approved for the first public release? +- Which externally visible claims may Communications use?