docs(#5458): document full mintcore file lifecycle in AGENTS.md

[fullsend-ai-coder]

Summary

Document the full 3-step lifecycle for adding new files to internal/mintcore/ in AGENTS.md. The existing instruction only covered step 1 (creating the .embed copy), which caused both agents and human reviewers to miss the embeddedMintFiles registration and gcfSkip exclusion steps during PR #5447, resulting in multiple fix iterations.

Related Issue

Fixes #5458

Changes

• Expanded the mintcore sync section in AGENTS.md with a numbered list covering all three steps:
  1. Create the .embed copy (enforced by lint-mint-embed-sync)
  2. Register in embeddedMintFiles for files without platform-specific build tags
  3. Add to gcfSkip in provisioner_test.go for files with build tags (e.g., //go:build js)
• References file_pem.go / pem_js.go as canonical examples of the build-tag exclusion pattern

Testing

• No code changes — documentation only
• Secret scan passed
• Gitlint passed

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• Documentation-only change, no new logic to test

---

Closes #5458

Post-script verification

• Branch is not main/master (agent/5458-mintcore-lifecycle-docs)
• Secret scan passed (gitleaks — cb2bcd9f282952232249eca4a281a3392a617d41..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:10 AM UTC · Completed 11:22 AM UTC
Commit: 463644b · View workflow run →

[github-actions]

Site preview

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

Commit: 9bbbe9118bd1ae36c0d3976711b3088d2e23679b

[fullsend-ai-review]

Review

Findings

High

• [logic-error] AGENTS.md:35 — Step 3 states that files with a platform-specific build tag (including //go:build !js) should NOT be registered in embeddedMintFiles and should instead be added to gcfSkip. This is incorrect — sts_verifier.go, gcp_pem.go, and wif.go all have //go:build !js and ARE registered in embeddedMintFiles. The !js tag means the file targets non-WASM (i.e., GCF), so it belongs in the GCF bundle. Only file_pem.go is excluded despite having //go:build !js, because it is standalone-mint-only (not because of the build tag). Following this documentation would cause an agent or developer adding a new //go:build !js file to incorrectly skip embeddedMintFiles registration and add it to gcfSkip, breaking the GCF deployment.
  Remediation: Rewrite steps 2 and 3 to reflect the actual criterion: (a) //go:build js (Worker-only) files should be added to gcfSkip and NOT registered in embeddedMintFiles; (b) //go:build !js files should generally be registered in embeddedMintFiles (they are needed for GCF); (c) files that are standalone-mint-only (like file_pem.go) should be added to gcfSkip regardless of build tag. See also: [incomplete-examples] finding at this location.

Medium

• [incomplete-examples] AGENTS.md:35 — Step 3 references file_pem.go / pem_js.go as examples in gcfSkip, but gcfSkip actually contains three entries: fetch_js.go, file_pem.go, and pem_js.go. The two cited files have different build tags (!js vs js) and are excluded for different reasons (standalone-mint-only vs Worker-only), which the documentation does not distinguish. See also: [logic-error] finding at this location.
  Remediation: Either list all three files or clarify the different exclusion reasons.

• [protected-path] AGENTS.md — This file is a protected path (governance/infrastructure). The PR links to issue AGENTS.md: Document full mintcore file lifecycle including embeddedMintFiles and build-tag exclusion #5458 and explains the rationale for the change. Human approval is always required for protected-path changes, regardless of context.

Low

• [numbered-list-format] AGENTS.md:33 — The numbered list items lack bold headings, inconsistent with the established pattern for numbered lists in this file (e.g., 1. **Unit tests:** Run..., 2. **Coverage:** CI enforces...).
  Remediation: Add bold labels to each list item.

• [heading-format] AGENTS.md:32 — The subsection heading When **adding a new file** does not match the established pattern for subsection headings in this file. Existing subsections use bold prefix with colon (e.g., **Mint function:**, **Standalone mint:**, **Dispatch workflows:**).
  Remediation: Change to **When adding a new file to internal/mintcore/:** to match the established heading pattern.

---

Labels: PR modifies AGENTS.md documentation for the mintcore subsystem.

[fullsend-ai-review]

See the review comment for full details.

[ifireball]

/fs-fix review comments

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 11:27 AM UTC · Completed 11:33 AM UTC
Commit: 7ada4e0 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed all 4 review findings. Fixed the high-severity logic error where !js files were incorrectly documented as belonging in gcfSkip (they should be in embeddedMintFiles for GCF). Listed all 3 gcfSkip entries with distinct exclusion reasons. Applied bold heading and numbered-list formatting to match existing patterns.

Fixed (4):

1. logic-error: !js files incorrectly documented as gcfSkip (AGENTS.md): Rewrote steps 2 and 3 to correctly reflect that //go:build !js files (e.g., sts_verifier.go, gcp_pem.go, wif.go) should be registered in embeddedMintFiles for GCF deployment, not added to gcfSkip. Only //go:build js (Worker-only) and standalone-mint-only files (like file_pem.go) belong in gcfSkip.
2. incomplete-examples: gcfSkip has 3 entries, not 2 (AGENTS.md): Listed all three gcfSkip entries (fetch_js.go, pem_js.go, file_pem.go) with distinct exclusion reasons: Worker-only (//go:build js) vs standalone-mint-only (//go:build !js).
3. numbered-list-format: missing bold headings on list items (AGENTS.md): Added bold labels to each numbered list item (Create the .embed copy, Register in embeddedMintFiles, Add to gcfSkip) to match the established pattern (e.g., 1. Unit tests: Run...).
4. heading-format: subsection heading doesn't match established pattern (AGENTS.md): Changed 'When adding a new file to internal/mintcore/:' to 'When adding a new file to internal/mintcore/:' to match the bold-prefix-with-colon pattern used throughout the file.

Tests: passed

_{Updated by fullsend fix agent}

[rh-hemartin]

LGTM, I do think at some point we need to split this AGENTS.md into docs/contributing/<topic>.md or docs/dev/<topic>.md to avoid having it full with instructions about how to touch code. Instead we could instruct the agents to search those docs and pick the one they believe is the appropriate. What do you think?

[ifireball]

@rh-hemartin

LGTM, I do think at some point we need to split this AGENTS.md into docs/contributing/<topic>.md or docs/dev/<topic>.md to avoid having it full with instructions about how to touch code. Instead we could instruct the agents to search those docs and pick the one they believe is the appropriate. What do you think?

I think that is a greate idea (for a new issue....)

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 6:59 AM UTC · Completed 7:09 AM UTC
Commit: 9bbbe91 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5459 — Document full mintcore file lifecycle in AGENTS.md

Overall assessment: This workflow demonstrates the full autonomous pipeline working well — retro agent identified a documentation gap from PR #5447, filed issue #5458, triage confirmed it, code agent implemented, review agent caught a critical error, fix agent corrected it in one iteration, and humans merged.

Timeline

Time (UTC)	Event
07-22 10:57	Retro agent files #5458 from PR #5447 analysis
07-22 11:02	Triage agent confirms as medium-priority docs issue, labels ready-to-code
07-22 11:09	Code agent opens PR #5459 with commit 463644b
07-22 11:13	Human (ifireball) approves — before review agent finishes
07-22 11:22	Review agent (run 29914638255) submits CHANGES_REQUESTED — catches high-severity logic error
07-22 11:26	Human triggers /fs-fix review comments
07-22 11:33	Fix agent (run 29915700918) pushes 9bbbe91, addresses all 4 findings
07-22 14:18	Second human (rh-hemartin) approves
07-23 06:56	PR merged

Positive signals

• Review agent outperformed the human reviewer. The code agent incorrectly documented that //go:build !js files should go in gcfSkip, when they actually belong in embeddedMintFiles (because !js means "non-WASM / GCF target"). The human approved without catching this; the review agent flagged it as high-severity. Following the incorrect docs would have broken GCF deployment.
• Fix agent was efficient. All 4 review findings (1 high logic error, 1 medium incomplete examples, 2 low formatting) were addressed in a single iteration with no rework.
• Full pipeline orchestration worked. The retro→triage→code→review→fix→merge cycle completed with minimal human intervention (just /fs-fix trigger and approvals).

Evidence for existing issues

• #897 (fix agent re-request review): No automated re-review was triggered after the fix agent pushed commit 9bbbe91. The fix agent's corrections to the critical logic error were never verified by the review agent — the PR merged on human approvals alone.
• #5504 (split AGENTS.md): Human reviewer rh-hemartin independently suggested splitting AGENTS.md into topic-specific files under docs/contributing/, corroborating this issue.
• #2199 (review agent fact-check docs): Positive evidence — the review agent successfully fact-checked documentation claims against source code and caught a critical inaccuracy that the human missed.

Proposal filed

1. Code agent should verify documentation claims against source files during generation — See proposal below.

Proposals filed

• Code agent should verify documentation claims against source files during generation (in fullsend-ai/agents)