diff --git a/.codingstandardrc b/.codingstandardrc index db3fe1c..2832cca 100644 --- a/.codingstandardrc +++ b/.codingstandardrc @@ -1,4 +1,4 @@ source = "https://github.com/wesley-dean/coding_standards.git" -version = "coding_standards@v2.1.0" -sha256 = "ee04401441a3206d5cdc2bdc2e6d5130ff278ddc1ecd641f1c01843aa0666020" +version = "coding_standards@v3.2.0" +sha256 = "f4e09cc804b254c79d1139a7413f2ec5311c05e44deca93965e36b9e85ae51c8" destination = "doc/standards" diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 3de7676..3f46de2 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -29,8 +29,8 @@ updates: prefix-development: chore include: scope groups: - minor-and-patch: + # Group eligible routine major/minor/patch versions, excluding security updates. + actions-version-updates: applies-to: version-updates - update-types: - - "minor" - - "patch" + patterns: + - "*" diff --git a/AGENTS.md b/AGENTS.md index c750cc2..44e3b3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -131,7 +131,7 @@ and focused fixtures. ## Shared Coding Standards -This repository adopts the complete pinned `coding_standards@v2.1.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization. +This repository adopts the complete pinned `coding_standards@v3.2.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization. Authoritative shared documentation standards used here: diff --git a/README.md b/README.md index 6fc819f..e8c0f5e 100644 --- a/README.md +++ b/README.md @@ -261,10 +261,14 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and ## Shared Coding Standards -This repository adopts the complete pinned `coding_standards@v2.1.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization. +This repository adopts the complete pinned `coding_standards@v3.2.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization. Authoritative shared documentation standards used here: - Python: `doc/standards/python/documentation-standard.md` - AWK: `doc/standards/awk/documentation-standard.md` + +## Dependabot Maintenance + +Routine GitHub Actions dependency version updates remain weekly with a seven-day cooldown. Eligible major, minor, and patch versions can be grouped under `actions-version-updates`; security updates remain independent. Groups containing a major upgrade require targeted manual review and are excluded from the existing non-major-only auto-merge path. Existing Dependabot PRs are not presumed superseded. See [ADR-013](doc/adr/ADR-013-consolidate-github-actions-dependabot-maintenance.md). diff --git a/doc/adr/ADR-013-consolidate-github-actions-dependabot-maintenance.md b/doc/adr/ADR-013-consolidate-github-actions-dependabot-maintenance.md new file mode 100644 index 0000000..f66e9b8 --- /dev/null +++ b/doc/adr/ADR-013-consolidate-github-actions-dependabot-maintenance.md @@ -0,0 +1,89 @@ +# ADR-013: Consolidate GitHub Actions Dependabot Version Updates + +Date: 2026-11-12 + +## Status + +Accepted + +## Decision + +Keep the repository's weekly GitHub Actions Dependabot version-update +schedule, seven-day cooldown, and existing commit-message convention. +Replace `minor-and-patch` with a single `actions-version-updates` group +using `applies-to: version-updates` and `patterns: ["*"]`, without +`update-types`. Eligible major, minor, and patch routine updates may be +grouped together. Security updates remain separate from scheduled version +updates and must not be delayed by the cooldown. + +Retain the existing `dependabot/fetch-metadata` guard excluding +`version-update:semver-major` from automatic merging. A group +containing a major upgrade must receive targeted manual review of its +highest-risk dependency and all material compatibility changes. + +## Context, Constraints, and Assumptions + +Previously, the minor/patch-only group allowed major GitHub Actions +versions to create additional routine PRs. The adopted +`coding_standards@v3.2.0` release recommends a balanced weekly +per-ecosystem group with a seven-day cooldown to reduce review volume, +without asserting a fixed number of PRs. + +The maintained Python documentation translator is an AWK filter with +precisely governed recognition and preservation of Python source, +structured fields, Doxygen integration, supported AWK portability, +and three validated release artifact flavors. Accepted ADRs 001-012 +remain authoritative. GitHub Actions dependency changes can affect +those testing and release-trust boundaries without changing source. + +The only configured Dependabot ecosystem is GitHub Actions. The +auto-merge condition, required-check identities, token permissions, +and release-authority boundaries must remain unchanged. Effective +GitHub CODEOWNERS enforcement, branch rules, and Dependabot security +update settings require separate verification: repository YAML +does not establish those controls. + +## Alternatives Considered + +1. Keep minor/patch-only grouping. Rejected as the default because + major versions would continue generating separate routine PRs + without inherently stronger review evidence. +2. Group major/minor/patch versions per ecosystem. Chosen to reduce + routine review fragmentation, with major-containing groups + excluded from the non-major-only auto-merge path. +3. Move to monthly updates or extend the cooldown. Rejected because + delaying routine visibility has not been justified by maintenance + evidence or compatibility needs. +4. Auto-merge groups containing major updates. Rejected because + breaking changes and altered Action privileges may affect tests, + documentation, release validation, and published artifacts. +5. Close existing Dependabot PRs immediately. Rejected because a + changed configuration does not prove their dependencies have + been replaced or validated. + +## Consequences, Risks, and Verification + +Routine version-update PR count may decline, but resolver conflicts, +incompatible versions, or multiple update classes can still produce +separate PRs. Grouped failures may be harder to isolate. A risky or +incompatible dependency may justify a narrowly governed grouping +exception, without ignoring its updates entirely. + +Each grouped PR requires review of each dependency's release notes, +permissions, migration impact, and test/release-path evidence. +Major-containing groups must not enter the existing automatic-merge +route. Existing Dependabot PR #18 stays open unless later updates +demonstrably supersede it with sufficient checks. + +Observe actual post-merge Dependabot runs and compare PR counts and +review effort. Verify security-alert and security-update settings +and effective review protections independently. No change to +Python translation, AWK source, test fixtures, compatibility floor, +Doxygen representation, or release artifact contract is authorized. + +## Related Decisions + +ADR-012 governs the frozen released standards snapshot and its +provenance; ADR-011 governs three generated artifact flavors; +ADRs 001-010 govern parsing, representation, integration, and +testing. This ADR supplements, but does not supersede, them. diff --git a/doc/decisions.md b/doc/decisions.md index d2c7ccd..d86cf24 100644 --- a/doc/decisions.md +++ b/doc/decisions.md @@ -129,7 +129,7 @@ offline artifact-generation primitive. See **Status:** Accepted -The repository adopts the complete verified `coding_standards@v2.1.0` snapshot +The repository currently pins the complete verified `coding_standards@v3.2.0` snapshot beneath `doc/standards/`, with exact release provenance recorded in `.codingstandardrc`. Applicable imported standards govern where relevant while accepted repository-specific ADRs and explicit local policy retain precedence for @@ -140,3 +140,14 @@ historical ADR text remains unchanged. Future standards upgrades replace the complete snapshot through normal review rather than local edits or automatic synchronization. See [ADR-012](adr/ADR-012-adopt-shared-coding-standards.md). + +## ADR-013: Consolidate GitHub Actions Dependabot Version Updates + +Routine GitHub Actions version updates retain their weekly schedule and seven-day +cooldown, but a wildcard group now permits eligible major, minor, and patch +upgrades to appear together. Dependabot security updates remain separate; a +major-containing group requires targeted manual review and remains outside the +existing non-major auto-merge path. No Python filter behavior, source parsing, +release artifact, or documentation compatibility contract is changed. + +See [ADR-013](adr/ADR-013-consolidate-github-actions-dependabot-maintenance.md). diff --git a/doc/standards/examples/repository/github/dependabot.yml b/doc/standards/examples/repository/github/dependabot.yml new file mode 100644 index 0000000..b4dd102 --- /dev/null +++ b/doc/standards/examples/repository/github/dependabot.yml @@ -0,0 +1,24 @@ +# Non-normative GitHub Actions example. Copy to .github/dependabot.yml +# through a separate reviewed repository change. Add other ecosystems +# deliberately after reviewing their manifests and CI evidence. +# +# Source: standards/general/dependabot-maintenance-standard.md +--- +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + cooldown: + default-days: 7 + commit-message: + prefix: fix + include: scope + groups: + # Routine major, minor, and patch releases in one version-update group. + # Security updates use independent repository settings/triggering. + actions-version-updates: + applies-to: version-updates + patterns: + - "*" diff --git a/doc/standards/examples/repository/github/pull-request.md b/doc/standards/examples/repository/github/pull-request.md index 4a5f1f7..713ecd6 100644 --- a/doc/standards/examples/repository/github/pull-request.md +++ b/doc/standards/examples/repository/github/pull-request.md @@ -30,10 +30,11 @@ merely because the build step completed successfully. ## Verification -- [x] Relevant automated tests pass. -- [x] Generated or distributed artifacts were verified where applicable. -- [x] Documentation affected by this change was updated. -- [x] Governing ADRs and standards affected by this change were reviewed. +- [x] Local archive structure and checksum verification passed. +- [x] CI is still pending; no CI pass is claimed yet. +- [x] Generated archive locally verified against the documented contract. +- [x] Documentation affected by this change updated. +- [x] Governing ADRs and standards affected by this change reviewed. ## Known Limitations and Follow-Up @@ -46,7 +47,8 @@ artifact signing; that remains separate scope. - [x] The pull request title reflects the highest semantic significance of the complete change. - [x] The diff remains within the declared scope. -- [x] Required verification has been completed to the extent available. +- [x] Available author-side verification completed and honestly reported. - [x] Material assumptions, limitations, and risks are visible. -- [x] The pull request is ready for normal review and may be merged once repository - checks and review requirements are satisfied. +- [x] Final planned commits pushed; no further implementation is expected. +- [x] PR marked Ready while CI remains pending. +- [x] Auto-merge armed; protected CI and human review gate merge. diff --git a/doc/standards/examples/repository/github/rulesets/ci-gate-main.json b/doc/standards/examples/repository/github/rulesets/ci-gate-main.json new file mode 100644 index 0000000..b75bbe9 --- /dev/null +++ b/doc/standards/examples/repository/github/rulesets/ci-gate-main.json @@ -0,0 +1,27 @@ +{ + "name": "CI check gate (reviewed example)", + "target": "branch", + "enforcement": "active", + "bypass_actors": [], + "conditions": { + "ref_name": { + "include": [ + "refs/heads/main" + ], + "exclude": [] + } + }, + "rules": [ + { + "type": "required_status_checks", + "parameters": { + "strict_required_status_checks_policy": true, + "required_status_checks": [ + { + "context": "test-gate" + } + ] + } + } + ] +} diff --git a/doc/standards/examples/repository/github/workflows/ci-gate.yml b/doc/standards/examples/repository/github/workflows/ci-gate.yml new file mode 100644 index 0000000..bd4061f --- /dev/null +++ b/doc/standards/examples/repository/github/workflows/ci-gate.yml @@ -0,0 +1,34 @@ +--- +# Non-normative reference example; copy through a reviewed local change. +# PR-head ref below is suitable for branch-push test checks. Review mixed +# push/PR event and fork semantics before using as an authoritative gate. +name: CI check gate + +# yamllint disable-line rule:truthy +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + checks: read + +jobs: + aggregate: + name: test-gate + runs-on: ubuntu-24.04 + timeout-minutes: 120 + permissions: + contents: read + checks: read + steps: + - name: Wait for observed standardized CI checks + uses: matiasalbarello/wait-on-check-action-ts@8087812521cdb59ebc7751984b31b17209b30eeb # v1.2.0 + with: + ref: ${{ github.event.pull_request.head.sha }} + repo-token: ${{ github.token }} + check-regexp: '^(test|e2e|end-to-end|integration|lint|security|build|compat)(-.+)?$' + running-workflow-name: test-gate + allowed-conclusions: success,skipped,cancelled + fail-on-no-checks: 'false' + wait-interval: '10' diff --git a/doc/standards/general/dependabot-maintenance-standard.md b/doc/standards/general/dependabot-maintenance-standard.md new file mode 100644 index 0000000..dff94af --- /dev/null +++ b/doc/standards/general/dependabot-maintenance-standard.md @@ -0,0 +1,204 @@ +# Consolidated Dependabot Version Update Standard + +## Status + +Recommended engineering standard + +## Purpose + +This standard reduces recurring Dependabot pull-request review work across a +portfolio of repositories while preserving security response, relevant CI +evidence, major-upgrade scrutiny, and repository approval protections. + +The shared default is a **weekly, per-ecosystem group of routine version +updates**, with a **seven-day version-update cooldown**. Major, minor, and +patch updates are eligible for the same routine group. Security updates +remain a separate process and MUST NOT be intentionally delayed or mixed +with routine version updates. + +Reducing PR count is an operational objective, not a promise of exactly one +PR per ecosystem per week or any particular portfolio-wide reduction. + +## Applicability and Governance + +Apply this standard when a repository uses GitHub Dependabot for scheduled +version updates. Repositories without supported dependency manifests or +with deliberately different requirements MAY document a local exception +through an accepted ADR or explicit repository policy. + +This standard does not require a repository to enable every Dependabot +package ecosystem. A repository MUST configure only ecosystems and +directories that actually apply to its maintained dependencies. + +The [reference Dependabot configuration](../examples/repository/github/dependabot.yml) +uses the `github-actions` ecosystem because that is the common pilot +across template-bash, adrctl, bashdeps, bashlog, and mktext. Additional +ecosystems SHOULD use the same grouping and scheduling principles when +their dependency semantics and test coverage make doing so appropriate. + +A standards release provides governing text and a **non-normative** +reference configuration. Receiving the file in `doc/standards/` MUST +NOT create or replace `.github/dependabot.yml`. Local adoption is an +independent reviewed change, consistent with ADR-003 and ADR-009. + +## Scheduled Version-Update Baseline + +For each routinely maintained package ecosystem, the default SHOULD be: + +- `schedule.interval: weekly` for actively maintained projects; +- `cooldown.default-days: 7` for ordinary version updates; +- one broadly matching group for `applies-to: version-updates`; +- `patterns: ["*"]` so all eligible named dependencies in that + ecosystem may be grouped; +- **no** `update-types` restriction on the broad group, allowing major, + minor, and patch releases together; and +- no newly restrictive `open-pull-requests-limit` while an existing + dependency-update backlog is being reconciled. + +The `github-actions` reference group is named +`actions-version-updates`. Other ecosystems MAY use a clear +ecosystem-specific group name. Grouping is normally scoped per +package ecosystem. Cross-ecosystem grouping is not part of this +baseline and MUST NOT be presumed to occur automatically. + +The default does not require fixed weekdays or time zones: repositories +MAY select scheduling windows appropriate to their maintenance and +CI workloads. + +A low-activity repository MAY choose `schedule.interval: monthly` +through explicit local governance. A cooldown up to 30 days MAY be +considered for low-activity repositories when the additional routine +update delay is acceptable. Neither slower scheduling nor a longer +cooldown may be treated as a substitute for security updates. + +Do not impose an artificially low open-PR limit merely to hide backlog +volume. A low limit can suppress useful new version update proposals +while stale PRs occupy the available slots. Review or reconcile the +existing queue before changing the limit. + +## Security Update Independence + +The wildcard group MUST specify `applies-to: version-updates`. It MUST +NOT silently group security updates, or make security fixes wait for a +weekly or monthly scheduled version-update cycle. The `cooldown` +setting governs version updates, not Dependabot security updates. + +Repositories relying on automated security remediation MUST verify +that the dependency graph, Dependabot alerts, and Dependabot security +updates are enabled and appropriately configured in their GitHub +settings. A `dependabot.yml` version-update schedule does not itself +establish this prerequisite. + +A separate, explicitly governed security-update grouping policy MAY +exist, but it MUST NOT be conflated with or inferred from the routine +version-update group. Prompt security handling remains an independent +requirement. + +## Major Upgrades and Review Controls + +Bundling a major release with minor and patch releases is intentional. +A grouped PR MUST be reviewed according to its **highest-risk change**, +including release notes, migration impact, trust boundary, and the +test evidence that actually exercises the affected behavior. + +A grouped PR containing any major update MUST NOT become eligible for +automatic merge merely because other dependencies in the group are +minor or patch updates. Where `dependabot/fetch-metadata` is used, +its documented `update-type` output represents the highest SemVer +change in a grouped PR; any major-containing group SHOULD be held out +of the non-major auto-merge path. Repositories MUST verify that the +actual auto-merge condition enforces the intended boundary. + +For non-major-only groups, requesting automatic merge MAY remain +permitted where existing repository governance permits it, but GitHub +MUST still enforce its configured required checks, CODEOWNERS review, +branch protections, and rulesets. A successful auto-merge workflow does +not itself prove the PR was approved or merged. + +Review of each changed dependency is still necessary. In particular, +GitHub Actions with write-capable tokens, release-publishing authority, +tag creation, package or container registry credentials, signing access, +or other privileged operations deserve targeted evidence. Passing a +linter or unit test that never exercises a changed release workflow +does not prove that release workflow remains safe or functional. + +Preserve full-commit-SHA pinning and other established provenance rules +when maintaining GitHub Actions dependencies. A grouped update MUST NOT +silently relax an independently governing dependency security standard. + +## Repository-Specific Grouping Exceptions + +The broad wildcard is a default, not a requirement to mix every +dependency into one PR under all circumstances. + +Repositories MAY define narrow `exclude-patterns`, separate named +version-update groups, or independent update entries for dependencies +whose authority or migration needs justify isolation. Examples include +sensitive release automation, registry authentication, and changes +that need separately exercised compatibility tests. + +Exceptions MUST be documented, scoped to the reason for isolation, +and periodically reconsidered. Excluding a dependency **from a group** +is different from ignoring its updates entirely; avoid `ignore` rules +as a substitute for routing a dependency into its own review path. + +Multiple package ecosystems SHOULD generally have separately reviewed +groups, since runtime packages, container bases, and GitHub Actions +present different change and verification surfaces. No single-PR +guarantee spans all ecosystems or repositories. + +## Adoption and Backlog Reconciliation + +A maintainer or agent adopting this model SHOULD: + +1. Review repository governance, existing Dependabot configuration, + package ecosystems, update-specific ADRs, and required PR gates. +2. Measure the current open Dependabot PR backlog and existing grouping + and cadence before changing the policy. +3. Copy and adapt the reference YAML into `.github/dependabot.yml` + through a normal reviewed repository PR; merge with any existing + ecosystem entries instead of replacing them blindly. +4. Keep security updates separate and verify the repository-level + security configuration and effective CODEOWNERS protections. +5. Preserve the existing non-major-only auto-merge behavior, or + document a separate reviewed decision if changing it. +6. Leave pre-existing PRs open until a later actual grouped PR + demonstrably covers their updates and necessary test evidence; + do not assume Dependabot will retroactively consolidate them. +7. Observe subsequent Dependabot runs, compare PR volume and + maintainer review effort, inspect grouped failures, and refine + narrow exceptions only when evidence supports them. + +A group may fail resolution or contain an incompatible upgrade. Split +or isolate the problematic dependency when needed rather than making +all of the grouped changes an automatic approval. + +## Failure Modes and Limits + +- Wildcard groups admit major releases, including breaking changes. +- One grouped failure can be harder to diagnose than an isolated PR. +- Resolver constraints, update availability, unsupported dependencies, + or group failures can still generate multiple separate PRs. +- Existing PRs are not guaranteed to be closed or replaced when a group + is added. +- A seven-day cooldown reduces routine release churn but does not + prove an upstream version is trustworthy. +- Disabled or misconfigured security-update settings leave a separate + vulnerability-remediation gap. +- Review and CODEOWNERS requirements must be enforced by GitHub + rulesets/branch protection, not by the mere presence of a + `CODEOWNERS` file. +- Grouping alone does not reduce PRs across multiple repositories; + it reduces eligible updates **within an ecosystem in one repository**. + +## Related Governance + +The [Development Workflow and Backlog Governance](development-workflow-governance.md) +continues to govern authorized work, PR readiness, review, and auto-merge. +The [General Testing Standard](testing-standard.md) governs meaningful +validation and aggregate failure reporting. The +[GitHub Actions Check Naming and Optional-Presence Gate Standard][check-gate] +does not prove mandatory tests ran, and a green `test-gate` MUST NOT be +mistaken for complete dependency compatibility or release-path evidence. + +[check-gate]: github-actions-check-gate-standard.md diff --git a/doc/standards/general/development-workflow-governance.md b/doc/standards/general/development-workflow-governance.md index a63f650..4051e69 100644 --- a/doc/standards/general/development-workflow-governance.md +++ b/doc/standards/general/development-workflow-governance.md @@ -244,6 +244,19 @@ match this convention. See ADR-011 for the decision context, alternatives, compatibility implications, and relationship to Conventional Commit release governance. +## Opt-In Three-Phase Development + +Repositories MAY explicitly adopt the companion +[Opt-In Three-Phase Development Governance](three-phase-development-governance.md) +standard by setting `three_phase_development = true` in the repository-root +`.codingstandardrc`. This adds separate Product Owner and Technical Architect +approval gates, issue-based story/task traceability, and a defined task queue. +Absent or `false` settings preserve the baseline workflow described here. +Standards upgrades MUST NOT silently change an existing repository's explicit +selection. The optional profile's more specific requirements govern where +it has been deliberately enabled, without weakening this document's core +scope, security, or review requirements. + ## Backlog Issues A backlog issue SHOULD contain enough information for another contributor to @@ -308,71 +321,104 @@ work. ## Draft and Ready-for-Review Lifecycle -New pull requests SHOULD be opened in draft mode. - -Draft status communicates that implementation, verification, documentation, -cleanup, or author review may still be in progress. A draft pull request MAY be -read, discussed, or inspected, but reviewers and maintainers SHOULD NOT interpret -its existence as a request to perform final review or merge it. - -Transitioning a pull request from Draft to Ready for review is an explicit project -signal. Once marked Ready for review, the author is declaring that: - -- the requested work is complete for the intended scope; -- the pull request description accurately represents the change; -- required verification has been performed to the extent available; -- known relevant documentation has been updated; -- the pull request is ready for normal review; and -- the pull request may be merged at any time once repository checks, review - requirements, and other merge gates are satisfied. - -A pull request SHOULD NOT be marked Ready for review merely to solicit preliminary -feedback while substantial known implementation work remains. Discussion during -implementation belongs on the draft pull request, issue, or other project channel. - -If substantive new work makes a Ready pull request incomplete again, the pull -request SHOULD return to draft status when the hosting platform and permissions -permit it. +New pull requests SHOULD be opened in draft mode. Draft status indicates +author-controlled implementation, documentation, verification, cleanup, or +review remains unfinished. A draft PR is not a request for final review. + +### Handoff after the final planned commit + +An automated coding agent MUST promptly mark a PR Ready for review when: + +- all currently planned changes within the authorized scope, including + necessary tests and documentation, are committed and pushed; +- no further implementation commits are presently expected; +- author-side verification has been performed to the extent practical, with + results, omissions, and limitations accurately disclosed; +- the PR title, description, issue links, and material risks represent + the current diff; and +- no unresolved material architecture, scope, security, compatibility, or + release decision prevents final review. + +When those conditions hold, the agent MUST make the transition before +ending its implementation handoff. Neither a possibility of later, +unanticipated corrective commits nor pending/running CI checks is a reason +to leave the PR in Draft. The agent MUST NOT wait solely for CI completion +before marking the PR Ready. + +Ready communicates that the author has finished planned work and is asking +for human review. It does not establish that CI has passed, that merge is +authorized, or that a technical task or story has satisfied its separate +Definition of Done. + +A known failing check the agent is actively fixing, or other substantial +known work requiring another planned commit, means author-side work remains +unfinished. The PR SHOULD remain Draft while that work continues. A failed +or missing required check MUST NOT be reported as passed or bypassed. + +### Later corrections + +A CI failure or review finding discovered after handoff does not automatically +invalidate a valid Ready transition. Narrow corrective commits MAY be made +while Ready if the PR remains accurate and reviewable. If substantial work +resumes or a material decision reopens, the agent SHOULD return the PR +to Draft when platform permissions allow it. Repository stale-approval and +most-recent-reviewable-push rules MUST continue to apply. Agents MUST NOT +bypass or presume that those protections exist. + +### Verified handoff + +Before ending an implementation session, the agent MUST inspect and report +the PR URL, its actual Draft/Ready state, whether auto-merge was successfully +armed, and the known verification state, including pending, failing, or +unavailable checks. A forbidden, failed, unsupported, or unsafe transition +MUST be reported explicitly rather than silently skipped. An agent MUST NOT +claim unobserved CI success or promise future monitoring without an +actual monitoring mechanism. ## Automatic Merge After Review -When a pull request is Ready for review, is intended for normal integration, and -the hosting platform and repository permit auto-merge, automated coding agents -SHOULD enable auto-merge. +After an agent-authored PR is Ready for review, the agent MUST enable +auto-merge when the hosting platform supports it, the repository permits +it, all required review and validation gates are verified to remain +enforced, and no separate manual-merge decision or material blocker applies. +Pending or running CI alone MUST NOT delay this action when those checks +remain required conditions for merge. -Enabling auto-merge delegates only the mechanical merge operation to the hosting -platform. It MUST NOT be treated as approval, as a substitute for human review, -or as permission to bypass required CI, CODEOWNERS approval, branch protection, -rulesets, security review, or any other repository gate. +Auto-merge delegates only the mechanical merge operation to the platform. +It MUST NOT constitute approval or bypass CI, CODEOWNERS approval, branch +protection, rulesets, security review, or any other required gate. -Auto-merge is appropriate when all of the following are true: +Auto-merge is appropriate only when: -- the pull request is Ready for review; -- the requested work is complete for the intended scope; -- the pull request is expected to merge once ordinary repository gates succeed; -- no additional maintainer decision is known to be required beyond those gates; +- the PR is Ready and currently planned author work is complete; +- all required checks and reviews will remain enforced before merge; +- the PR is intended for ordinary integration after those gates succeed; +- no additional human decision is required beyond those configured gates; and -- the hosting platform will enforce the repository's normal merge requirements - before completing the merge. +- the normal merge strategy and reviewed semantic classification are preserved. + +An automated agent MUST NOT enable auto-merge when: -An automated agent SHOULD NOT enable auto-merge when: +- the PR is still Draft or known implementation work remains incomplete; +- the maintainer has requested a separate manual merge; +- unresolved architecture, security, compatibility, release, or scope questions + require a decision; +- required merge gates are unknown or cannot be verified to remain in force; +- human approval is expected but not enforced, so the PR could merge before + that human review; or +- auto-merge would weaken, bypass, or obscure an authorization boundary. -- the pull request remains a draft; -- the maintainer has requested manual merge control; -- unresolved architectural, security, compatibility, release, or scope questions - require an explicit decision before merge; -- required merge gates are not understood or cannot be verified to remain in - force; or -- auto-merge would weaken, bypass, or obscure an intended human authorization - boundary. +A required failed check must continue to block merge. CODEOWNERS approval is +compatible with arming auto-merge before review, because the hosting platform +continues enforcing that human gate. -A required CODEOWNERS review is compatible with auto-merge. In that model, the -CODEOWNERS approval remains the human authorization gate, while the hosting -platform performs the merge only after that approval and all other required -conditions have been satisfied. +If auto-merge is unsupported, forbidden, or unsafe, the agent MUST leave it +disabled and report why. If requested, the agent MUST verify the platform +accepted the auto-merge operation and report the actual result. -When an agent enables auto-merge, it SHOULD preserve the repository's normal merge -strategy and reviewed commit-title or release-classification requirements. +Repositories SHOULD dismiss stale approvals or require approval of the +most recent reviewable push so corrective commits cannot silently evade +human review. Agents MUST obey the protections actually configured. ## Squash Merges @@ -583,9 +629,11 @@ An agent has implemented most of a task but still needs to finish tests and upda usage documentation. The pull request may remain open in draft mode so its work is visible and discussion can occur. -Once the implementation, verification, and documentation are complete, the agent -marks the pull request Ready for review. That transition means a maintainer may -review and merge it whenever the repository's normal gates permit. +Once the agent has pushed the last planned implementation, test, and +documentation changes, it marks the PR Ready even if CI is still pending. +It enables auto-merge if the repository's required review and CI gates +can be verified as enforced. The maintainer can review immediately; the +platform waits for every required condition before merging. ### Security Finding @@ -617,10 +665,13 @@ verify that: - security-sensitive findings were handled through the appropriate process; - architectural decisions were not smuggled into implementation without required governance; and -- Ready-for-review status accurately means the pull request can be reviewed and - merged once normal repository gates are satisfied; and -- auto-merge, when enabled, leaves every required review, CI, branch-protection, - CODEOWNERS, security, and other merge gate in force. +- agent-authored PRs move from Draft to Ready after final planned commits, + without waiting solely for pending CI; +- passing, pending, failing, and unavailable checks are reported accurately; +- auto-merge is verifiably armed when safe or a specific blocker is reported; + and +- auto-merge preserves every required CI, CODEOWNERS, security, review, and + other merge gate. ## Repository Adoption @@ -670,6 +721,11 @@ person. ## Related Templates +When the optional three-phase profile is enabled, its non-normative +[User Story](../templates/repository/github/user-story.md) and +[Technical Task](../templates/repository/github/technical-task.md) templates +provide reference issue structures. + The non-normative repository templates provide reusable structures for work governed by this document: diff --git a/doc/standards/general/github-actions-check-gate-standard.md b/doc/standards/general/github-actions-check-gate-standard.md new file mode 100644 index 0000000..daf104e --- /dev/null +++ b/doc/standards/general/github-actions-check-gate-standard.md @@ -0,0 +1,230 @@ +# GitHub Actions Check Naming and Optional-Presence Gate Standard + +## Status + +Recommended engineering standard + +## Purpose + +This standard establishes predictable GitHub Actions check-run names and a +single, observable aggregate status for repositories that choose to use the +`matiasalbarello/wait-on-check-action-ts` GitHub Marketplace action. It is designed to +permit a new repository created from a template to have no matching checks +yet, without manufacturing a failed build, while accepting matching checks +**observed by the action** when their conclusions are `success`, `skipped`, or +`cancelled`. + +The aggregation contract is intentionally weaker than a complete expected-test +inventory. A passing gate MUST NOT be represented as proof that tests ran, +that every expected check appeared, or that every workflow was enabled. + +## Applicability + +The check-name convention applies to GitHub Actions CI jobs in repositories +using this standard. The Marketplace aggregator and ruleset reference are for +GitHub-hosted repositories; the [General Testing Standard](testing-standard.md) +continues to govern test content and failure semantics independently. + +Repositories that already have required check names MUST preserve their +effective branch protections and check identities during adoption. This +standard does not retroactively rename jobs, add required status contexts, +activate branch rulesets, or supersede repository-specific accepted ADRs. + +## Check-Run Naming Convention + +GitHub Checks reports **job names**, not workflow filenames or merely +workflow-level display names. Repositories using the gate SHOULD give each +eligible job a stable lowercase `jobs..name` matching one of these +case-sensitive patterns: + +| Check family | Pattern | Valid examples | +| --- | --- | --- | +| General tests | `^test(-.+)?$` | `test`, `test-unit`, `test-bats` | +| End-to-end tests | `^(e2e|end-to-end)(-.+)?$` | `e2e`, `end-to-end-protocol` | +| Integration tests | `^integration(-.+)?$` | `integration`, `integration-db` | +| Lint and format | `^lint(-.+)?$` | `lint`, `lint-shellcheck` | +| Security analysis | `^security(-.+)?$` | `security`, `security-codeql` | +| Build validation | `^build(-.+)?$` | `build`, `build-container` | +| Compatibility | `^compat(-.+)?$` | `compat`, `compat-bash43` | + +The combined pattern used by the gate is: + +```regex +^(test|e2e|end-to-end|integration|lint|security|build|compat)(-.+)?$ +``` + +It matches both an exact family name and a family name followed by a hyphen +and at least one character. For example, `test` and `test-unit` match; +`testing`, `testy-little-test`, `my-test`, and `test-` do not. + +The name `test-gate` also matches this pattern and MUST be excluded from +the gate's own polling to prevent a self-dependency. A repository MAY use +different nomenclature through explicit local governance, but it MUST adapt +its regex and rule configuration accordingly rather than silently weakening +the declared selection policy. + +When a matrix or reusable workflow changes the actual published check name, +the repository MUST verify the name as reported by GitHub rather than infer +it from the YAML source. + +## Presence Is Optional; Accepted Conclusions Are Explicit + +**No check family is mandatory solely because it is listed here.** In +particular, a newly created repository MAY have zero test, E2E, +integration, lint, security, build, or compatibility jobs and still receive +a successful aggregate result. + +The required Marketplace action configuration is: + +```yaml +allowed-conclusions: success,skipped,cancelled +fail-on-no-checks: 'false' +``` + +`fail-on-no-checks: 'false'` is a deliberate policy choice, not an exception +to be removed during template initialization. The action's upstream default +is `true`, so repositories MUST set `false` explicitly when adopting this +profile. The action's upstream default for `allowed-conclusions` accepts +`success` and `skipped`; this profile MUST explicitly configure the three +accepted conclusions as `success,skipped,cancelled`. + +The resulting observational policy is: + +- Zero matching check runs: the aggregate MAY succeed. +- One or more matching check runs: the action waits for the matched checks + it observes and accepts conclusions of `success`, `skipped`, or `cancelled`. +- A matching check with a conclusion outside that explicit list, including + `failure`, `timed_out`, `action_required`, or `neutral`, MUST NOT be accepted. +- Accepted `skipped` and `cancelled` conclusions MUST NOT be presented as + evidence that test execution completed successfully. Cancellation can result + from concurrency supersession or interruption; neither proves coverage. +- A check that is absent because no job was defined, a workflow was disabled, + a job was never scheduled, the wrong revision was queried, or an expected + run has not yet appeared is **not necessarily detected**. + +This profile MUST NOT be described as requiring at least one test, proving all +tests were run, proving the repository is secure, or guaranteeing complete CI +coverage. + +## Standard Aggregate Job + +A GitHub Actions repository adopting this profile SHOULD maintain one +separate aggregation workflow with an actual GitHub check-run name of +`test-gate`. It SHOULD use the published Marketplace action with a fully +pinned commit SHA, the combined expression above, read-only +`checks: read` access, and a bounded job timeout. + +The aggregator MUST exclude `test-gate` from its own matched checks using +`running-workflow-name: test-gate` or an independently verified equivalent. +It MUST NOT require each test workflow to run its own copy of the waiting action. + +The current reference is +[`matiasalbarello/wait-on-check-action-ts`](https://github.com/matiasalbarello/wait-on-check-action-ts), +release `v1.2.0`, resolved to commit +`8087812521cdb59ebc7751984b31b17209b30eeb`. This native Node.js 24 +GitHub Action uses a bundled JavaScript distribution instead of runtime Ruby +setup and Bundler installation. It paginates Checks API results across multiple +pages. Maintainers MUST review any change to the selected action revision and +its bundled/transitive JavaScript dependencies as a supply-chain change. +Pinning identifies code; it does not prove that code is trustworthy. + +A non-normative [GitHub workflow example](../examples/repository/github/workflows/ci-gate.yml) +provides a concrete starting point. Copying it from an adopted standards +snapshot to `.github/workflows/` is a separate, reviewed repository change, +not part of standards adoption. + +## Commit Identity and Workflow Events + +The action queries checks against the configured Git ref. A workflow's event +type affects where GitHub attaches the result: for example, branch-push jobs +generally report against the branch head SHA, while pull-request-triggered +jobs may report against the synthetic PR merge SHA. + +A repository MUST verify which ref contains **each check family it intends +to observe**, rather than presume that one PR head/merge SHA represents every +workflow. A single-regex action invocation over one ref may omit checks +attached to another revision. The example targets PR-head branch-push checks +and is not a universal mixed-event or fork-compatible solution. + +Repositories MUST retain any separately required checks that this aggregator +does not reliably observe. Fork PRs, merge queues, status check source +identity, workflow path filters, and conditional jobs require separate local +review before asserting compatibility. + +## Incomplete-Inventory and Early-Success Limits + +The Marketplace action evaluates matching checks present in its API results. +It does **not** derive the expected checks from repository workflow files. + +Consequently, a check that finishes early may allow the aggregator to succeed +before another intended check has been registered. If one check matches, +`fail-on-no-checks: 'false'` does not establish that any *other* expected +check exists. A disabled workflow or job renamed outside the regex might not +be noticed. These properties are not bugs in the chosen optional-presence +contract; they are limits of observable-check aggregation. + +Unlike the original Ruby action, the selected TypeScript implementation does +not collapse duplicate check names to the latest run. When old and new check +runs share a name on the same ref, it can consider both, so a superseded failed +run may still fail the aggregate even after a newer run succeeds. Conversely, +its API pagination avoids a first-page-only check inventory. Repositories +SHOULD verify duplicate check, rerun, and multi-suite behavior against actual +GitHub check runs before treating the gate as a reliable merge signal. + +A repository MUST NOT use this aggregate as the sole evidence of mandatory +security, release, compliance, or other fail-closed verification unless +separate controls independently establish the required coverage and trusted +check identity. Existing individually required checks MUST remain effective +until an explicit, reviewed migration establishes an equivalent or stronger +result. + +## Ruleset Declaration and Activation + +The [importable JSON ruleset example](../examples/repository/github/rulesets/ci-gate-main.json) +declares the exact `test-gate` status-check context for the repository's +`main` branch. GitHub rulesets name **specific** required status checks; +the regex belongs in the waiting action, not in the ruleset. + +Importing JSON through GitHub settings is an explicit administrative action. +Committing the example inside `doc/standards/` does not activate it, nor +does adopting a standards release install any workflow. The example is +a **single-check ruleset fragment**, not a replacement for CODEOWNERS review, +pull-request protections, or other active policy. Its `active` enforcement +setting takes effect upon an administrator's deliberate import and creation, +so maintainers MUST inspect and adapt the branch target and existing +protections before importing it. + +A repository SHOULD enable the required `test-gate` status check only after +verifying the gate executes for its intended pull requests and produces its +result on the commit identity required by branch protection. A green +`test-gate` remains the optional-presence assertion described above; +GitHub requiring that check to pass does not strengthen the meaning of the +action's observed-check selection. + +## Adoption and Review Checklist + +1. Inventory all existing required status contexts and their actual GitHub + check-run names; do not rename a protected check without a migration. +2. Name eligible CI jobs using the standardized patterns where practical, + preserving the repository's test execution and failure propagation. +3. Copy and adapt the non-normative aggregate workflow for the repository's + actual event model, including a suitable check-ref and timeout. +4. Verify the exact action SHA, permissions, no-match success path, matching + failure path, acceptance of `skipped` and `cancelled`, rejection of other + conclusions, and the gate's self-exclusion. +5. Observe actual mixed-event, matrix, and rerun behavior before relying on + the result in review automation. +6. Import and enable the reference ruleset only as a separate administrative + decision, retaining all independently mandatory checks and CODEOWNERS gates. +7. Document any checks outside the observed ref or outside the prefix taxonomy, + plus any repository-specific stronger completeness requirements. + +## Relationship to Other Standards + +The [General Testing Standard](testing-standard.md) continues to govern test +quality, required project test commands, generated artifact qualification, +failure propagation, and credential safety. The +[Development Workflow and Backlog Governance](development-workflow-governance.md) +continues to govern review readiness and auto-merge under effective human and +CI gates. This convention standardizes check naming and optional-presence +reporting without replacing those requirements. diff --git a/doc/standards/general/three-phase-development-governance.md b/doc/standards/general/three-phase-development-governance.md new file mode 100644 index 0000000..a10c119 --- /dev/null +++ b/doc/standards/general/three-phase-development-governance.md @@ -0,0 +1,183 @@ +# Opt-In Three-Phase Development Governance + +## Status + +Optional repository governance; normative only when explicitly enabled. + +## Purpose + +This standard extends [Development Workflow and Backlog Governance](development-workflow-governance.md) with three phases: product planning, technical planning, and implementation. It does not replace baseline scope control, architecture, testing, security, or PR governance. Its purpose is to make a project's approved requirements, work, decisions, and progress reconstructible without relying on a prior conversation. + +MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative when the profile is enabled. + +## Activation and Compatibility + +The repository root `.codingstandardrc` MAY contain: + +~~~toml +three_phase_development = true +~~~ + +Omitted or explicitly `false` means disabled. No repository is enrolled based on its age, template origin, or a standards upgrade. Missing configuration means disabled; a malformed or non-Boolean value MUST be reported and MUST NOT be interpreted as authorization. A new-project initialization SHOULD explicitly enable the profile after adopting and recording a verified standards release. Existing repositories retain their previously selected governance unless they explicitly opt in through a reviewed change. + +Standards adoption, upgrade, downgrade, and repair MUST preserve the repository's explicit workflow selection. The optional field does not alter the existing `source`, `version`, `sha256`, or `destination` provenance fields. An adoption process MUST NOT silently discard unrelated repository-owned configuration or fabricate provenance. + +When disabled, the existing Development Workflow and Backlog Governance standard remains applicable without the additional phase, issue-label, or approval requirements below. This profile imposes no retrospective triage requirement on an existing repository unless it opts in. + +## Roles and Boundaries + +A person MAY occupy several roles; an AI agent MAY assist in several roles, but role names and write access do not grant authorization. The project MUST retain an identifiable human or explicitly designated repository authority for consequential decisions. + +| Role | Responsibility | Approval boundary | +| --- | --- | --- | +| Product Owner | Defines product value, scope, epics, priorities, and acceptance criteria | Approves user stories for technical planning | +| Project Manager | Facilitates requirements, planning, story quality, and backlog visibility | May recommend, not self-approve | +| Technical Architect | Owns architecture, security boundaries, interfaces, and the technical plan | Approves technical tasks for development and consequential design choices | +| Senior Engineer | Decomposes approved stories into technical tasks, dependencies, and verification plans | May recommend, not self-approve | +| Implementer | Executes approved tasks, verifies outcomes, and proposes reviewable changes | May choose routine implementation details inside the approved contract | + +Delegation of approval authority MUST be documented in repository governance. Agents MUST NOT acquire authority simply by changing roles or starting another chat. + +## Phase 1: Project Management (What and Why) + +The Project Manager collaborates with the Product Owner to define product goals, scope, epics, and user stories. Stories SHOULD follow: + +> As a [role], so that [benefit], I want [capability]. + +Stories MUST capture desired behavior with observable acceptance criteria, relevant constraints, known dependencies, and exclusions. They SHOULD avoid prematurely committing to a particular implementation. Proposed stories may be created freely; their existence does not authorize technical or implementation work. + +**Exit gate:** The Product Owner authorizes technical planning by applying the `approved` label to the particular user-story issue, or by explicitly directing its application. That label is the authoritative approval state for the story's current scope and priority. Story approval does not authorize technical tasks without their own `approved` label. + +## Phase 2: Technical Planning (How) + +The Senior Engineer MUST review repository governance and accepted ADRs before proposing the implementation. Each distinct technical task SHOULD link to its parent approved story and describe implementation boundaries, dependencies, verification, compatibility requirements, and completion criteria. Stories SHOULD link back to their tasks. + +Consequential architecture, security, persistence, public-interface, deployment, and compatibility decisions MUST follow repository ADR and approval governance. A task issue cannot replace an ADR. + +**Exit gate:** The Technical Architect authorizes a technical task for development by applying the `approved` label to that task, or by explicitly directing its application after reviewing the technical approach and required ADRs. The task's own label is authoritative; an approved parent story does not approve its technical tasks. + +## Phase 3: Development (Execute and Verify) + +Before execution, an implementer MUST examine the current approved issues, governing documentation, dependencies, and blockers. Work MUST follow the priority rules below and remain within authorized task scope. Routine helpers, tests, documentation, error handling, and other necessary supporting work MAY be done without separate approval if they preserve the approved contract. + +Implementers MUST link changes and PRs to tracked tasks, report actual verification evidence, and avoid claiming delivery merely because code has been written or merged. + +**Exit gate:** A technical task is Done only after its own Definition of Done; a story is Done only when its acceptance criteria have been independently verified. Release readiness is assessed separately. Separate chats MAY represent these phases, but the repository and approval records remain authoritative. + +## Issue and Milestone Conventions + +When using GitHub, the profile SHOULD use ordinary issues, labels, milestone fields, and Markdown links; no GitHub Projects board or custom issue-management tooling is required. Repositories using another tracker MUST document equivalent, inspectable controls. + +The suggested GitHub labels are: + +| Label | Meaning | +| --- | --- | +| `type:story` | A product/user requirement | +| `type:task` | An implementation task | +| `approved` | Authoritative, sufficient approval of this issue's current scope for its phase | +| `in-progress` | Work underway on an open issue | +| `priority:high` | High priority | +| `priority:low` | Low priority | + +Neither priority label means normal priority. The two priority labels MUST NOT coexist, and each issue SHOULD have one type label. For an **open** issue, `approved` without `in-progress` means TODO; `approved` plus `in-progress` means In Progress. An open issue without `approved` is **proposed**, not TODO, regardless of any other labels. Closure with reason completed means Done only after the applicable Definition of Done; issues closed as not planned are excluded from delivered work. + +Milestones MAY represent epics. Assign milestones to product stories rather than implementation tasks so milestone completion reflects capabilities rather than engineering activities. A GitHub issue has one milestone; cross-cutting feature relationships SHOULD use references rather than double counting. Story checklists with issue links are useful navigation aids, not automatically authoritative completion measurements. Each task SHOULD link back to its story, and blockers MUST be recorded visibly. + +Label creation is a one-time repository setup step where needed. Reference templates are distributed with the standards but are not activated automatically. + +## Authoritative Approval Labels and Scope Changes + +For an opted-in repository using GitHub, the presence of the `approved` label +on an issue is the **authoritative and sufficient workflow approval record** for +that issue's current scope and phase. On a `type:story` issue it signifies +Product Owner authorization for technical planning. On a `type:task` issue +it signifies Technical Architect authorization for development, including the +bounded maintenance path. Absence of the label means the issue is not approved, +regardless of its title, milestone, issue text, or parent status. + +An additional issue comment, dated approval statement, audit of who applied the +label, or separately maintained approval section is **not required** to establish +that workflow approval. Agents and contributors selecting work MUST use the +issue's current live label state instead of reconstructing approval from comments +or cached summaries. Approval applies only to the labeled issue; it does not +flow automatically from a labeled story to its technical tasks or across phases. + +The decision to approve MUST originate with the human responsible for the +appropriate project role, or an explicitly designated repository authority. +That person MAY apply the label directly or explicitly instruct an agent or +tool to apply it to identified issues. Agents MUST NOT decide to approve their +own proposals, add the label without such a direction, infer approval from +silence, or broaden an approval to other issues. Repositories SHOULD limit +label modification to trusted actors through their available governance and +permissions. The label represents workflow approval, **not** GitHub access +control, permission escalation, a substitute for accepted ADRs, or PR review +and merge authorization. + +A materially changed approved issue MUST have `approved` removed and must +receive a new approval decision before the changed scope becomes actionable. +This includes changed acceptance criteria, new independently valuable behavior, +material interface or compatibility changes, or consequential security or +architecture decisions. Routine implementation detail within the approved +contract does not require removing the label. An agent MAY remove the label to +prevent work on materially changed scope but MUST NOT restore it autonomously. + +Immediately before beginning consequential implementation, the implementer +SHOULD re-read the issue's current labels and check applicable dependencies, +ADRs, and blockers rather than relying on a prior snapshot. This policy +changes issue-level workflow authorization evidence only; all independent +security, testing, human accountability, and repository review controls remain. + +## Newly Discovered Work and Blockers + +Agents MAY discover and create additional issue proposals during development. The default is **unapproved**. + +- Necessary supporting work within an approved task MAY proceed normally. +- Distinct additional engineering work for an existing approved story SHOULD become an unapproved technical task for Technical Architect review. +- New product functionality or materially changed story requirements MUST become an unapproved story for Product Owner review. +- Consequential design decisions require the applicable architectural review/ADR. +- Vulnerabilities or sensitive details MUST follow private security reporting rather than public issue creation. + +If new work blocks an active task, document the blocker and related proposal or decision, stop only affected work, and proceed to another approved actionable task if possible. An affected task MAY remain `in-progress` while visibly blocked. An agent MUST NOT silently reprioritize its proposals or implement them to avoid waiting for approval. + +## Definitions of Ready and Done + +**Story Ready:** Desired behavior, acceptance criteria, scope boundaries, priority, and dependencies are identifiable, and the story bears the authoritative `approved` label. + +**Task Ready:** The task bears its own authoritative `approved` label, its parent story is approved (or the maintenance exception below applies), and agreed technical scope, governing ADRs, dependencies, and a verification plan are recorded. + +**Task Done:** The authorized implementation and necessary tests/documentation are complete; relevant checks have passed or their limitations are explicitly documented; and required integration/review gates have been satisfied. + +**Story Done:** Required technical work is completed and its independently verifiable acceptance criteria have been shown to pass. Closing the final task or merging a PR is not by itself acceptance of the story. + +For the opt-in profile, use non-closing PR references such as `Refs #123` until issue closure conditions are satisfied. A closing keyword MAY be used only when merging itself fulfills the Definition of Done and `in-progress` cleanup is handled. Closing a completed issue SHOULD remove `in-progress`. A declined issue MUST NOT be counted as delivered. + +### Lightweight Maintenance Path + +A bounded defect correction, documentation fix, or routine maintenance operation MAY be approved and executed as a stand-alone technical task without a parent story, provided its own `approved` label is applied under the Technical Architect's authority and it introduces no new product behavior or consequential architecture. It still needs traceable scope, workflow approval, verification, and completion. This is not a loophole to relabel features as maintenance. Urgent security work follows the repository's secure escalation procedures. + +## Work Selection and Priority + +Unless the authorized human reprioritizes work, implementers SHALL: + +1. Finish actionable open, approved `in-progress` technical tasks first. +2. Then select approved TODO tasks marked `priority:high`. +3. Then select approved TODO tasks with normal (unlabeled) priority. +4. Finally select approved TODO tasks marked `priority:low`. +5. Within each tier prefer the oldest actionable task by issue creation time. + +Dependencies and blockers take precedence. Product stories are not execution-queue items. Prefer one active task per agent unless parallel effort has an explicit benefit. Add `in-progress` when starting an approved task; remove it and close the task with the completed reason only after verification. + +## Reporting, Handoffs, and Migration + +Reports SHOULD separately show completed versus approved technical tasks, accepted versus approved stories, and accepted stories within each epic. Include both counts and percentages, explicitly exclude rejected/not-planned work from delivered counts, and disclose any additions or removals from approved scope. Unweighted issue counts are **not** a measure of effort, delivery date, or production readiness. + +A handoff SHOULD leave enough durable issue/repository context to reconstruct current approval labels, blockers, verification results, accepted decisions, and the next actionable task without access to prior chats. + +New-project setup SHOULD set `three_phase_development = true` only after recording actual released standards provenance. Existing repositories opting in SHOULD inventory their current backlog and apply `approved` only to work authorized by the appropriate human; no preexisting issue is automatically authorized. Opting out does not waive baseline engineering, security, or review governance. + +## Related Standards and Templates + +- [Development Workflow and Backlog Governance](development-workflow-governance.md) +- [AI Safety Standard](ai/safety-standard.md) +- [User Story](../templates/repository/github/user-story.md) +- [Technical Task](../templates/repository/github/technical-task.md) diff --git a/doc/standards/templates/README.md b/doc/standards/templates/README.md index ae5b791..83c6bc3 100644 --- a/doc/standards/templates/README.md +++ b/doc/standards/templates/README.md @@ -37,7 +37,8 @@ in the completed artifact. The initial corpus contains: -- `repository/github/` for pull-request and issue templates; +- `repository/github/` for pull-request, general issue, user-story, and + technical-task templates; - `general/security/` for security and STRIDE disclosure; - `adr/` for Architecture Decision Records; and - `git/` for Conventional Commit and merge-message references. diff --git a/doc/standards/templates/repository/github/pull-request.md b/doc/standards/templates/repository/github/pull-request.md index 1661acf..b1e9f00 100644 --- a/doc/standards/templates/repository/github/pull-request.md +++ b/doc/standards/templates/repository/github/pull-request.md @@ -40,15 +40,17 @@ impact. --> ## Verification - - -- [ ] Relevant automated tests pass. -- [ ] Generated or distributed artifacts were verified where applicable. -- [ ] Documentation affected by this change was updated. -- [ ] Governing ADRs and standards affected by this change were reviewed. + + +- [ ] Author-side verification performed and reported accurately. +- [ ] Pending, failed, or unavailable CI checks identified explicitly. +- [ ] Generated or distributed artifacts verified where applicable. +- [ ] Documentation affected by this change updated. +- [ ] Governing ADRs and standards affected by this change reviewed. ## Known Limitations and Follow-Up @@ -57,14 +59,17 @@ backlog items. Remove this section when there is nothing material to disclose. ## Readiness Checklist - + - [ ] Related issues are linked where applicable. - [ ] The pull request title reflects the highest semantic significance of the complete change. - [ ] The diff remains within the declared scope. -- [ ] Required verification has been completed to the extent available. +- [ ] Available author-side verification completed and honestly reported. - [ ] Material assumptions, limitations, and risks are visible. -- [ ] The pull request is ready for normal review and may be merged once repository - checks and review requirements are satisfied. +- [ ] Final planned commits pushed; no further implementation is expected. +- [ ] PR marked Ready, without waiting solely for pending CI. +- [ ] Auto-merge armed under enforced gates, or blocker reported. diff --git a/doc/standards/templates/repository/github/technical-task.md b/doc/standards/templates/repository/github/technical-task.md new file mode 100644 index 0000000..d7dcdde --- /dev/null +++ b/doc/standards/templates/repository/github/technical-task.md @@ -0,0 +1,31 @@ +--- +name: Technical task +about: Describe bounded engineering work and verification +title: "" +labels: "type:task" +assignees: "" +--- + +## Parent Story or Maintenance Exception + + + +## Technical Objective and Implementation + + + +## Dependencies and Governing Decisions + + + +## Verification Plan + +- [ ] ... + +## Completion Criteria + + + +- [ ] ... + diff --git a/doc/standards/templates/repository/github/user-story.md b/doc/standards/templates/repository/github/user-story.md new file mode 100644 index 0000000..cb54f2a --- /dev/null +++ b/doc/standards/templates/repository/github/user-story.md @@ -0,0 +1,36 @@ +--- +name: User story +about: Describe product behavior and acceptance criteria +title: "" +labels: "type:story" +assignees: "" +--- + +## Story + +As a [role], so that [benefit], I want [capability]. + +## Problem and Value + + + +## Acceptance Criteria + + + +- [ ] ... + +## Scope, Exclusions, and Dependencies + + + +## Epic / Milestone + + + +## Related Technical Tasks + + + +- [ ] #123 +