diff --git a/.ai-context/WORKFLOWS.md b/.ai-context/WORKFLOWS.md index 238d7f0c..1bd76aaf 100644 --- a/.ai-context/WORKFLOWS.md +++ b/.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 ` 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 -/-- -``` - -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/ -``` - -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 #` 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 #` or `Closes #` -- 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 diff --git a/AGENTS.md b/AGENTS.md index 37038daf..1ec03b82 100644 --- a/AGENTS.md +++ b/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 - `/--`. -- 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/` 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 #` or `Closes #` 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 343073eb..f5a5161d 100644 --- a/CONTRIBUTING.md +++ b/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 - /-- - ``` - - Example: - - ```text - enhancement/179-20260528-projects-list-json - ``` - - `basectl gh issue start ` 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 ~/work/base-worktrees/ origin/main - ``` - -6. Keep the PR scoped to the issue. Avoid unrelated refactors. -7. Link the PR back to the issue with `Fixes #` or `Closes #`. -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/ - git -C ~/work/base branch -d - git -C ~/work/base push origin --delete - ``` - -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 diff --git a/STANDARDS.md b/STANDARDS.md index 05018dfe..b8af774f 100644 --- a/STANDARDS.md +++ b/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 - `/--`, 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 diff --git a/skills.md b/skills.md index a4d4f4df..90fb1f15 100644 --- a/skills.md +++ b/skills.md @@ -5,55 +5,19 @@ Coding standards live in `STANDARDS.md`. ## GitHub Issue And PR Workflow -Use this workflow when creating GitHub issues, branches, worktrees, or pull -requests for Base. - -- Prefer `basectl gh` for supported Base repository GitHub workflows so Base - dogfoods its own issue, branch, PR, and repository hygiene tool. -- Fall back to the GitHub connector, raw `gh`, or `git` when `basectl gh` does - not support the needed operation or local `gh` authentication/tooling is not - available. -- Assign Codex-created issues to `codeforester`. -- Use GitHub default-style labels: - - `bug` for defects. - - `enhancement` for features, refactors, and most maintenance. - - `documentation` for docs-only changes. - - `ci` for GitHub Actions, tests, and release automation. - - `security` for hardening, dependency pinning, and static analysis. -- Do not create new `type:*` labels. -- Name branches as `/--`, for example - `bug/245-20260529-fix-profile-project-prompt`. The category prefix must match - the issue's single standard category label. -- Do not use provider-specific alternatives such as `feat/`, `agent/`, - `codex/`, or a bare `-` branch. The same server-side rule applies - to every AI tool and human contributor. -- Do all pull request implementation work in a dedicated worktree under - `~/work/base-worktrees/`. -- Before creating a worktree, check whether the current checkout is already a - linked worktree for the issue. Do not create nested or duplicate worktrees. -- Keep the PR worktree available while review feedback is pending. After merge, - sync `main`, remove the worktree, and delete local and remote branches. -- Link PRs to issues with `Fixes #` or `Closes #`. -- See `docs/github-workflow.md` for the full policy, including milestones and - GitHub Projects. +Use the [GitHub Workflow](docs/github-workflow.md) for the canonical issue, +Project, branch, worktree, pull request, and cleanup policy. Before editing, +complete its [pre-edit workflow gate](docs/github-workflow.md#pre-edit-workflow-gate) +and prefer `basectl gh` for supported operations; use the documented fallbacks +when necessary. Assign agent-created issues to `codeforester` when GitHub +allows it. ## Close a superseded pull request -Use this workflow when a pull request will not merge because another pull -request carries its implementation. Treat the close decision and branch -cleanup as one operation for every AI tool and human contributor: - -- verify that the replacement pull request contains the superseded work; -- add a closing comment linking the replacement pull request; -- close the superseded pull request and delete its remote head branch; -- remove agent-created local branches and worktrees, then verify cleanup; -- preserve user-owned or dirty worktrees unless the user explicitly approves - their removal; and -- keep ownership of any failed cleanup instead of making it a user follow-up. - -Do not apply this cleanup to an ordinary closed pull request without an -established replacement. See `docs/github-workflow.md` for the detailed close, -delete, and verification procedure. +When a replacement PR carries the work, follow the canonical [superseded PR +closure procedure](docs/github-workflow.md#superseded-pull-requests), including +the closing comment and branch/worktree cleanup. Do not apply it to an ordinary +closed PR without an established replacement. ## Debug and verify Base behavior diff --git a/tests/test_contract_hardening.py b/tests/test_contract_hardening.py index 5bcaa544..eef06ab0 100644 --- a/tests/test_contract_hardening.py +++ b/tests/test_contract_hardening.py @@ -191,13 +191,14 @@ def test_superseded_pr_cleanup_guidance_is_shared_across_ai_tools() -> None: "workflow": " ".join(workflow.split()), "ai_context": " ".join(ai_context.split()), } - for text in normalized.values(): - assert "replacement" in text - assert "cleanup" in text - - assert "closing comment" in normalized["agents"] - assert "delete its remote head branch" in normalized["agents"] - assert "agent-created local branches and worktrees" in normalized["skills"] + for name in ("agents", "skills", "ai_context"): + assert "docs/github-workflow.md" in normalized[name] + assert "superseded-pull-requests" in normalized[name] + assert "cleanup" in normalized[name] + + assert "replacement" in normalized["workflow"] + assert "closing comment" in normalized["workflow"] + assert "remote head ref" in normalized["workflow"] assert "user-owned or dirty worktree" in normalized["workflow"] assert "cleanup step fails" in normalized["workflow"] assert "gh pr close " in normalized["workflow"]