docs(#6307): add mintcore contributor guide

[fullsend-ai-coder]

Summary

• Add docs/contributing/mintcore.md — a contributor guide documenting the shipped mintcore architecture (platform accessors, load-site construction, WASM-safe wiring, and rejected patterns)
• Link the guide from the AGENTS.md topic-specific guidance table and from docs/architecture.md (standalone mint deployment section)
• docs/contributing/go-code.md WASM section already covers the accessor invariants consistently — no changes needed

Details

The guide covers:

1. Deploy targets — GCF, CF Worker, standalone; what each load site constructs
2. Layering — internal/mintcore/ vs entrypoints vs CF Worker TypeScript adapter
3. Platform accessors — mintEnv, mintHTTP; build-tagged implementations; RegisterEnv/RegisterHTTP on WASM
4. Load-site construction — each entrypoint builds OIDCVerifier + PEMAccessor and calls NewHandler(pem, verifier)
5. WASM-unsafe patterns — closures in config structs, constructor-time mintHTTP, niladic *FromEnv factories, threading http.Client
6. WASM-safe patterns — Register* at bootstrap, plain-data configs, request-time mintHTTP(req)
7. PEM remains injected — FilesystemPEMAccessor / GCPSecretPEMAccessor / HostPEMAccessor
8. Interfaces vs accessors — when to use each pattern
9. Embed sync and make wasm-build — new file checklist, gcfSkip, gzip size gate
10. Rejected patterns — explicitly marks niladic factories, wire_*.go, mintPEM, NewPlatformHandler() as rejected (not TODO)

Testing

• Documentation-only change — no Go code modified
• lychee offline link check passed (0 errors across all changed files)
• lint-docs-links passed
• scan-secrets passed
• gitlint passed

---

Closes #6307

Post-script verification

• Branch is not main/master (agent/6307-mintcore-contributor-guide)
• Secret scan passed (gitleaks — c6e147139de3d787167799e15fcb5f7222674bd0..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[github-actions]

Site preview

Preview: https://2ad411d8-site.fullsend-ai.workers.dev

Commit: c61b66e2eb76e762317827746aefd56e9942ed85

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:33 AM UTC · Completed 9:50 AM UTC

Commit: c725d59 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Medium

• [scope gap — acceptance criterion not met] docs/contributing/mintcore.md — Issue docs(mintcore): document platform accessors, load-site construction, and WASM-safe wiring #6307 AC5 requires the guide to explicitly treat niladic factories (NewJWKSVerifierFromEnv, NewSTSVerifierFromEnv, VerifierFactory), wire_*.go, mintPEM, and NewPlatformHandler() as rejected (not TODO). The "Rejected patterns" section was present in an earlier commit but was removed in the final revision. The PR body still claims a "Rejected patterns" section exists (section 10), but the shipped file contains no such section and zero occurrences of the required identifiers. The WASM-unsafe patterns section covers related anti-patterns but does not name the specific rejected approaches from refactor(mintcore): resolve platform strategies at deploy build time #6304/refactor(mint): internalize mintPEM and deploy-time wiring #6306.
  Remediation: Add a "Rejected patterns" section (or clearly labeled subsection) that explicitly names these identifiers as rejected, with brief rationale referencing refactor(mint): internalize mintPEM and deploy-time wiring #6306 and PR refactor(#6305): internalize env access via build-tagged mintEnv #6308.

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The linked issue (docs(mintcore): document platform accessors, load-site construction, and WASM-safe wiring #6307, acceptance criterion 3) explicitly authorizes adding a table row linking to the new guide, providing sufficient context. Human approval is always required for protected-path changes regardless of context.

Previous run

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The linked issue (docs(mintcore): document platform accessors, load-site construction, and WASM-safe wiring #6307, acceptance criterion 3) explicitly authorizes adding a table row linking to the new guide, providing sufficient context. Human approval is always required for protected-path changes regardless of context.

Previous run (2)

Review

Findings

Medium

• [technical documentation accuracy] docs/contributing/mintcore.md:32 — The layering diagram incorrectly nests gcf/mintsrc/ under internal/dispatch/cf/. The actual filesystem has internal/dispatch/cf/ and internal/dispatch/gcf/ as sibling directories under internal/dispatch/. The diagram's indentation implies the path internal/dispatch/cf/gcf/mintsrc/ which does not exist — the correct path is internal/dispatch/gcf/mintsrc/. The embed sync section later in the document uses the correct full path, so the error is confined to the diagram, but a contributor reading it for orientation would be misled.
  Remediation: Split into two separate top-level entries in the diagram — internal/dispatch/cf/ (with workersrc/) and internal/dispatch/gcf/ (with mintsrc/).

• [acceptance criteria gap] docs/contributing/go-code.md:20 — Issue docs(mintcore): document platform accessors, load-site construction, and WASM-safe wiring #6307 acceptance criterion 2 requires go-code.md to stay consistent with the new guide. The new mintcore.md correctly lists five gcfSkip entries (env_js.go, fetch_js.go, http_client_js.go, pem_js.go, file_pem.go), matching the actual code in provisioner_test.go. However, go-code.md still claims three entries, omitting env_js.go and http_client_js.go. This ships a contradiction between two contributor guides.
  Remediation: Update the gcfSkip enumeration in go-code.md to list all five current entries.

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The linked issue (docs(mintcore): document platform accessors, load-site construction, and WASM-safe wiring #6307, acceptance criterion 3) explicitly authorizes adding a table row linking to the new guide, providing sufficient context. Human approval is always required for protected-path changes regardless of context.

Low

• [documentation preamble convention] docs/contributing/mintcore.md:8 — The new file includes a "Read this when you are changing files under..." paragraph. No other file in docs/contributing/ includes such a preamble — all existing contributing docs rely solely on the AGENTS.md table's "When to read" column for scope guidance. This creates a minor maintenance duplication: if the paths change, two locations must be updated.
  Remediation: Consider removing the preamble to match the convention used by other contributing docs.

[ifireball]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 9:55 AM UTC · Completed 10:01 AM UTC

Commit: c725d59 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed all 4 review findings: fixed the layering diagram path nesting, updated gcfSkip count from 3 to 5 in go-code.md, removed non-standard preamble from mintcore.md, and acknowledged the protected-path informational finding (no code fix needed — human approval is a separate process).

Fixed (3):

1. layering diagram incorrectly nests gcf/mintsrc/ under internal/dispatch/cf/ (docs/contributing/mintcore.md): Split internal/dispatch/cf/ and internal/dispatch/gcf/ into separate top-level entries in the diagram to match the actual filesystem structure where they are sibling directories
2. go-code.md gcfSkip count lists three entries instead of five (docs/contributing/go-code.md): Updated gcfSkip enumeration from three to five entries, adding env_js.go and http_client_js.go to match the actual gcfSkip map in provisioner_test.go
3. documentation preamble convention mismatch in mintcore.md (docs/contributing/mintcore.md): Removed the 'Read this when you are changing files under...' preamble to match the convention of other docs/contributing/ files, which rely solely on the AGENTS.md table's 'When to read' column for scope guidance

Disagreed (1):

1. AGENTS.md is a protected governance file requiring human approval: This is an informational finding about the PR touching a protected path. The AGENTS.md change (adding a table row) is authorized by issue docs(mintcore): document platform accessors, load-site construction, and WASM-safe wiring #6307 acceptance criterion 3. Human approval is a separate process handled outside the fix agent — no code change is needed.

Tests: passed

Next steps:

• /fs-review — request a re-review of the changes
• /fs-fix <your instruction> — run another fix pass with specific guidance
• Push commits directly — review re-runs automatically on push
  _{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:03 AM UTC · Completed 10:16 AM UTC

Commit: 351d42a · View workflow run →

[ifireball]

/fs-fix drop mentions about unused/dropped patterns like niliadic factories

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 10:49 AM UTC · Completed 10:56 AM UTC

Commit: 351d42a · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 2 (human-triggered)

Addressed human instruction to drop mentions of unused/dropped patterns like niliadic factories from the mintcore contributor guide. Removed all sections that documented historical design decisions that were never shipped (niliadic FromEnv factories, threading http.Client, wire_.go/NewPlatformHandler, mintPEM/RegisterPEM) and the 'Rejected patterns' summary table. The guide now focuses exclusively on the shipped architecture.

Fixed (1):

1. Drop mentions about unused/dropped patterns like niliadic factories (docs/contributing/mintcore.md): Removed five sections documenting rejected/unimplemented patterns: (1) 'Niladic FromEnv factories' anti-pattern section, (2) 'Threading http.Client through entrypoints' anti-pattern section, (3) 'wire_.go / NewPlatformHandler()' anti-pattern section, (4) 'mintPEM / RegisterPEM' anti-pattern section, (5) 'Rejected patterns' summary table at the end of the file. Also simplified the 'mintEnv / mintHTTP inside verifier constructors' example to remove the dropped function name pattern, and removed the 'no mintPEM accessor and no RegisterPEM' clause from the 'PEM remains injected' section. Updated AGENTS.md table to drop 'rejected patterns' from the mintcore guide scope description.

Tests: passed

Next steps:

• /fs-review — request a re-review of the changes
• /fs-fix <your instruction> — run another fix pass with specific guidance
• Push commits directly — review re-runs automatically on push
  _{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:58 AM UTC · Completed 11:17 AM UTC

Commit: c61b66e · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 7:46 PM UTC · Completed 7:59 PM UTC

Commit: c61b66e · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.36

[fullsend-ai-retro]

Retro: PR #6515 — docs(#6307): add mintcore contributor guide

Workflow overview: A docs-only PR adding docs/contributing/mintcore.md with cross-references from AGENTS.md and docs/architecture.md. The code agent created the guide, the review agent found issues across 3 iterations with 2 fix cycles, and the human merged after approving.

Timeline

1. Issue docs(mintcore): document platform accessors, load-site construction, and WASM-safe wiring #6307 created 2026-08-17 with 5 acceptance criteria for documenting mintcore architecture.
2. Triage (3 runs, Aug 17-18): identified blocking dependencies refactor(mintcore): internalize mintEnv and static HTTPDoer #6305/refactor(mint): internalize mintPEM and deploy-time wiring #6306.
3. Code run 1 (08:40 UTC, run 32628895277): Agent wrote all 3 files but never ran git add or git commit. Sandbox network restrictions caused pre-commit run to fail; the agent fell back to running hooks manually, then exited without committing. Post-code script reported "No PR created."
4. Code run 2 (09:22 UTC, run 32630813445): Human triggered /fs-code. Agent committed successfully, PR docs(#6307): add mintcore contributor guide #6515 created at 09:31 UTC.
5. Review iteration 1 (09:50 UTC): 4 findings — layering diagram error (medium, true positive), gcfSkip count mismatch (medium, true positive), protected-path AGENTS.md (medium, non-actionable), preamble convention (low, marginal).
6. Fix iteration 1 (10:01 UTC): Fixed 3 of 4 findings. Correctly identified protected-path as informational.
7. Review iteration 2 (10:16 UTC): Only protected-path remained.
8. Human editorial instruction (10:47 UTC): /fs-fix drop mentions about unused/dropped patterns like niliadic factories.
9. Fix iteration 2 (10:56 UTC): Removed all rejected-patterns content per human instruction.
10. Review iteration 3 (11:17 UTC): 2 findings — scope gap (medium, contradicted human instruction) and protected-path (medium, repeated for third time).
11. Human approved twice (11:05, 11:49 UTC) and merged at 19:44 UTC.

What went well

• Review iteration 1 technical findings were strong. The layering diagram error and gcfSkip count mismatch were genuine factual/consistency bugs that demonstrated the review agent's ability to cross-reference documentation against filesystem structure and source code.
• Fix agent executed accurately. Both fix iterations correctly applied the requested changes — the first addressing review findings, the second following the human's editorial direction.
• Efficient cycle. 3 review iterations and 2 fix iterations, all CI green, merged same day.

Evidence for existing issues

• Investigate code agent run reporting success without creating a PR #4689 (investigate code agent reporting success without creating a PR): This retro identified the specific root cause mechanism — sandbox network restrictions caused pre-commit run to fail, leading the agent down a manual verification fallback path where it lost track of the commit step. The agent wrote all files but never staged or committed them. This is the clearest causal trace yet for this class of failure.
• Code agent status comment should reflect actual outcome when no PR is created #2378 (code agent status comment should reflect actual outcome): The post-code script reported "agent determined no changes needed" when the agent had actually created/modified 3 files but forgot to commit them. Misleading status.
• Bot gives identical "protected-path" review comments on every workflow run #2794 (identical protected-path comments every run): The protected-path AGENTS.md finding appeared in all 3 review iterations despite being acknowledged as non-actionable in fix iteration 1. The finding was self-contradictory — it acknowledged the issue explicitly authorized the AGENTS.md change but still flagged it.
• Review re-review anchoring should incorporate author response context to suppress explained-away findings #5265 (re-review anchoring should incorporate author response context): The iteration 3 "scope gap" finding is direct evidence for this issue. The human explicitly instructed the fix agent to remove rejected-patterns content, then the review agent generated a new finding flagging that removal as violating issue AC5. The human's instruction was an implicit amendment of the acceptance criteria, but the review agent had no awareness of it.

Proposals filed

• Post-code guard: detect uncommitted working-tree changes after agent exit (in fullsend-ai/agents)