docs(governance): align issue/commit granularity guidance (#7)

Author: tinmanworks

AGENTS.md

@@ -9,3 +9,4 @@ This repository is the source for generating C/C++ template repositories.
 3. Treat setup scripts as cross-platform contracts (`sh`, `ps1`, `cmd`).
 4. Validate all model scaffolds before release.
 5. Preserve low-friction defaults and explicit error messaging.
+6. For GitHub Project-managed repos, implement only against clear issues; keep issues and commits small and issue-scoped by default (`one issue -> one small commit set`), with documented exceptions for non-diff, discovery-first, or unavoidable architecture-wide work.

templates/common/AGENTS.md

@@ -20,5 +20,9 @@ This repository follows Tinman Doctrine.
    - Avoid secrets in commits and docs
 4. Delivery quality bar:
    - Keep changes small and focused
+   - If work is tracked in GitHub Projects, implement only against a clear issue
+   - Prefer small, unambiguous issues; split broad tasks into manageable subtasks
+   - Keep commits small and issue-scoped; default to one issue -> one small commit set
+   - Exceptions are allowed for non-diff tasks, discovery-first work, or unavoidable architecture-level changes; document rationale in the issue or PR
    - Ensure lint/tests/build pass for touched areas
 5. If local repo policy conflicts with doctrine snapshot, follow local repo files and call out the conflict explicitly.

templates/common/docs/doctrine/repo-management.md

@@ -1,7 +1,7 @@
 # Repo Governance Doctrine
 
 Status: Stable  
-Last Reviewed: 2026-02-28
+Last Reviewed: 2026-03-04
 
 ## Scope
 
@@ -18,8 +18,9 @@ This is policy and doctrine, not automation.
 
 1. Commit signing policy
 2. Commit message policy
-3. Repo placement policy (Personal vs Organization)
-4. Visibility policy (Public vs Private vs Internal)
+3. GitHub Projects issue and commit granularity policy
+4. Repo placement policy (Personal vs Organization)
+5. Visibility policy (Public vs Private vs Internal)
 
 ## Commit Signing Policy
 
@@ -126,6 +127,56 @@ For important repositories (templates, core libs, product repos), enforce both:
 - Signed commits
 - CI or hook-based commit message linting against this policy
 
+## GitHub Projects Issue and Commit Granularity Policy
+
+### Applicability
+
+Mandatory when a repository is associated with a GitHub Project used for planning and execution.
+Advisory (not mandatory) for playground/experimental repositories that are not project-managed.
+
+### Required outcome
+
+- Work is issue-driven when the repo is project-managed.
+- Issues are small, specific, and unambiguous.
+- Commits are small and manageable by default.
+- Feature/fix/refactor delivery remains traceable from issue to implementation.
+
+### Issue definition rules
+
+- Define issue scope clearly (what to change and what is out of scope).
+- State expected result and completion criteria.
+- Avoid broad issue titles/descriptions that hide implementation decisions.
+- Split large work (feature, fix, refactor) into manageable issues or subtasks.
+- If an issue starts broad (research/discovery), split it into concrete sub-issues once implementation paths are known.
+
+### Issue-to-commit mapping
+
+- Default mapping: one issue -> one small commit set.
+- A commit set may contain multiple commits, but commits must remain within one issue scope.
+- Keep commit units logically staged and reviewable.
+- Reference the issue in commits/PRs where repository conventions support it.
+
+### Exceptions
+
+- Non-diff operational issues (for example, external settings or service configuration) may be completed without a repository commit.
+- Discovery-first issues may begin broad before decomposition.
+- Unavoidable architecture-level changes may require a larger commit set.
+- Even when larger changes are required, stage commits logically and document rationale in the issue or PR.
+
+### Execution gating
+
+- For project-managed repos, do not implement ad-hoc work without a corresponding issue.
+- Create or refine the issue first, then implement.
+- Close issues only after acceptance criteria are met.
+
+### Enforcement baseline
+
+For important repositories (templates, core libs, product repos), enforce:
+
+- GitHub Projects usage discipline (work tracked by issues)
+- Issue templates that require scope + expected result + completion criteria
+- PR or CI checks that encourage issue linkage where feasible
+
 ## Repo Placement Policy (Personal vs Organization)
 
 ### Keep in personal account when