diff --git a/docs/standards/documentation-and-citations.md b/docs/standards/documentation-and-citations.md index 8e026fe..d8617dc 100644 --- a/docs/standards/documentation-and-citations.md +++ b/docs/standards/documentation-and-citations.md @@ -27,6 +27,6 @@ A recorded upstream default, version gate, or price belongs in durable content o Every recommendation, option, or decision an author or agent presents, and every recommended number, default, limit, or "best practice" in it, carries a `Basis:` label that names where it came from: a `file:line`, a tool's output, or a URL retrieved for it in the current session, or `judgment` when no source stands behind it. The label lets a reader check the claim without re-deriving it and shows which claims rest on the author alone. -The rule covers what is presented from now on: a reply, a pull request or issue body, a design or decision record. It does not require relabeling tracked prose written before it, and a convention document is not such a presentation: its rules rest on its sources footer. +The rule covers what an author or agent presents: a reply, a pull request or issue body, a design or decision record. Existing tracked prose need not be relabeled, and a convention document is not such a presentation: its rules rest on its sources footer. -`judgment` is not enough for a decision that spans repositories, changes shared infrastructure, cannot be undone, or bears on security. When research cannot settle such a decision, present it as an open question that names the evidence that would settle it, not as a recommendation. +`judgment` alone is not enough for a decision that bears on security, a secret or a trust boundary, or that cannot be undone. When research cannot settle such a decision, present it as an open question that names the evidence that would settle it, not as a recommendation. Who decides any other judgment-only call is set by the consuming repository's or operator's own instructions. diff --git a/docs/standards/issue-tracker.md b/docs/standards/issue-tracker.md index b19ca45..8d054af 100644 --- a/docs/standards/issue-tracker.md +++ b/docs/standards/issue-tracker.md @@ -49,7 +49,7 @@ The title and Issue Type are set at filing, always, except on an issue filed thr On organization repositories the type axis is **native GitHub Issue Types**, not labels. Issue Types are an organization-level, single-select field: an issue carries **at most one** type, never two. GitHub positions them as the successor to a type-prefixed label. They are the governance mechanism for this axis; there is no parallel type label alongside them. GitHub does not require every issue to carry a type: search exposes a positive `type:"Bug"`-style qualifier per enabled type but no `no:type` negation to find the untyped remainder directly (querying `no:type` silently returns the unfiltered total, not a filtered one), so finding what's missing means comparing per-type counts against the total or reading an issue's `type` field, which is `null` when unset. An issue created via a form or API call that skips the field can silently fall outside the taxonomy this way. -**Issue creation always sets the type**, apart from the agent-ready work-item form above. CLI and agent-driven issue creation passes `--type` with one of the org's enabled native types, for example `gh issue create --type Task` (or `Bug`/`Feature`, whichever applies). The web UI's issue form surfaces the same Types field at creation time, but GitHub does not force it to be filled in there either; setting it is this policy's requirement, not something the platform enforces on either path. github-iac does not assign a type on a schedule; [ADR 0003](https://github.com/melodic-software/github-iac/blob/main/docs/adr/0003-issue-type-axis-native-issue-types.md) deleted that sweep. An issue that skips the field stays untyped until a person or the triage lane sets one of the live organization types. +**Issue creation always sets the type**, apart from the agent-ready work-item form above. CLI and agent-driven issue creation passes `--type` with one of the org's enabled native types, for example `gh issue create --type Task` (or `Bug`/`Feature`, whichever applies). The web UI's issue form surfaces the same Types field at creation time, but GitHub does not force it to be filled in there either; setting it is this policy's requirement, not something the platform enforces on either path. No scheduled job assigns a type ([ADR 0003](https://github.com/melodic-software/github-iac/blob/main/docs/adr/0003-issue-type-axis-native-issue-types.md) records why). An issue that skips the field stays untyped until a person or the triage lane sets one of the live organization types. Personal accounts have no native Issue Types, so their repositories retain a labeled type axis under the same naming grammar. This is a deliberate per-account divergence, not drift; each account's own infrastructure-as-code program is the record of which mechanism its repositories use (see "Definitions live in infrastructure-as-code" above). @@ -77,7 +77,7 @@ Issue fields are defined once for the organization by an organization owner in i Prefer a native mechanism over a status label wherever GitHub offers one, because the native mechanism carries behavior the label can only imitate: - **Blocking is a dependency edge, not a label.** Model "this cannot proceed until that is done" as a native blocked-by relationship between issues. The edge resolves itself when the blocker closes; a label has to be cleared by hand and silently goes stale. -- **Claiming is an assignee plus a lease, not a label, and the mechanism is active.** A worker taking an issue sets themselves as its assignee under a time-boxed lease, so ownership and its freshness live in the native field where a second worker can trust them, rather than in a label anyone can leave behind. The activation trigger this convention named, assignment contention becoming real, was met when autonomous multi-worker loop lanes began claiming from the same backlog; the mechanism is the work-items plugin's [tracker-seam lease protocol](https://github.com/melodic-software/claude-code-plugins/blob/main/plugins/work-items/tools/work-item-tracker/CONTRACT.md#lease-protocol), which defines the lease semantics (expiration, renewal, concurrent-claim arbitration). +- **Claiming is an assignee plus a lease, not a label.** A worker taking an issue sets themselves as its assignee under a time-boxed lease, so ownership and its freshness live in the native field where a second worker can trust them, rather than in a label anyone can leave behind. The work-items plugin's [tracker-seam lease protocol](https://github.com/melodic-software/claude-code-plugins/blob/main/plugins/work-items/tools/work-item-tracker/CONTRACT.md#lease-protocol) defines the lease semantics (expiration, renewal, concurrent-claim arbitration). - **Work status is the one status.** The organization issue field Work status holds an issue's single current status, with no sub-statuses. The name keeps it apart from a project's own Status field. - **Hold labels stack beside it.** A hold means *a human must act before work can continue*, such as waiting on the owner's decision or on the reporter's information. Holds can stack and a field holds one value, so each hold is also a flat label, spelled the same as its Work status option; the spellings are defined in infrastructure-as-code. - **Work that waits on a decision is blocked by a decision issue.** File the decision as its own issue, Work status `needs-owner-decision`, assigned to the owner, and add a blocked-by edge from the waiting issue to it. When the owner decides and the decision issue closes, the edge clears and the waiting work becomes startable. A dependency written only in prose stops nothing. @@ -88,7 +88,7 @@ Every new issue passes through triage. The floor label is the bare marker `needs A workflow applies `needs-triage` when an issue opens **without** any triage-status label already present: label-absence conditioning, not author allowlists. The creating bot or scheduler for infrastructure issues (lane telemetry, rolling reports, scheduled maintenance) applies its own status label at creation time; because the floor fires only on absence, self-labeled infrastructure issues skip it. Issue-form `labels:` and `type:` keys are the official deterministic auto-apply path for human-filed issues but fire only for template-created issues; API and bot-created issues bypass forms, so absence conditioning is the robust pattern. -Exit is human-gated: a maintainer clears `needs-triage` and sets the real Work status, priority and area during triage. Label provisioning and rename mechanics live in `github-iac`; the auto-apply workflow lives in `ci-workflows`. This playbook records the posture only. +Exit is the triage step: whoever triages, a person or the triage lane, clears `needs-triage` and sets the real Work status, priority and area. Label provisioning and rename mechanics live in `github-iac`; the auto-apply workflow lives in `ci-workflows`. This playbook records the posture only. ### Recurring and rolling items @@ -98,7 +98,7 @@ Reconcile recurring items by a dedicated bare marker label (for example `recurri ## Closing pull requests -A pull request that resolves an issue uses one of GitHub's native closing keywords as the default house style. The keyword is what wires the automatic link and auto-close on merge; a plain-text reference like "see #123" does neither, and a disclaimer around a keyword does not stop it, because GitHub's parser ignores the surrounding words. The pull-request body contract is not restated here: the `body` fields of `components/pr-convention-policy/policy.json` record it (the accepted linkage lines, including how to link without closing and the no-issue opt-out, and the required sections), and the `ci-workflows` `check-contract` composite enforces it. The practice applies org- and account-wide, not only where a CI gate can check it. The shared `check-contract` composite inside each requires-ci repository's `CI Status` check reports it, leaving an advisory comment and the `needs-issue-linkage` label rather than failing the check, and repositories without CI follow the same convention unreported. +A pull request that resolves an issue uses one of GitHub's native closing keywords as the default house style. The keyword is what wires the automatic link and auto-close on merge; a plain-text reference like "see #123" does neither, and a disclaimer around a keyword does not stop it, because GitHub's parser ignores the surrounding words. The pull-request body contract is not restated here: the `body` fields of `components/pr-convention-policy/policy.json` record it (the accepted linkage lines, including how to link without closing and the no-issue opt-out, and the required sections). The practice applies org- and account-wide, not only where a CI gate can check it. The shared `ci-workflows` `check-contract` composite inside each requires-ci repository's `CI Status` check reports it, leaving an advisory comment and the `needs-issue-linkage` label rather than failing the check, and repositories without CI follow the same convention unreported. ## Optional conventions @@ -106,7 +106,7 @@ The following are documented patterns, not requirements. Use them where they add - **🤖 marks a bot-authored comment.** A trailing 🤖 on a comment tells a human reader at a glance that an agent, not a person, wrote it. - **Cite the evidence when closing on it.** A pull request or comment that closes an issue because of external evidence (a log, a run, an upstream release) links or quotes that evidence rather than asserting the conclusion bare. -- **🔒 is retired.** The interim "I'm on this" marker served while the assignee-plus-lease mechanism above was deferred; with that mechanism active, the lease is the claim signal. Treat any 🔒 still encountered as a stale artifact of the interim period. +- **A 🔒 marker is stale.** The assignee and its lease are the claim signal; ignore any 🔒 left on an issue. ## Governance: infrastructure-as-code is the sole writer @@ -117,7 +117,7 @@ The taxonomy drifts the moment two parties can write it, so the recurrence fix i - **A rename keeps its attachments only in the documented order.** Renaming a label inside the program destroys and recreates it, stripping it from every item. Declare the new name in the program first, rename the live label through the REST API, and let no apply run between the two steps ([`github-iac` README, "Changing labels"](https://github.com/melodic-software/github-iac/blob/main/README.md#changing-labels)). Code that reads the label accepts both names before the rename and drops the old name after it. - **A label is deleted only after its readers are gone and its items are saved.** Never delete a label a workflow reads. Before a delete, save the list of items that carry it; GitHub keeps the labeled events after the label is gone, so history stays countable. - **`pulumi import` recovers a mistake.** If a label reached a repository out-of-band before anyone noticed, import it into the program's state and codify it, so the next preview is clean rather than destructive. -- **CODEOWNERS marks privileged paths, not reviewers.** CODEOWNERS is adopted only where a repository is in the org `trust-root` ruleset (claude-code-plugins, standards), which requires code-owner approval with `required_approving_review_count` still 0. In a single-maintainer org it routes no second opinion; it makes a human click the gate for App-authored and auto-merged changes to paths that reach a privileged context. Each repository's CODEOWNERS header states its rule. +- **CODEOWNERS marks privileged paths, not reviewers.** CODEOWNERS is adopted only where a repository is in the org `trust-root` ruleset, which requires code-owner approval with `required_approving_review_count` at 0; the ruleset's own target list says which repositories those are. In a single-maintainer org it routes no second opinion; it makes a human click the gate for App-authored and auto-merged changes to paths that reach a privileged context. Each repository's CODEOWNERS header states its rule. ## Related diff --git a/docs/standards/reference-dont-duplicate.md b/docs/standards/reference-dont-duplicate.md index b5e808b..a02b576 100644 --- a/docs/standards/reference-dont-duplicate.md +++ b/docs/standards/reference-dont-duplicate.md @@ -75,6 +75,6 @@ Further reading (links only, not load-bearing until a targeted primary-source ve ## Related -- Whether a page may exist at all, the admission test upstream of this discipline: see `documentation-existence.md`. -- Citing authorities *outside* the repo (vendor docs, framework references): see `documentation-and-citations.md`. -- Resolving derivable external state instead of copying a snapshot of it: see `legacy-and-migration-debt.md` for the current-form-only posture. +- Whether a page may exist at all, the admission test upstream of this discipline: see [`documentation-existence.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/documentation-existence.md). +- Citing authorities *outside* the repo (vendor docs, framework references): see [`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/documentation-and-citations.md). +- Resolving derivable external state instead of copying a snapshot of it: see [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/legacy-and-migration-debt.md) for the current-form-only posture.