docs(#347): document mint deploy-time source stamping pattern

[fullsend-ai-coder]

Add build metadata stamping guidance to the Mint function section of AGENTS.md. The mint Cloud Function must receive version and commit metadata via deploy-time source stamping (provisioner writes mintcore/version.go into the function source zip at bundle time), not runtime environment variables. This prevents version metadata from drifting out of sync with the deployed code.

This documentation gap caused the code agent on PR fullsend-ai#2909 to initially choose the env-var approach, requiring a human-directed fix iteration.

---

Closes #347

Post-script verification

• Branch is not main/master (agent/347-doc-mint-stamping-pattern)
• Secret scan passed (gitleaks — a2afa8b179a351845733c680b839a39a82304db6..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:49 AM UTC · Completed 6:58 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [technical documentation accuracy] AGENTS.md:30 — The added paragraph states "the provisioner generates mintcore/version.go" using present tense, but no mintcore/version.go file or version-generation logic exists in this repository's codebase. The bundleFunctionSource() function in internal/dispatch/gcf/provisioner.go bundles existing files and rewrites go.mod but does not generate any source files. Issue Document mint version-stamping pattern in AGENTS.md to prevent env-var anti-pattern #347 references PR feat(#2904): expose version and commit in mint /health and /v1/status fullsend-ai/fullsend#2909 on the upstream repo (fullsend-ai/fullsend) where this pattern was implemented — if that implementation has not been ported to this fork, the documentation describes a mechanism that does not yet exist here. Consider rewording to make the prescriptive intent clearer (e.g., "should generate" rather than "generates") or verify the upstream implementation has been synced.

• [scope-mismatch] AGENTS.md:30 — The paragraph uses present-tense implementation claims ("the provisioner generates") when the implementation may not exist in this repository. AGENTS.md serves as prescriptive guidance for code agents, so the intent is valid and aligned with issue Document mint version-stamping pattern in AGENTS.md to prevent env-var anti-pattern #347. However, the wording should distinguish between describing what exists and prescribing what agents should do. See also: [technical documentation accuracy] finding at this location.

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected path requiring human approval. The PR links to issue Document mint version-stamping pattern in AGENTS.md to prevent env-var anti-pattern #347 and the description explains the rationale (preventing the env-var anti-pattern for build metadata). Human review and approval is required for this change regardless of automated review status.

Low

• [stale-pattern-description] docs/guides/infrastructure/infrastructure-reference.md:280 — The GCF Provisioner Flow diagram shows environment variables (ALLOWED_ORGS, ROLE_APP_IDS, etc.) set at deploy time. The new AGENTS.md guidance states build metadata should use source stamping, not env vars. These are different categories of data (operational configuration vs build metadata) so there is no real contradiction, but a clarifying note distinguishing the two would reduce ambiguity.

• [incomplete-pattern-coverage] docs/guides/infrastructure/mint-administration.md:84 — This section describes the provisioner bundling mintcore but does not mention version.go generation at bundle time. A follow-up note would improve completeness once the implementation is confirmed to exist in this repository.

Previous run

Review

Verdict: comment

This is a well-scoped, 2-line documentation addition to AGENTS.md that adds architectural guidance about deploy-time source stamping for the mint Cloud Function. The change is authorized by issue #347, follows existing style conventions, introduces no security concerns, and is placed logically in the Mint function section.

One medium-severity correctness finding below.

Findings

1. Documentation claims code that does not exist in this codebase — medium / technical-accuracy

File: AGENTS.md (new line 30)

The added paragraph states: "The provisioner writes mintcore/version.go into the function source zip at bundle time with version and commit values baked in."

This is a present-tense factual claim about the provisioner's behavior, but exhaustive search confirms this code does not exist in the current codebase:

• No version.go file in internal/mintcore/ or internal/mint/
• No version.go.embed in internal/dispatch/gcf/mintsrc/mintcore/
• The embeddedMintFiles map in provisioner.go (lines 51–66) does not include a version.go entry
• bundleFunctionSource() bundles files as-is without generating or injecting a version.go
• No grep matches for version stamping logic (writeVersion, stampVersion, BuildVersion, BuildCommit) anywhere in the mint or mintcore packages

The linked issue (#347) references upstream PR fullsend-ai#2909 on fullsend-ai/fullsend where this pattern was implemented. This fork has not synced that code.

The architectural guidance is sound — deploy-time source stamping does prevent version drift compared to runtime env vars, and the prescriptive direction ("Follow this same pattern...") achieves the issue's stated goal of preventing the env-var anti-pattern. However, the present-tense factual claim could mislead an agent that tries to locate the referenced code as a pattern to follow.

Suggested remediation: Either (a) land this docs change after syncing the upstream code that implements the pattern, or (b) reword to make the prescriptive intent clearer, e.g.: "The mint Cloud Function should receive version and commit metadata via deploy-time source stamping, not runtime environment variables. The provisioner generates mintcore/version.go and writes it into the function source zip at bundle time..."

2. Sync exception not clarified — low / internal-consistency

File: AGENTS.md (new line 30)

The existing AGENTS.md guidance says: "When changing any file in internal/mintcore/, sync it to the corresponding .embed file under mintsrc/mintcore/." If version.go is generated at bundle time by the provisioner (as the new paragraph claims), it should not follow the manual .embed sync pattern — it would be dynamically created, not a static copy. The documentation doesn't clarify this exception, which could cause an agent to create a version.go.embed file unnecessarily.

Dimensions reviewed

Dimension	Model	Result
Correctness	opus	1 medium, 1 low
Security	opus	Clean
Intent & coherence	sonnet	Clean — well-authorized, correctly scoped
Style & conventions	sonnet	Clean — matches existing patterns
Docs currency	sonnet	Clean — no contradictions
Cross-repo contracts	—	Skipped (no API changes)

---

Labels: PR adds documentation to AGENTS.md about mint function patterns

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 7:56 AM UTC · Completed 8:06 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed both review findings with a single coherent edit to AGENTS.md line 30. Finding 1 (medium/technical-accuracy): reworded from present-tense factual claims to prescriptive language since the referenced code does not exist in this fork. Finding 2 (low/internal-consistency): added clarification that version.go is an exception to the .embed sync pattern.

Fixed (2):

1. Documentation claims code that does not exist in this codebase (mintcore/version.go) (AGENTS.md): Reworded build metadata stamping paragraph from present-tense factual claims ('receives', 'writes') to prescriptive language ('should receive', 'generates...and writes'), making the intent clearer since mintcore/version.go does not yet exist in this fork
2. Sync exception for version.go not clarified (AGENTS.md): Added explicit note that version.go does not follow the manual .embed sync pattern since it is generated at bundle time, preventing agents from creating an unnecessary version.go.embed file

Tests: passed

_{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:09 AM UTC · Completed 8:20 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[medium] technical documentation accuracy

The added paragraph states 'the provisioner generates mintcore/version.go' using present tense, but no mintcore/version.go file or version-generation logic exists in this repository's codebase. bundleFunctionSource() in internal/dispatch/gcf/provisioner.go bundles existing files and rewrites go.mod but does not generate any source files. Issue #347 references PR fullsend-ai#2909 on the upstream repo (fullsend-ai/fullsend) where this pattern was implemented — if that implementation has not been ported to this fork, the documentation describes a mechanism that does not yet exist here.

Suggested fix: Reword to make prescriptive intent clearer (e.g., 'should generate' rather than 'generates') or verify the upstream implementation has been synced to this repository.

[fullsend-ai-review]

[medium] scope-mismatch

The paragraph uses present-tense implementation claims ('the provisioner generates') when the implementation may not exist in this repository. AGENTS.md serves as prescriptive guidance for code agents, so the intent is valid and aligned with issue #347. However, the wording should distinguish between describing what exists and prescribing what agents should do.

Suggested fix: Adjust wording to be prescriptive rather than descriptive, e.g., 'At bundle time, the provisioner should generate mintcore/version.go...' or add a note referencing upstream PR fullsend-ai#2909.