docs: canonicalize GitHub workflow guidance

.ai-context/WORKFLOWS.md

@@ -2,141 +2,37 @@
 
 ## Pre-Edit Workflow Gate
 
-Before modifying Base files, classify the request.
-
-For implementation work in `basefoundry/base`, do not edit on `main`. Create
-or choose the GitHub issue, set the required Project metadata, move Project
-`Status` to `In Progress`, create the issue branch and dedicated worktree, and
-verify the active branch is not `main` before editing files.
-
-Read-only investigation, design-only discussion, and requests explicitly scoped
-to local-only/no-PR work may stay outside this gate. If the scope turns into
-issue-backed implementation work after edits have started, stop, create or
-choose the issue, move the work onto the issue branch/worktree, and then
-continue.
+Before modifying Base files, follow the canonical [pre-edit workflow
+gate](../docs/github-workflow.md#pre-edit-workflow-gate). It distinguishes
+issue-backed implementation from read-only investigation, design discussion,
+and explicitly local-only work; implementation begins in an issue-backed
+worktree rather than on `main`.
 
 ## Issue-First Work
 
-Base uses GitHub Issues as the public product backlog. Implementation work
-should start from a GitHub issue with one primary category label:
-
-- `bug`
-- `enhancement`
-- `documentation`
-- `ci`
-- `security`
-
-Do not create new `type:*` labels.
-
-Issues created by automation should be assigned to `codeforester` when GitHub
-allows it. When an issue is tracked in the repo-named Project, move its status
-through `In Progress`, `In Review`, and `Done` as the work advances. Repo-named
-Project metadata uses five fields: `Status`, `Priority`, `Area`, `Size`, and
-`Initiative`.
-Use `Agentic Coding Platform` for GitHub-centered agentic workflow work such as
-agent-ready repo baselines, agent-readiness checks, issue-readiness gates,
-Copilot/cloud-agent readiness, current local context evidence, and planned
-handoff artifacts such as #1562. The workspace-level agent brief from #1561 is
-shipped local evidence in this initiative.
-Use the smallest accurate `Size` when creating issues: `T` for tiny obvious
-work, `S` for normal small work or unknown scope, `M` for interacting changes,
-and `L` only for work that should probably be split. The default remains `S`
-when automation cannot infer scope.
-Issue creation is unassigned by default unless `basectl gh issue create`
-receives `--assignee <login>` or `.github/base-project.yml` sets
-`project.issue_defaults.assignee`; use `--no-assignee` to skip that repo-local
-default for a specific issue.
-Starter issues for first external contributors use the `good first issue`
-label only when the issue has explicit acceptance criteria, concrete Project
-metadata, `Size` `T` or `S`, and local validation that does not require private
-state. Use `help wanted` without `good first issue` for broader work where
-outside help is useful but deeper Base context is needed.
-
-When updating GitHub issues, pull requests, labels, comments, or Project
-metadata, protect the API budget. Use a read-plan-write flow: fetch the target
-IDs and current values, compute the minimal local diff, then write only changed
-fields. Do not run parallel mutating GitHub requests. Prefer exact issue and
-Project item updates, exact-item GraphQL mutations, or
-`basectl gh project issue set-fields` with known targets over broad scans. Cache
-IDs during the train, pause between bulk writes, and obey `retry-after`,
-`x-ratelimit-reset`, secondary-limit, and content-generation-limit responses. If
-a limit is hit, stop writes and report completed and remaining targets before
-resuming later. Consider GitHub Apps only for recurring multi-repo automation
-that needs a separate installation budget and narrowly scoped permissions.
-
-Base-managed repositories should carry `.github/workflows/project-intake.yml`
-as the fallback for issues created outside `basectl gh issue create`.
-`basectl repo init` seeds it for new repositories, and `basectl repo configure`
-creates it when missing from older repositories.
-They should also carry `.github/workflows/issue-branch-policy.yml`; this trusted
-workflow publishes the semantic category/issue status without checking out PR
-code, queues default-branch refreshes for matching open PRs after issue
-relabeling, aggregates all open PRs sharing a head SHA, and `repo configure`
-promotes a recent trusted default-branch
-dispatch to a GitHub-Actions-bound required status.
-When a shared repo or Project schema repair needs to roll across a local repo
-family, use `basectl workspace configure --dry-run` first, then
-`basectl workspace configure`; it delegates to the same idempotent per-repo
-`repo configure` path and reports configured, skipped, and failed repos.
-If a repo Project has GitHub's default `View 1` instead of the standard Base
-views, use `basectl repo configure --replace-project` with `--repo`; Base
-archives the old Project and recreates it from `base-project-template`.
-Already-standard Projects are left intact and continue through metadata repair.
+Base uses GitHub Issues as the public product backlog. Use the canonical
+[GitHub Workflow](../docs/github-workflow.md) for issue labels, assignment,
+repo-named Project metadata and status, readiness, API-budget safeguards, and
+repository workflow configuration. Keep this file focused on AI-context-specific
+guidance, including agent-ready repo baselines, and link there instead of
+copying those rules.
 
 ## Branch And Worktree Flow
 
-Use a dedicated worktree for PR work. Branch names follow:
-
-```text
-<category>/<issue>-<YYYYMMDD>-<slug>
-```
-
-The allowed categories are `bug`, `enhancement`, `documentation`, `ci`, and
-`security`; short or provider-specific prefixes are not aliases. Base-managed
-repositories enforce this for every non-default remote branch through the
-`Base branch naming` GitHub ruleset, while `basectl gh pr create` fails early
-for an invalid local branch, including an impossible calendar date. The prefix
-must match the issue's single category label. The trusted Issue Branch Policy
-workflow publishes the GitHub-Actions-bound `base/issue-branch-policy` status
-on the PR head and refreshes it after issue relabeling. GitHub statuses are
-SHA-scoped, so the workflow validates every open PR sharing that SHA; the
-branch-name ruleset remains the immediate remote boundary for repo-owned
-branches, while the status adds semantic validation for raw Git and forks.
-
-The standard worktree location is:
-
-```text
-~/work/base-worktrees/<slug>
-```
-
-Start from current `origin/main`, keep the worktree while the PR is open, and
-clean it up after merge.
+Use the canonical [branch and worktree
+flow](../docs/github-workflow.md#worktrees) for branch naming, worktree
+location, review lifetime, and cleanup. This context file does not repeat
+those repository-wide rules.
 
 ## Pull Requests
 
-Pull requests are issue-backed by default and scoped to one issue unless there
-is a documented exception. `basectl gh pr create` adds `Fixes #<issue>` from
-Base branch names by default; pass `--no-fixes` only when the PR should not
-close the issue automatically. If `base_manifest.yaml` declares `github.pr`,
-the command renders required PR sections from that project policy. PR bodies
-should include:
-
-- summary of what changed and why
-- issue reference such as `Fixes #<issue>` or `Closes #<issue>`
-- validation commands and relevant output
-- `Demo Impact`
-- notes or tradeoffs when helpful
-- whether `.ai-context/` was updated or not applicable
-
-The issue owns milestone and Project tracking. PRs should inherit relevant
-labels but should not be added as duplicate Project items by default.
-
-When a PR is closed because another PR supersedes it, the agent owns the full
-close-and-cleanup operation: verify the replacement, link it in the closing
-comment, delete the remote head branch, remove agent-created local branches and
-worktrees, and verify cleanup. Preserve user-owned or dirty worktrees unless
-the user explicitly approves removal, and do not hand failed cleanup back as a
-user task.
+Pull requests are issue-backed by default and scoped to one issue. Follow the
+canonical [GitHub Workflow](../docs/github-workflow.md) for PR creation,
+required body sections, metadata, and issue/Project tracking. Keep this file's
+AI-context-specific guidance separate from that repository-wide policy.
+
+When a replacement PR supersedes another, follow the canonical [superseded PR
+closure procedure](../docs/github-workflow.md#superseded-pull-requests).
 
 ## Validation
 

AGENTS.md

@@ -22,83 +22,13 @@ them.
 
 ## GitHub Workflow
 
-### Pre-Edit Workflow Gate
-
-Before modifying files in this repository, classify the request.
-
-- For implementation work in `basefoundry/base`, do not edit on `main`.
-- First create or choose the GitHub issue, set required Project metadata, move
-  Project `Status` to `In Progress`, create the issue branch and worktree, and
-  verify the active branch is not `main`.
-- Only start file edits after the issue-backed worktree is active.
-- Read-only investigation, design-only discussion, and requests explicitly
-  scoped to local-only/no-PR work may stay outside this gate, but keep that
-  scope explicit in the handoff.
-- If edits start before the work is recognized as issue-backed implementation
-  work, stop, create or choose the issue, move the work onto the issue
-  branch/worktree, and then continue.
-
-### Standard Issue Flow
-
-- Create or choose a GitHub issue before implementation work.
-- Use one primary category label: `bug`, `enhancement`, `documentation`, `ci`,
-  or `security`.
-- Do not create or apply `type:*` issue labels.
-- Assign agent-created Base repository issues to `codeforester` when GitHub
-  allows it; `.github/base-project.yml` carries this repo-local default for
-  `basectl gh issue create`.
-- For issues tracked in the repo-named Project, set Project `Status` to
-  `In Progress` before implementation starts, move it to `In Review` when the
-  PR opens, and verify `Done` after merge/closure. If Project V2 access or item
-  state prevents an update, mention that in the work summary.
-- When creating issues, choose Project `Size` from actual scope: `T` for tiny
-  obvious work, `S` for normal small work or unknown scope, `M` for interacting
-  changes, and `L` only for work that should probably be split.
-- Prefer `basectl gh` for supported issue, branch, PR, check, and cleanup
-  operations.
-- Fall back to the GitHub connector, raw `gh`, or `git` when `basectl gh` does
-  not support the needed operation or local tooling is unavailable.
-- For GitHub issue, PR, label, comment, or Project metadata writes, treat API
-  budget as shared infrastructure: serialize mutating requests, compute minimal
-  diffs before writing, prefer exact issue, Project item, or GraphQL operations
-  over broad scans, and pause between bulk writes.
-- If GitHub reports rate pressure, a secondary limit, a content-generation
-  limit, or a `retry-after` delay, stop mutating state and report what
-  completed, what remains, and when it is safe to resume.
-- Branch from `origin/main` with
-  `<category>/<issue>-<YYYYMMDD>-<slug>`.
-- Treat that branch shape as tool-independent: do not substitute `feat/`,
-  `agent/`, `codex/`, a bare issue number, or another provider-specific prefix.
-  The prefix must match the issue's single category label. `basectl gh pr
-  create` rejects invalid or mismatched names, the GitHub branch naming ruleset
-  rejects invalid non-default branches at the remote boundary, and the required
-  `base/issue-branch-policy` status checks semantic matches across every open PR
-  sharing the head commit.
-- Use a dedicated worktree under `~/work/base-worktrees/<slug>` for PR work.
-- Before creating a worktree, check whether the current checkout is already a
-  linked worktree for the intended issue.
-- Link PRs with `Fixes #<issue>` or `Closes #<issue>` when merge should close
-  the issue.
-- After merge, sync `main`, remove the worktree, and delete local and remote
-  branches.
-
-### Superseded Pull Request Closure
-
-- If a pull request is closed because another pull request supersedes it,
-  closure and cleanup are one operation. Do not leave the head branch as a
-  user follow-up.
-- Verify that the replacement pull request contains the work, add a closing
-  comment linking it, close the superseded pull request, delete its remote head
-  branch, remove agent-created local branches and worktrees, and verify that
-  the branch and worktree are gone.
-- Do not delete a user-owned or dirty worktree without explicit approval. If a
-  cleanup step fails, keep ownership of the blocker and report it as unfinished
-  work rather than handing the cleanup back to the user.
-- Ordinary closed pull requests are not automatically branch-cleanup
-  candidates; use this flow only when supersession has been established.
-
-See `docs/github-workflow.md` for the full policy, including PR body sections,
-milestones, GitHub Projects, and cleanup rules.
+Before implementation, complete the [pre-edit workflow
+gate](docs/github-workflow.md#pre-edit-workflow-gate) and work from the
+issue-backed worktree. Use the [GitHub Workflow](docs/github-workflow.md) for
+the canonical issue, repo-named Project, branch, worktree, pull request, and
+cleanup policy, including [superseded pull
+requests](docs/github-workflow.md#superseded-pull-requests). This file adds
+only the agent-specific repository guidance below.
 
 ## Repository Release Contract
 

CONTRIBUTING.md

@@ -20,65 +20,11 @@ for issue-backed work, validation, and design-only sessions.
 
 ## Workflow
 
-1. Create or choose a GitHub issue before starting implementation work.
-2. Make sure the issue has one primary GitHub-style category label:
-   - `bug` for defects, regressions, or correctness issues.
-   - `enhancement` for new capabilities, product improvements, refactors, and
-     most maintenance work.
-   - `documentation` for documentation-only work.
-   - `ci` for GitHub Actions, tests, release automation, or CI reliability.
-   - `security` for security hardening, dependency pinning, static analysis, or
-     permission tightening.
-3. When the issue is tracked in the repo-named Project, set its Project
-   `Status` to `In Progress` before branch or worktree work begins. Move it to
-   `In Review` when the PR opens, and verify it is `Done` after merge/closure.
-4. Create a branch from the issue using this convention:
-
-   ```text
-   <category>/<issue>-<YYYYMMDD>-<slug>
-   ```
-
-   Example:
-
-   ```text
-   enhancement/179-20260528-projects-list-json
-   ```
-
-   `basectl gh issue start <number>` can generate the branch name and matching
-   `git worktree add` command from the issue label and title.
-
-   This is a repository rule, not an AI-tool convention. Do not replace the
-   category with `feat`, `agent`, `codex`, or another tool-specific prefix.
-   Base-managed GitHub configuration enforces the pattern on every non-default
-   remote branch, and `YYYYMMDD` must be a real calendar date. The category
-   must also match the issue's single primary category label. `basectl gh pr
-   create` rejects an invalid or mismatched local branch, and the required
-   `base/issue-branch-policy` status applies the same semantic check to pull
-   requests opened through raw Git or another tool.
-
-5. Use an isolated Git worktree for each pull request:
-
-   ```bash
-   git fetch origin main
-   git worktree add -b <branch> ~/work/base-worktrees/<slug> origin/main
-   ```
-
-6. Keep the PR scoped to the issue. Avoid unrelated refactors.
-7. Link the PR back to the issue with `Fixes #<issue>` or `Closes #<issue>`.
-8. Use the standard PR body and fill in Summary, Issue, Validation, Demo
-   Impact, and Notes.
-9. After merge, sync `main`, remove the worktree, and delete the local and
-   remote branches:
-
-   ```bash
-   git -C ~/work/base pull --ff-only origin main
-   git -C ~/work/base worktree remove ~/work/base-worktrees/<slug>
-   git -C ~/work/base branch -d <branch>
-   git -C ~/work/base push origin --delete <branch>
-   ```
-
-For the full policy, including milestone and GitHub Project guidance, see
-[GitHub Workflow](docs/github-workflow.md).
+Use the [GitHub Workflow](docs/github-workflow.md) for the complete
+issue-backed workflow, including labels, repo-named Project status, branch and
+worktree rules, PR linking, review, supersession, and cleanup. In brief, start
+from an issue, implement off `main` in a dedicated worktree, keep the PR scoped
+to that issue, and clean up after merge.
 
 ## Contributor Setup
 

STANDARDS.md

@@ -665,25 +665,11 @@ git diff --check
    - `ci`
    - `security`
    - `needs-demo`
-6. Issues created by Codex or other automation should be assigned to
+6. Issues created by agents or other automation should be assigned to
    `codeforester`.
-7. Every non-default branch must match
-   `<category>/<issue>-<YYYYMMDD>-<slug>`, where `category` is one of `bug`,
-   `enhancement`, `documentation`, `ci`, or `security`. This rule applies to
-   humans, AI tools, GitHub Actions, and repository helpers; tool-specific
-   prefixes are not exceptions. `YYYYMMDD` must be a real calendar date. The
-   category must equal the issue's single primary category label; a
-   syntactically valid but mismatched prefix is not canonical.
-8. Base-managed repositories should enforce that branch shape with the active
-   `Base branch naming` GitHub ruleset. `basectl gh pr create` must reject a
-   nonconforming or category-mismatched branch before opening a pull request,
-   and the source-bound `base/issue-branch-policy` status must perform the same
-   semantic check for raw Git and other tools before merge. Issue category
-   changes must automatically revalidate open pull requests.
-9. Pull request work should happen in a dedicated worktree.
-10. Prefer `basectl gh` when it supports the workflow. Fall back to raw `gh`,
-   the GitHub connector, or `git` when needed.
-11. PR descriptions should include:
+7. Follow [GitHub Workflow](docs/github-workflow.md) for issue-backed Project,
+   branch, worktree, pull request, supersession, and cleanup requirements.
+8. PR descriptions should include:
    - what changed
    - why it changed
    - validation commands