diff --git a/REVIEW.md b/REVIEW.md index d213590..0004102 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -20,7 +20,7 @@ section. ## Severity -This organization's criteria (`conventions/review/` in `standards`) resolve +This organization's criteria (`standards/review/` in `standards`) resolve to three severities: **Critical**, **Important**, **Suggestion**. On this surface's three markers: @@ -36,7 +36,7 @@ to the three-tier vocabulary above and not something a criterion assigns. A finding tagged `blocking` is always 🔴 Important here, regardless of what severity its underlying criterion would otherwise carry in context. -`blocking` is this file's own tag, not a severity a `conventions/review/` +`blocking` is this file's own tag, not a severity a `standards/review/` criterion assigns. ## Depth @@ -45,7 +45,7 @@ Managed Code Review cannot resolve a citation below: `@` imports are not expanded and cited files are not read into the prompt. A self-hosted or local review using the `review` plugin can follow one into the full criterion, its severity nuance, and its sources. A citation is a path of the -form `conventions/review/.md#`, resolved relative to wherever +form `standards/review/.md#`, resolved relative to wherever the `standards` checkout root is available: this repository's own root when `standards` reviews itself, or the `--add-dir` mount root everywhere else. @@ -68,14 +68,14 @@ Always check: - A high-risk security action, such as authentication, an authorization failure, a privilege change, or sensitive-data access, has a corresponding audit-log - entry (`conventions/review/observability.md#logging`). This is an + entry (`standards/review/observability.md#logging`). This is an observability completeness check on the logging seam; whether the action itself is safe is the security lane's question. - A change that writes two or more related records, files, or state locations carries an atomicity mechanism spanning them: a transaction, an atomic rename, a constraint, or a compensation step. An interruption between steps must not leave state no code path expects - (`conventions/review/error-handling.md#atomicity`). + (`standards/review/error-handling.md#atomicity`). - No Dependabot pull request waits on a human. One whose updates are all non-major, with GitHub Actions only from `actions/*`, `github/*` or `anthropics/*`, and none in the policy's `reviewOnly` security-critical @@ -99,12 +99,12 @@ Always check: - A handler or endpoint that receives an object id (a path segment, body field, or query parameter) checks the caller is authorized for that specific record, not only that the id is well-formed. Tagged `blocking` - (`conventions/review/security.md#object-level-authorization`). + (`standards/review/security.md#object-level-authorization`). - A data-access path that reaches tenant-owned data carries an explicit tenant scope. Tagged `blocking` - (`conventions/review/multi-tenancy.md#tenant-scoped-data-access`). + (`standards/review/multi-tenancy.md#tenant-scoped-data-access`). - No secret, token, or credential is added to tracked source or config. - Tagged `blocking` (`conventions/review/security.md#secrets-and-credentials`). + Tagged `blocking` (`standards/review/security.md#secrets-and-credentials`). - A query or process invocation built from external input is parameterized, never string-concatenated. Tagged `blocking` - (`conventions/review/security.md#trust-boundaries-and-injection`). + (`standards/review/security.md#trust-boundaries-and-injection`). diff --git a/docs/standards/README.md b/docs/standards/README.md index e9adbab..3f59741 100644 --- a/docs/standards/README.md +++ b/docs/standards/README.md @@ -5,7 +5,7 @@ standards-contract: 1.0.2 # Standards index Team-layer engineering standards synced from melodic-software/standards -(`conventions/engineering/`). Change them there, not here. +(`standards/engineering/`). Change them there, not here. | Surface | Applies when | File | |---|---|---| diff --git a/docs/standards/bulk-mutation.md b/docs/standards/bulk-mutation.md index 6f09afa..fdeafd0 100644 --- a/docs/standards/bulk-mutation.md +++ b/docs/standards/bulk-mutation.md @@ -31,6 +31,6 @@ confirm-first variant rather than standing in for consent. ## Boundaries -- **vs [`deterministic-work-execution.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-work-execution.md)**: +- **vs [`deterministic-work-execution.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/deterministic-work-execution.md)**: that file covers producing the count honestly by running a tool. This file says when the count is required and what to do with it. diff --git a/docs/standards/concise-prose.md b/docs/standards/concise-prose.md index d53994b..318417a 100644 --- a/docs/standards/concise-prose.md +++ b/docs/standards/concise-prose.md @@ -6,14 +6,14 @@ is a reasoning-only judgment: word or sentence counts can flag a passage for review, but they cannot prove that a shorter version is equivalent. This rule owns wording, not whether content belongs or where it lives. -[`documentation-existence.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-existence.md) owns whether a +[`documentation-existence.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/documentation-existence.md) owns whether a page may exist at all; -[`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md) owns reductions to executable code; -[`progressive-disclosure.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/progressive-disclosure.md) owns information -layering; and [`reference-dont-duplicate.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/reference-dont-duplicate.md) and -[`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md) jointly own -whether a fact stays inline or is cited. [`naming.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/naming.md) owns -identifiers, and [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/legacy-and-migration-debt.md) +[`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/simpler-code.md) owns reductions to executable code; +[`progressive-disclosure.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/progressive-disclosure.md) owns information +layering; and [`reference-dont-duplicate.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/reference-dont-duplicate.md) and +[`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/documentation-and-citations.md) jointly own +whether a fact stays inline or is cited. [`naming.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/naming.md) owns +identifiers, and [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/legacy-and-migration-debt.md) owns whether historical narration belongs at all. Apply this convention to the prose that remains after those decisions. diff --git a/docs/standards/design-for-change.md b/docs/standards/design-for-change.md index a9b4127..8ad8df1 100644 --- a/docs/standards/design-for-change.md +++ b/docs/standards/design-for-change.md @@ -1,6 +1,6 @@ # Design for change -A design is judged by what a change of direction costs: how many files it touches and how far the breakage spreads. These rules let a reviewer check that cost on a diff. Each one applies where it makes sense: a rule that would add a mechanism with no present need yields to [simpler-code.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md#build-only-what-someone-acts-on). +A design is judged by what a change of direction costs: how many files it touches and how far the breakage spreads. These rules let a reviewer check that cost on a diff. Each one applies where it makes sense: a rule that would add a mechanism with no present need yields to [simpler-code.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/simpler-code.md#build-only-what-someone-acts-on). ## Intent @@ -19,14 +19,14 @@ The owner's direction, verbatim (2026-10-27): Each rule gives the check, why it holds, and its source. 1. **Hide each volatile decision in one module.** Check: a decision likely to change (a provider, store, wire or file format, transport, algorithm, or policy) is known to one module; callers depend on that module's contract, not on the decision. Why: the decision can then change by editing that one module. Source: [Parnas, "On the Criteria To Be Used in Decomposing Systems into Modules", CACM 15(12), 1972](https://doi.org/10.1145/361598.361623). -2. **A reversal stays local.** Check: for the decision the diff introduces, name the plausible reversal and count what it would edit. Swapping it should touch the owning module plus the composition root or configuration. A swap that would edit callers in other features means the decision leaked. Do not count the files a feature legitimately spans inside its own slice; that is the [shotgun-surgery carve-out](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#responsibility-and-cohesion). Why: "Gather together the things that change for the same reasons. Separate those things that change for different reasons." Source: [Martin, "The Single Responsibility Principle", 2014](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html); the Common Closure Principle in [Martin, "The Principles of OOD"](http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod). -3. **Slice by feature.** Check: a new feature lands in its own slice, and one slice does not import another slice's internals. The structure is owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#feature-and-vertical-slice-organization); when to share across slices by [code-organization.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/code-organization.md#share-at-the-second-consumer-never-copy). Why: "Minimize coupling between slices, and maximize coupling in a slice." Where it does not fit: Bogard warns the style assumes a team that recognizes code smells and refactors when a handler does too much. Source: [Bogard, "Vertical Slice Architecture", 2018](https://www.jimmybogard.com/vertical-slice-architecture/). -4. **Wire at the composition root; inject at volatile boundaries.** Check: business code receives a volatile collaborator through its constructor; it does not construct one or pull one from a service locator. Why: "the configuration of services is separated from their use." Dissent: Fowler himself gives Service Locator "a slight edge" inside one application and prefers injection for classes used by several; this catalog's default stays injection, per the [Hollywood Principle](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#let-the-framework-call-you-hollywood-principle). An interface for a stable in-process dependency is [needless indirection](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#abstraction-fit). Source: [Fowler, "Inversion of Control Containers and the Dependency Injection pattern", 2004](https://martinfowler.com/articles/injection.html). -5. **What varies by deploy is configuration.** Check: a value that differs between deploys (endpoints, credentials, per-environment settings) is read from configuration, not source; internal wiring that never varies stays in code. Why: config is "everything that is likely to vary between deploys." The YAGNI bound is owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#configurable-by-default-within-reason), and consumer-varying values by [shareable-artifact-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/shareable-artifact-design.md#externalize-what-a-consumer-may-decide). Source: [The Twelve-Factor App, III. Config](https://12factor.net/config). -6. **Add a variant by addition, not by edit.** Check: a new variant arrives as a new registration, strategy, or handler, not as another branch in shared dispatch. The bar and its YAGNI counterweight are owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#open-for-extension-closed-for-modification) and reviewed under [code-design.md](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#pattern-application). Source: the Open-Closed Principle in [Martin, "The Principles of OOD"](http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod). -7. **A pattern names the variation it serves.** Check: a diff that introduces one of the patterns below names the present need from the "Fits when" column; with none, it is [premature patternization](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#pattern-application). Why: each pattern adds classes and indirection that pay only when the variation exists. Source: [Gamma, Helm, Johnson, Vlissides, *Design Patterns*, Addison-Wesley, 1994](https://www.informit.com/store/design-patterns-elements-of-reusable-object-oriented-9780201633610), with the per-pattern pages below. -8. **DRY means one source per piece of knowledge, not per string.** Check: run the ordered tests in [reference-dont-duplicate.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/reference-dont-duplicate.md#consolidation-doctrine-ordered-tests) before consolidating; same text encoding different knowledge stays separate. An existing abstraction that is gaining a parameter or branch per caller is inlined back into its callers, not extended. Why: "duplication is far cheaper than the wrong abstraction." Source: [Metz, "The Wrong Abstraction", 2016](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction); [Dodds, "AHA Programming", 2020](https://kentcdodds.com/blog/aha-programming). -9. **Clean Code rules are heuristics.** Check: SOLID and *Clean Code* smells are reviewed under [code-design.md](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md); a deviation on a measured hot path carries its measurement. Why: the book's rules are contested: its examples ([qntm, 2020](https://qntm.org/clean)), its performance cost ([Muratori, "Clean Code, Horrible Performance", 2023](https://www.computerenhance.com/p/clean-code-horrible-performance)), and SOLID itself ([North, "CUPID: for joyful coding", 2022](https://dannorth.net/blog/cupid-for-joyful-coding/)). Source: [Martin, *Clean Code*, Prentice Hall, 2008](https://www.informit.com/store/clean-code-a-handbook-of-agile-software-craftsmanship-9780132350884). +2. **A reversal stays local.** Check: for the decision the diff introduces, name the plausible reversal and count what it would edit. Swapping it should touch the owning module plus the composition root or configuration. A swap that would edit callers in other features means the decision leaked. Do not count the files a feature legitimately spans inside its own slice; that is the [shotgun-surgery carve-out](https://github.com/melodic-software/standards/blob/main/standards/review/code-design.md#responsibility-and-cohesion). Why: "Gather together the things that change for the same reasons. Separate those things that change for different reasons." Source: [Martin, "The Single Responsibility Principle", 2014](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html); the Common Closure Principle in [Martin, "The Principles of OOD"](http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod). +3. **Slice by feature.** Check: a new feature lands in its own slice, and one slice does not import another slice's internals. The structure is owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/architecture-and-design.md#feature-and-vertical-slice-organization); when to share across slices by [code-organization.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/code-organization.md#share-at-the-second-consumer-never-copy). Why: "Minimize coupling between slices, and maximize coupling in a slice." Where it does not fit: Bogard warns the style assumes a team that recognizes code smells and refactors when a handler does too much. Source: [Bogard, "Vertical Slice Architecture", 2018](https://www.jimmybogard.com/vertical-slice-architecture/). +4. **Wire at the composition root; inject at volatile boundaries.** Check: business code receives a volatile collaborator through its constructor; it does not construct one or pull one from a service locator. Why: "the configuration of services is separated from their use." Dissent: Fowler himself gives Service Locator "a slight edge" inside one application and prefers injection for classes used by several; this catalog's default stays injection, per the [Hollywood Principle](https://github.com/melodic-software/standards/blob/main/standards/engineering/architecture-and-design.md#let-the-framework-call-you-hollywood-principle). An interface for a stable in-process dependency is [needless indirection](https://github.com/melodic-software/standards/blob/main/standards/review/code-design.md#abstraction-fit). Source: [Fowler, "Inversion of Control Containers and the Dependency Injection pattern", 2004](https://martinfowler.com/articles/injection.html). +5. **What varies by deploy is configuration.** Check: a value that differs between deploys (endpoints, credentials, per-environment settings) is read from configuration, not source; internal wiring that never varies stays in code. Why: config is "everything that is likely to vary between deploys." The YAGNI bound is owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/architecture-and-design.md#configurable-by-default-within-reason), and consumer-varying values by [shareable-artifact-design.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/shareable-artifact-design.md#externalize-what-a-consumer-may-decide). Source: [The Twelve-Factor App, III. Config](https://12factor.net/config). +6. **Add a variant by addition, not by edit.** Check: a new variant arrives as a new registration, strategy, or handler, not as another branch in shared dispatch. The bar and its YAGNI counterweight are owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/architecture-and-design.md#open-for-extension-closed-for-modification) and reviewed under [code-design.md](https://github.com/melodic-software/standards/blob/main/standards/review/code-design.md#pattern-application). Source: the Open-Closed Principle in [Martin, "The Principles of OOD"](http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod). +7. **A pattern names the variation it serves.** Check: a diff that introduces one of the patterns below names the present need from the "Fits when" column; with none, it is [premature patternization](https://github.com/melodic-software/standards/blob/main/standards/review/code-design.md#pattern-application). Why: each pattern adds classes and indirection that pay only when the variation exists. Source: [Gamma, Helm, Johnson, Vlissides, *Design Patterns*, Addison-Wesley, 1994](https://www.informit.com/store/design-patterns-elements-of-reusable-object-oriented-9780201633610), with the per-pattern pages below. +8. **DRY means one source per piece of knowledge, not per string.** Check: run the ordered tests in [reference-dont-duplicate.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/reference-dont-duplicate.md#consolidation-doctrine-ordered-tests) before consolidating; same text encoding different knowledge stays separate. An existing abstraction that is gaining a parameter or branch per caller is inlined back into its callers, not extended. Why: "duplication is far cheaper than the wrong abstraction." Source: [Metz, "The Wrong Abstraction", 2016](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction); [Dodds, "AHA Programming", 2020](https://kentcdodds.com/blog/aha-programming). +9. **Clean Code rules are heuristics.** Check: SOLID and *Clean Code* smells are reviewed under [code-design.md](https://github.com/melodic-software/standards/blob/main/standards/review/code-design.md); a deviation on a measured hot path carries its measurement. Why: the book's rules are contested: its examples ([qntm, 2020](https://qntm.org/clean)), its performance cost ([Muratori, "Clean Code, Horrible Performance", 2023](https://www.computerenhance.com/p/clean-code-horrible-performance)), and SOLID itself ([North, "CUPID: for joyful coding", 2022](https://dannorth.net/blog/cupid-for-joyful-coding/)). Source: [Martin, *Clean Code*, Prentice Hall, 2008](https://www.informit.com/store/clean-code-a-handbook-of-agile-software-craftsmanship-9780132350884). ## Pattern fit @@ -36,7 +36,7 @@ Each rule gives the check, why it holds, and its source. | [Factory Method / Abstract Factory](https://refactoring.guru/design-patterns/factory-method) | the caller cannot know the concrete type or its dependencies ahead of time, or a [family of related objects](https://refactoring.guru/design-patterns/abstract-factory) must be created together | one concrete type is ever built; constructor injection already supplies it | | [Builder](https://refactoring.guru/design-patterns/builder) | an object needs many optional parts (a telescoping constructor), or several representations from one construction process | the object has a few required fields; named arguments or an options record do it | | [Decorator](https://refactoring.guru/design-patterns/decorator) | a cross-cutting behavior (logging, retry, caching, authorization) wraps a contract without the wrapped type knowing | the stack's order matters but is not stated, or the framework's middleware or pipeline already offers the hook | -| [Mediator](https://refactoring.guru/design-patterns/mediator) | many components would otherwise reference each other directly and cannot change or be reused apart | each request has one handler and the mediator only adds a hop; the mediator grows into a god object; a handler dispatches another command, which [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#command-orchestration-and-consistency-boundaries) forbids | +| [Mediator](https://refactoring.guru/design-patterns/mediator) | many components would otherwise reference each other directly and cannot change or be reused apart | each request has one handler and the mediator only adds a hop; the mediator grows into a god object; a handler dispatches another command, which [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/standards/engineering/architecture-and-design.md#command-orchestration-and-consistency-boundaries) forbids | "Fits when" follows each pattern's applicability on the linked page. "Over-engineering when" follows its listed costs where that page states one; the rest of that column (Factory's constructor injection, Decorator's framework hook, Mediator's single-handler hop) is this catalog's judgment, bounded by the linked bars. Against an in-process mediator library in particular: "everything is done in-process" ([Comartin, "Why use MediatR? 3 reasons why and 1 reason not", 2020](https://codeopinion.com/why-use-mediatr-3-reasons-why-and-1-reason-not/)). diff --git a/docs/standards/deterministic-work-execution.md b/docs/standards/deterministic-work-execution.md index 0ed1d6f..23d6f2d 100644 --- a/docs/standards/deterministic-work-execution.md +++ b/docs/standards/deterministic-work-execution.md @@ -21,7 +21,7 @@ the result in text. ## Classify each substep before executing it -[`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md) owns the tier definitions. +[`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/enforceability-tiers.md) owns the tier definitions. Apply them to the current substep, not to the task as a whole: - For **deterministic** work, execute the operation and consume the returned @@ -69,18 +69,18 @@ while retaining quality assurance and an audit trail This convention governs one-off execution during the current task. It does not require committing a throwaway script, adding a dependency, or building a general utility. If the same deterministic finding recurs, route it through -[`enforceability-tiers.md#routing-a-recurring-finding`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md#routing-a-recurring-finding) +[`enforceability-tiers.md#routing-a-recurring-finding`](https://github.com/melodic-software/standards/blob/main/standards/engineering/enforceability-tiers.md#routing-a-recurring-finding) instead of accumulating session scripts. When executable logic becomes committed behavior, the simplicity, ownership, -and test obligations in [`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md), -[`code-organization.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/code-organization.md), and -[`../review/testing.md`](https://github.com/melodic-software/standards/blob/main/conventions/review/testing.md) apply. When the concern is a +and test obligations in [`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/simpler-code.md), +[`code-organization.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/code-organization.md), and +[`../review/testing.md`](https://github.com/melodic-software/standards/blob/main/standards/review/testing.md) apply. When the concern is a reusable artifact's fixed shape rather than an in-task computation, -[`deterministic-artifact-scaffolding.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-artifact-scaffolding.md) +[`deterministic-artifact-scaffolding.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/deterministic-artifact-scaffolding.md) owns it. Treat the output as proof only of the exact structural or computational claim it checked; the verification-honesty criteria in -[`../review/testing.md#verification-honesty`](https://github.com/melodic-software/standards/blob/main/conventions/review/testing.md#verification-honesty) +[`../review/testing.md#verification-honesty`](https://github.com/melodic-software/standards/blob/main/standards/review/testing.md#verification-honesty) own broader proof claims. ## Keep agent-run commands plain diff --git a/docs/standards/reference-dont-duplicate.md b/docs/standards/reference-dont-duplicate.md index 690890f..b5e808b 100644 --- a/docs/standards/reference-dont-duplicate.md +++ b/docs/standards/reference-dont-duplicate.md @@ -54,7 +54,7 @@ The same discipline holds outside prose. Deduplicate with the language's idiomat ## History lives in version control -Where and when something came from is a fact the version-control history already owns. An origin or history aside in code, comments, configuration, or docs (a "ported from" note, an "added on " comment) copies that fact into a second place nothing keeps current. Leave it out of explanatory prose, code, comments, and configuration; [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/legacy-and-migration-debt.md) covers the related case of prose that narrates a migration. +Where and when something came from is a fact the version-control history already owns. An origin or history aside in code, comments, configuration, or docs (a "ported from" note, an "added on " comment) copies that fact into a second place nothing keeps current. Leave it out of explanatory prose, code, comments, and configuration; [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/legacy-and-migration-debt.md) covers the related case of prose that narrates a migration. A record whose purpose is evidence keeps its dates and origins: a manifest's adoption, rollout, or canary notes, an architecture decision record, a component's admission evidence, a changelog. There the date is the evidence a decision rests on, not a copy of version-control history. diff --git a/docs/standards/source-authority-tiers.md b/docs/standards/source-authority-tiers.md index 4c01c49..e4c4638 100644 --- a/docs/standards/source-authority-tiers.md +++ b/docs/standards/source-authority-tiers.md @@ -5,12 +5,12 @@ behaves, what a default is, or whether an option exists is only as strong as the distance between the claim and the thing that decides it, and that distance is what a citation alone does not record. This convention ranks that distance and states how much corroboration a claim needs before it is treated as settled. -[`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md) owns *whether +[`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/documentation-and-citations.md) owns *whether and where* a citation appears once a claim is accepted; this owns *what the source is worth* and *how many are needed*. Neither answers the other's question. -This spans two of the tiers [`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md) +This spans two of the tiers [`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/enforceability-tiers.md) defines. A source floor is **deterministic** in nature: one primary plus two corroborators is an exact count. But the sources are named in a session, not in a tracked artifact, so no tool has anything to count. Deciding which rung a @@ -81,7 +81,7 @@ A source's rung is a property of when it was read, not of the source. A fetch from a previous session has decayed to **Recalled**: its content is now indistinguishable from memory, and the upstream may have moved. Re-retrieve before relying on it. This governs a source's standing as evidence; -[`documentation-and-citations.md#time-bound-external-claims-need-a-recheck-trigger`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md#time-bound-external-claims-need-a-recheck-trigger) +[`documentation-and-citations.md#time-bound-external-claims-need-a-recheck-trigger`](https://github.com/melodic-software/standards/blob/main/standards/engineering/documentation-and-citations.md#time-bound-external-claims-need-a-recheck-trigger) governs the separate obligation attached to a time-bound fact once it is written into durable content. @@ -109,23 +109,23 @@ so when a common pattern fails the check. ## Boundaries -- **vs [`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md)**: that +- **vs [`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/documentation-and-citations.md)**: that file owns whether a fact is cited rather than copied, where the link sits, and which footer it belongs to. This file owns how much the cited source is worth and how many are required. -- **vs [`reference-dont-duplicate.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/reference-dont-duplicate.md)**: that file +- **vs [`reference-dont-duplicate.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/reference-dont-duplicate.md)**: that file owns one source of truth per fact inside the repository. This file ranks sources outside it, where there is no single owner to defer to. -- **vs [`deterministic-work-execution.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-work-execution.md)**: +- **vs [`deterministic-work-execution.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/deterministic-work-execution.md)**: that file owns whether an execution was honest enough for its output to count as evidence at all. This file owns what that output is worth beside other sources once it does. A primary rung means a claim may rest on the source; it does not mean the source answered the question that was asked. -- **vs [`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md)**: that file +- **vs [`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/enforceability-tiers.md)**: that file classifies a *convention* by who can decide it. This file classifies a *source* by what it can establish. The two ladders are unrelated; only the vocabulary for this document's own classification is borrowed. -- **vs [`session-time-agent-output-trust.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/session-time-agent-output-trust.md)**: +- **vs [`session-time-agent-output-trust.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/session-time-agent-output-trust.md)**: that file governs an assertion an agent makes about its own work. An agent's assertion carries no rung of its own; it inherits the rung of the source it names, or **Recalled** when it names none.