docs: harden and scope agent guidance

[Wibias]

Summary

• replaces the root AGENTS.md with explicit source-of-truth, branch, workflow, validation, review, security, and completion rules
• adds scoped agent guidance for src/, scripts/, docs-site/, and .github/
• expands the existing gui/AGENTS.md while preserving all existing i18n requirements
• adds CODEOWNERS coverage and governance-review requirements for agent-instruction files
• distinguishes runtime authority from public documentation authority
• prevents pending behaviour from being documented as already released
• removes duplicated and historical guidance from the root file

Scope

This pull request changes repository governance and contributor guidance only.

It does not change runtime behaviour, dependencies, workflow permissions, release logic, publishing, or deployment behaviour.

Validation

• deterministic migration script verified the exact source states
• exact changed-file set verified
• existing gui/AGENTS.md i18n requirements preserved
• git diff --check passed
• script completed with a clean committed working tree
• current dev workflows were verified to accept dev2-go as an integration target

Required governance review

Changes to AGENTS.md and related agent-instruction files require explicit governance review under MAINTAINERS.md.

Before merge:

• obtain approval from @lidge-jun or @Ingwannu
• replace the temporary Requirement 2 text in the Wibias maintainer change-log entry with:

Requirement 2 was satisfied by @Reviewer's approval of PR #PR_NUMBER.

This pull request should not be merged while that entry still describes the review requirement as incomplete.

Summary by CodeRabbit

• Documentation

  • Added and refreshed repository guidance across multiple areas via new and updated AGENTS.md files, including workflow/security expectations, validation steps, and clear instructions for GUI, documentation site, source code, and release scripts.
  • Expanded GUI guidance for localized UI text and accessibility, plus stricter i18n sourcing rules for user-facing strings.

• Governance / Policy

  • Updated merge/review policy for handling changes across dev and dev2-go, and clarified promotion/release timing guidance.
  • Added stricter governance rules for AGENTS.md updates and updated ownership coverage for these policy documents.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The pull request formalizes repository governance, adds directory-specific agent instructions, defines GitHub automation security rules, expands CODEOWNERS coverage, and documents validation requirements for documentation, GUI, scripts, and runtime source changes.

Changes

Repository governance and ownership

Layer / File(s)	Summary
Repository policy and ownership AGENTS.md, MAINTAINERS.md, .github/CODEOWNERS	Repository scope, structure, branch targets, working rules, review rules, promotion policy, and governance ownership requirements were formalized.
Validation and security controls AGENTS.md, .github/AGENTS.md	Changed-surface validation, security review boundaries, workflow permission and action-pinning rules, release blockers, and completion checks were documented.

Directory-specific instructions

Layer / File(s)	Summary
Scoped implementation guidance docs-site/AGENTS.md, gui/AGENTS.md, scripts/AGENTS.md, src/AGENTS.md	Documentation, dashboard, script, and runtime source areas now have scoped rules covering implementation constraints, security boundaries, localization, generated output, and required validation commands.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: ingwannu, lidge-jun

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the PR’s main change: strengthening and scoping AGENTS guidance across the repository.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[Wibias]

Review/merge ready.

[Wibias]

Added dual-landing guidance so agents follow the owner's interim policy:

• still one PR base (dev by default, dev2-go only for scoped Go work)
• after merge, also land on the other integration line (cherry-pick / paired PR / maintainer sync) until the pipeline exists
• release path remains dev → main, with ~weekly promote/deploy when directed

Updated in AGENTS.md and MAINTAINERS.md (MAINTAINERS.md remains authoritative).

[Wibias]

Softened the dual-landing text after the owner's follow-up:

• Go port still unstable → aiming at two release tracks
• Prefer landing on both dev and dev2-go when a change belongs on both
• Mechanics / separate Go release path still TBD (owner looking into it)
• Not a finished hard workflow for agents to invent beyond that

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

MAINTAINERS.md (1)

39-44: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Record this governance approval in the change log before merge.

Because this PR changes AGENTS.md, add a dated entry under MAINTAINERS.md’s change log recording approval by @lidge-jun or @Ingwannu. The current log only documents the prior @Wibias maintainer change and does not satisfy the PR’s stated completion requirement for this governance update.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@MAINTAINERS.md` around lines 39 - 44, Update MAINTAINERS.md’s change log with
a dated entry documenting governance approval for the AGENTS.md change by either
`@lidge-jun` or `@Ingwannu`, alongside the existing `@Wibias` entry, before merge.

AGENTS.md (1)

49-61: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Resolve the contradictory dev2-go targeting rules.

Lines 49-61 still make a dev2-go PR invalid unless it touches Go/native-port files, but lines 72-77 say shared TypeScript changes may belong on both tracks and that the old Go-only rule is no longer sufficient. This can cause valid dual-track work to be rejected or retargeted incorrectly. Align lines 49-61 with the interim policy—for example, retain dev as the default while allowing maintainer-directed shared changes to target or land on dev2-go.

Based on learnings, shared changes should land on both tracks when applicable without inventing dual-base PRs.

Also applies to: 63-77

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` around lines 49 - 61, Update the dev2-go targeting rules in
AGENTS.md so dev remains the default branch while maintainer-directed shared
changes may target or land on dev2-go when applicable. Remove the requirement
that every dev2-go pull request touch Go/native-port scope and ensure the
surrounding policy consistently states that shared changes should be applied to
both tracks through separate pull requests, without requiring dual-base PRs.

Source: Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@AGENTS.md`:
- Around line 49-61: Update the dev2-go targeting rules in AGENTS.md so dev
remains the default branch while maintainer-directed shared changes may target
or land on dev2-go when applicable. Remove the requirement that every dev2-go
pull request touch Go/native-port scope and ensure the surrounding policy
consistently states that shared changes should be applied to both tracks through
separate pull requests, without requiring dual-base PRs.

In `@MAINTAINERS.md`:
- Around line 39-44: Update MAINTAINERS.md’s change log with a dated entry
documenting governance approval for the AGENTS.md change by either `@lidge-jun` or
`@Ingwannu`, alongside the existing `@Wibias` entry, before merge.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ec3b4e41-5bec-450f-9b6d-0092570e0812

📥 Commits

Reviewing files that changed from the base of the PR and between c008aa3 and af0a18c.

📒 Files selected for processing (2)

• AGENTS.md
• MAINTAINERS.md

[Wibias]

Branch-policy update (matches owner endgame)

Replaced the earlier dual-track / land on both wording. Agents were about to follow the wrong story.

Now documented in AGENTS.md + MAINTAINERS.md:

• dev2-go = home base (dogfood / triage / features / behavior / TS+Go sync)
• dev PRs allowed, but do not merge until the same change is also on dev2-go (rebase/retarget and/or add Go)
• hotfixes: dev first + needs-go-port → follow up on dev2-go
• no duplicate contributor PRs; maintainers rebase dev2-go onto dev
• planned endgame: FF dev ← dev2-go, retire dev2-go intake; preview before latest; promotion freeze with the FF

Note for this PR: it still targets dev (governance-only is fine), but under the new rule it also needs to land on dev2-go before merge so agents on that line read the same policy. Happy to open/retarget the follow-up.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 54-58: Align the branch-policy exception across all authority
files: update AGENTS.md lines 54-58 to remove the exception or require
governance changes to be covered on dev2-go, apply the same requirement in the
review guidance at AGENTS.md lines 146-149, and keep the authoritative merge
policy consistent in MAINTAINERS.md lines 21-28.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 22d221a8-5dc2-4f91-86ad-dff83051440a

📥 Commits

Reviewing files that changed from the base of the PR and between af0a18c and b5f041d.

📒 Files selected for processing (2)

• AGENTS.md
• MAINTAINERS.md

[Wibias]

CodeRabbit follow-up

Addressed on latest push:

1. Governance exception — removed. Docs/CI/governance may still target dev, but must also be on dev2-go before merge (same as other dev PRs). Only needs-go-port hotfixes may merge on dev first.
2. Review guidance — same rule; no governance carve-out.
3. Change log — added 2026-07-29 endgame-policy entry marked governance approval still open (will close when @lidge-jun / @Ingwannu review).

Not re-applied: the “Go-only dev2-go vs dual-track contradiction” finding — that text is already gone after the endgame rewrite.

This PR: under the updated rule it still needs to land on dev2-go before merge (retarget or follow-up).

[Wibias]

Intake policy updated (owner-confirmed)

Rewrote branch policy to the locked day-to-day init:

1. merge → dev (default PR target)
2. rebase dev2-go onto that
3. port go/ only if needed, otherwise leave it

Paused: freeze features on dev / put behavior on dev2-go first.
Kept: dev2-go is not a release-promotion source; planned FF collapse + preview-before-latest + promotion freeze with FF.

[Wibias]

Transition workflow completed

1. Merged into dev: a47aa3fe (docs: harden and scope agent guidance #583) — nested AGENTS + CODEOWNERS; kept owner Transition intake already on dev.
2. Carried onto dev2-go: docs: carry agent guidance hardening onto dev2-go (#583) #659 (cherry-pick of that merge).
3. Go port: none — docs/governance only (decision recorded).