From e65487b0538b8cc8e29611c0d297aeb0f710f00f Mon Sep 17 00:00:00 2001 From: Alan Szmyt Date: Tue, 25 Aug 2026 12:19:29 -0400 Subject: [PATCH] feat(projections): add decision-impact guidance hook Roadmap-Step: AET-Q07 ADR-Ref: ADR-001 ADR-Ref: ADR-002 ADR-Ref: egohygiene/hygiene#ADR-002 ADR-Ref: egohygiene/hygiene#ADR-005 Refs: #49 --- .github/copilot-instructions.md | 4 + ROADMAP.md | 33 ++++- .../organization/agents/architect.agent.md | 51 ++++++++ .../agents/arxiv-publisher.agent.md | 51 ++++++++ .../organization/agents/auditor.agent.md | 51 ++++++++ .../agents/bug-fix-teammate.agent.md | 51 ++++++++ .../agents/cleanup-specialist.agent.md | 51 ++++++++ .../agents/github-issue-creator.agent.md | 51 ++++++++ .../agents/implementation-planner.agent.md | 51 ++++++++ .../agents/specfile-creator.agent.md | 51 ++++++++ .../agents/test-specialist.agent.md | 51 ++++++++ .../.github/agents/architect.agent.md | 51 ++++++++ .../.github/agents/arxiv-publisher.agent.md | 51 ++++++++ .../.github/agents/auditor.agent.md | 51 ++++++++ .../.github/agents/bug-fix-teammate.agent.md | 51 ++++++++ .../agents/cleanup-specialist.agent.md | 51 ++++++++ .../agents/github-issue-creator.agent.md | 51 ++++++++ .../agents/implementation-planner.agent.md | 51 ++++++++ .../.github/agents/specfile-creator.agent.md | 51 ++++++++ .../.github/agents/test-specialist.agent.md | 51 ++++++++ library/organization/agents/AGENT-CONTRACT.md | 15 +++ .../projections/PROJECTION-CONTRACT.md | 25 ++++ .../projections/build-projections.py | 123 +++++++++++++++++- .../projections/provider-registry.v1.json | 2 +- .../templates/decision-impact.AGENTS.md | 49 +++++++ tests/test_provider_projections.py | 89 ++++++++++++- 26 files changed, 1247 insertions(+), 11 deletions(-) create mode 100644 library/organization/projections/templates/decision-impact.AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 015d7ce..1a92c91 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -41,6 +41,10 @@ Do **not** treat `.staging/`, `dist/`, or any other path as canonical source. 5. **Validate local Markdown links** before finalizing documentation changes. 6. **Consumer-local instructions override Aether defaults** for that consumer's context. +7. **Run the decision-impact checkpoint before code changes.** Apply the + canonical + [`decision-impact.AGENTS.md`](../library/organization/projections/templates/decision-impact.AGENTS.md) + module by reference; do not copy or weaken its Hygiene contract pins. --- diff --git a/ROADMAP.md b/ROADMAP.md index 53eef8e..97c79c5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -8,7 +8,7 @@ status: draft owners: - egohygiene created: 2026-08-08 -updated: 2026-08-24 +updated: 2026-08-25 governed_by: - architecture-roadmap depends_on: @@ -33,9 +33,9 @@ repository: egohygiene/aether visibility: public publication: central route: /roadmap/aether/ -updated: 2026-08-24 +updated: 2026-08-25 --> -## 2026-08-24 execution snapshot +## 2026-08-25 execution snapshot > This evidence-reconciled snapshot is the issue-generation and visual-roadmap handoff. The longer-horizon strategy below remains canonical context; generated HTML, JSON, progress, issue plans, and commit lists are projections. @@ -187,6 +187,33 @@ issues: [] - Aether already owns reusable AI artifacts; roadmap authoring support is assigned there by the visual-roadmap specification. + +#### AET-Q07 — Add the decision-impact instruction hook + +**State:** `ready` +**Depends on:** `AET-Q01` + +**Outcome:** Every generated agent projection receives one concise, +version-pinned checkpoint that distinguishes consequential decisions from +routine implementation and preserves human decision authority. + +**Exit criteria:** + +- [ ] The shared module pins, rather than copies, the proposed Hygiene ADR and Repository Intelligence contracts. +- [ ] Create, update, supersede, reference, and `ADR not required` flows cover consequential and routine examples. +- [ ] Provider projections and a generated repository `AGENTS.md` fixture contain exactly one managed hook. +- [ ] Deterministic tests reject malformed or duplicate managed blocks. + +**Current evidence:** + +- Issue #49 defines the decision-impact scope and acceptance criteria. +- The pinned Hygiene contracts remain proposed; this step must not claim their acceptance. + ### Roadmap-to-issue handoff - A step is complete only when its exit criteria and required evidence are satisfied; commit count never determines progress. diff --git a/dist/github/organization/agents/architect.agent.md b/dist/github/organization/agents/architect.agent.md index 74d1a6b..f209ce0 100644 --- a/dist/github/organization/agents/architect.agent.md +++ b/dist/github/organization/agents/architect.agent.md @@ -8,6 +8,7 @@ tools: - edit - web --- + ## Mission @@ -41,3 +42,53 @@ Inspect repository evidence before describing current architecture. Skip missing ## Completion Finish with the architecture artifact, resolved decisions, remaining open questions, implementation boundaries, and recommended next step toward Specfile Creator. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/arxiv-publisher.agent.md b/dist/github/organization/agents/arxiv-publisher.agent.md index dedb506..ede6b26 100644 --- a/dist/github/organization/agents/arxiv-publisher.agent.md +++ b/dist/github/organization/agents/arxiv-publisher.agent.md @@ -9,6 +9,7 @@ tools: - execute - web --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`prepare-arxiv-release`](.agents/skills/prepare-arxiv-release/SKILL.m ## Completion Report produced artifacts, exact validation performed, warnings, unresolved publisher constraints, and any manual submission steps that remain. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/auditor.agent.md b/dist/github/organization/agents/auditor.agent.md index abfecb2..d3a73cb 100644 --- a/dist/github/organization/agents/auditor.agent.md +++ b/dist/github/organization/agents/auditor.agent.md @@ -6,6 +6,7 @@ tools: - read - search --- + ## Mission @@ -37,3 +38,53 @@ Apply the [`audit-repository`](.agents/skills/audit-repository/SKILL.md) skill a ## Completion Finish only when the report exists, follows the specification, cites evidence, documents scope and uncertainty, and records all commands or checks relied upon. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/bug-fix-teammate.agent.md b/dist/github/organization/agents/bug-fix-teammate.agent.md index 2a6cdcc..846a40f 100644 --- a/dist/github/organization/agents/bug-fix-teammate.agent.md +++ b/dist/github/organization/agents/bug-fix-teammate.agent.md @@ -8,6 +8,7 @@ tools: - edit - execute --- + ## Mission @@ -39,3 +40,53 @@ Apply the [`bug-fixing`](.agents/skills/bug-fixing/SKILL.md) skill. Follow repos ## Completion Report the root cause, fix, regression protection, validation results, residual risk, and any checks that could not run. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/cleanup-specialist.agent.md b/dist/github/organization/agents/cleanup-specialist.agent.md index c671167..55f34dc 100644 --- a/dist/github/organization/agents/cleanup-specialist.agent.md +++ b/dist/github/organization/agents/cleanup-specialist.agent.md @@ -8,6 +8,7 @@ tools: - edit - execute --- + ## Mission @@ -37,3 +38,53 @@ Apply the [`repository-cleanup`](.agents/skills/repository-cleanup/SKILL.md) ski ## Completion Summarize what was cleaned, why behavior is preserved, validation performed, and any candidates intentionally left untouched. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/github-issue-creator.agent.md b/dist/github/organization/agents/github-issue-creator.agent.md index 3acdd02..76e56b3 100644 --- a/dist/github/organization/agents/github-issue-creator.agent.md +++ b/dist/github/organization/agents/github-issue-creator.agent.md @@ -7,6 +7,7 @@ tools: - search - web --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`github-issue-authoring`](.agents/skills/github-issue-authoring/SKILL ## Completion Return exactly the output format selected by the governing specification or explicit user request, with no cleanup required before use. Recommended next step: implementation by Copilot or the default implementer. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/implementation-planner.agent.md b/dist/github/organization/agents/implementation-planner.agent.md index 6154994..b407b8b 100644 --- a/dist/github/organization/agents/implementation-planner.agent.md +++ b/dist/github/organization/agents/implementation-planner.agent.md @@ -8,6 +8,7 @@ tools: - edit - web --- + ## Mission @@ -39,3 +40,53 @@ Apply the [`implementation-planning`](.agents/skills/implementation-planning/SKI ## Completion Deliver the plan, dependency graph or ordering, validation strategy, risks, assumptions, and open questions in the requested artifact or Markdown response. Recommended next step: GitHub Issue Creator. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/specfile-creator.agent.md b/dist/github/organization/agents/specfile-creator.agent.md index ce3b426..f314e52 100644 --- a/dist/github/organization/agents/specfile-creator.agent.md +++ b/dist/github/organization/agents/specfile-creator.agent.md @@ -8,6 +8,7 @@ tools: - edit - web --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`create-specification-file`](.agents/skills/create-specification-file ## Completion Write the requested kebab-case `.spec.md` file or return its complete content, and identify unresolved decisions that block implementation. Recommended next step: Implementation Planner. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/organization/agents/test-specialist.agent.md b/dist/github/organization/agents/test-specialist.agent.md index ee15fbe..0a72184 100644 --- a/dist/github/organization/agents/test-specialist.agent.md +++ b/dist/github/organization/agents/test-specialist.agent.md @@ -8,6 +8,7 @@ tools: - edit - execute --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`test-engineering`](.agents/skills/test-engineering/SKILL.md) skill. ## Completion Report the behavior covered, test layers used, commands and results, remaining gaps, and any production seam that still blocks reliable testing. Recommended next step: Auditor. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/architect.agent.md b/dist/github/repository/.github/agents/architect.agent.md index 128033f..1ad3efc 100644 --- a/dist/github/repository/.github/agents/architect.agent.md +++ b/dist/github/repository/.github/agents/architect.agent.md @@ -8,6 +8,7 @@ tools: - edit - web --- + ## Mission @@ -41,3 +42,53 @@ Inspect repository evidence before describing current architecture. Skip missing ## Completion Finish with the architecture artifact, resolved decisions, remaining open questions, implementation boundaries, and recommended next step toward Specfile Creator. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/arxiv-publisher.agent.md b/dist/github/repository/.github/agents/arxiv-publisher.agent.md index 7ad979d..2361d74 100644 --- a/dist/github/repository/.github/agents/arxiv-publisher.agent.md +++ b/dist/github/repository/.github/agents/arxiv-publisher.agent.md @@ -9,6 +9,7 @@ tools: - execute - web --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`prepare-arxiv-release`](.agents/skills/prepare-arxiv-release/SKILL.m ## Completion Report produced artifacts, exact validation performed, warnings, unresolved publisher constraints, and any manual submission steps that remain. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/auditor.agent.md b/dist/github/repository/.github/agents/auditor.agent.md index dbc49a7..de37f04 100644 --- a/dist/github/repository/.github/agents/auditor.agent.md +++ b/dist/github/repository/.github/agents/auditor.agent.md @@ -6,6 +6,7 @@ tools: - read - search --- + ## Mission @@ -37,3 +38,53 @@ Apply the [`audit-repository`](.agents/skills/audit-repository/SKILL.md) skill a ## Completion Finish only when the report exists, follows the specification, cites evidence, documents scope and uncertainty, and records all commands or checks relied upon. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/bug-fix-teammate.agent.md b/dist/github/repository/.github/agents/bug-fix-teammate.agent.md index 2a6cdcc..846a40f 100644 --- a/dist/github/repository/.github/agents/bug-fix-teammate.agent.md +++ b/dist/github/repository/.github/agents/bug-fix-teammate.agent.md @@ -8,6 +8,7 @@ tools: - edit - execute --- + ## Mission @@ -39,3 +40,53 @@ Apply the [`bug-fixing`](.agents/skills/bug-fixing/SKILL.md) skill. Follow repos ## Completion Report the root cause, fix, regression protection, validation results, residual risk, and any checks that could not run. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/cleanup-specialist.agent.md b/dist/github/repository/.github/agents/cleanup-specialist.agent.md index c671167..55f34dc 100644 --- a/dist/github/repository/.github/agents/cleanup-specialist.agent.md +++ b/dist/github/repository/.github/agents/cleanup-specialist.agent.md @@ -8,6 +8,7 @@ tools: - edit - execute --- + ## Mission @@ -37,3 +38,53 @@ Apply the [`repository-cleanup`](.agents/skills/repository-cleanup/SKILL.md) ski ## Completion Summarize what was cleaned, why behavior is preserved, validation performed, and any candidates intentionally left untouched. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/github-issue-creator.agent.md b/dist/github/repository/.github/agents/github-issue-creator.agent.md index 98466fc..9c9eef8 100644 --- a/dist/github/repository/.github/agents/github-issue-creator.agent.md +++ b/dist/github/repository/.github/agents/github-issue-creator.agent.md @@ -7,6 +7,7 @@ tools: - search - web --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`github-issue-authoring`](.agents/skills/github-issue-authoring/SKILL ## Completion Return exactly the output format selected by the governing specification or explicit user request, with no cleanup required before use. Recommended next step: implementation by Copilot or the default implementer. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/implementation-planner.agent.md b/dist/github/repository/.github/agents/implementation-planner.agent.md index 6154994..b407b8b 100644 --- a/dist/github/repository/.github/agents/implementation-planner.agent.md +++ b/dist/github/repository/.github/agents/implementation-planner.agent.md @@ -8,6 +8,7 @@ tools: - edit - web --- + ## Mission @@ -39,3 +40,53 @@ Apply the [`implementation-planning`](.agents/skills/implementation-planning/SKI ## Completion Deliver the plan, dependency graph or ordering, validation strategy, risks, assumptions, and open questions in the requested artifact or Markdown response. Recommended next step: GitHub Issue Creator. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/specfile-creator.agent.md b/dist/github/repository/.github/agents/specfile-creator.agent.md index 440400c..68af735 100644 --- a/dist/github/repository/.github/agents/specfile-creator.agent.md +++ b/dist/github/repository/.github/agents/specfile-creator.agent.md @@ -8,6 +8,7 @@ tools: - edit - web --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`create-specification-file`](.agents/skills/create-specification-file ## Completion Write the requested kebab-case `.spec.md` file or return its complete content, and identify unresolved decisions that block implementation. Recommended next step: Implementation Planner. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/dist/github/repository/.github/agents/test-specialist.agent.md b/dist/github/repository/.github/agents/test-specialist.agent.md index ee15fbe..0a72184 100644 --- a/dist/github/repository/.github/agents/test-specialist.agent.md +++ b/dist/github/repository/.github/agents/test-specialist.agent.md @@ -8,6 +8,7 @@ tools: - edit - execute --- + ## Mission @@ -38,3 +39,53 @@ Apply the [`test-engineering`](.agents/skills/test-engineering/SKILL.md) skill. ## Completion Report the behavior covered, test layers used, commands and results, remaining gaps, and any production seam that still blocks reliable testing. Recommended next step: Auditor. + + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/library/organization/agents/AGENT-CONTRACT.md b/library/organization/agents/AGENT-CONTRACT.md index acd74aa..32bffa3 100644 --- a/library/organization/agents/AGENT-CONTRACT.md +++ b/library/organization/agents/AGENT-CONTRACT.md @@ -98,6 +98,21 @@ Projection is performed by `build-projections.py`. For each source `AGENT.md`: 4. Internal spec links (``../specs//.spec.md``) are rewritten to ``.github/specs//.spec.md`` for repository projections and ``specs//.spec.md`` for organization projections. +5. The shared decision-impact instruction at + [`../projections/templates/decision-impact.AGENTS.md`](../projections/templates/decision-impact.AGENTS.md) + is inserted exactly once in every generated agent projection. Canonical + role bodies do not copy this managed module. + +### Decision-impact inheritance + +The decision-impact module is the concise, always-on checkpoint for code-change +tasks. It pins the versioned Hygiene ADR and Repository Intelligence contracts, +preserves their proposal status, and defines create, update, supersede, +reference, and `ADR not required` flows without redefining organization policy. + +Provider builders must replace the marked block in place when it already +exists and reject malformed or duplicate marker sets. This keeps generated +agent guidance and repository-root `AGENTS.md` integrations non-duplicative. --- diff --git a/library/organization/projections/PROJECTION-CONTRACT.md b/library/organization/projections/PROJECTION-CONTRACT.md index 662a5fe..07f76a3 100644 --- a/library/organization/projections/PROJECTION-CONTRACT.md +++ b/library/organization/projections/PROJECTION-CONTRACT.md @@ -1,6 +1,7 @@ # Aether provider projection contract Status: `aether.projection-interface/v1` +Interface version: `1.1.0` Owner: `egohygiene/aether` Registry: [`provider-registry.v1.json`](provider-registry.v1.json) @@ -42,6 +43,16 @@ The source owns: Provider adapters may transform syntax and paths, but they do not rewrite canonical intent. +Every projected agent also receives the shared, canonical decision-impact +module from +[`templates/decision-impact.AGENTS.md`](templates/decision-impact.AGENTS.md). +The module is injected through managed markers instead of being copied into +each role source. It currently pins the proposed Hygiene ADR policy at version +`1.0.0` and Repository Intelligence contract at `1.0.0-alpha.1`, both at +immutable Hygiene revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +Its draft projection does not promote either upstream proposal or grant +implementation authority. + ## Projection states Every provider entry declares one of these states: @@ -61,6 +72,8 @@ Every generated Markdown agent includes an `aether-projection` HTML comment imme - provider adapter; - canonical source path; - normalized SHA-256 source digest; +- the decision-impact module version, upstream pins, source, and normalized + digest; - generator path. JSON/manual outputs carry equivalent provenance fields, and `dist/projections/manifest.v1.json` records hashes for every generated output. @@ -131,6 +144,18 @@ dist/zencoder/manual-import/agents.json As of the registry's `last_verified` date, Aether has not verified a repository-native custom-agent file format for Zencoder. The generated JSON is therefore deliberately labeled `manual-import` and is input to the provider UI/catalog rather than a file that claims automatic discovery. +### Repository-instruction fixture + +```text +dist/fixtures/repository-instructions/AGENTS.md +``` + +This generated file is an integration fixture for repository-root guidance, +not a consumer-owned instruction file to overwrite wholesale. Holon or another +authorized installer must preserve repository commands, boundaries, and nested +instruction precedence while reconciling the marked module. Reapplying the +module replaces the existing marked block and never adds a second copy. + ## GitHub MCP template Aether publishes a secret-free local Docker template at: diff --git a/library/organization/projections/build-projections.py b/library/organization/projections/build-projections.py index a6d2899..6ff71e9 100644 --- a/library/organization/projections/build-projections.py +++ b/library/organization/projections/build-projections.py @@ -23,11 +23,23 @@ AGENTS_DIR = REPO_ROOT / "library" / "organization" / "agents" REGISTRY_PATH = REPO_ROOT / "library" / "organization" / "projections" / "provider-registry.v1.json" SCHEMA_PATH = REPO_ROOT / "catalog" / "schemas" / "aether.projection-interface.v1.schema.json" +DECISION_IMPACT_PATH = ( + REPO_ROOT + / "library" + / "organization" + / "projections" + / "templates" + / "decision-impact.AGENTS.md" +) GENERATOR_ID = "library/organization/projections/build-projections.py" INTERFACE_SCHEMA = "aether.projection-interface/v1" +INTERFACE_VERSION = "1.1.0" MANIFEST_SCHEMA = "aether.projection-manifest/v1" MANUAL_IMPORT_SCHEMA = "aether.manual-agent-import/v1" FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL) +INSTRUCTION_METADATA_RE = re.compile(r"") +DECISION_IMPACT_START = "" +DECISION_IMPACT_END = "" _SKILL_LINK_RE = re.compile(r"(?:\.\./){2}skills/[^/]+/([^/]+)/SKILL\.md") _SPEC_LINK_RE = re.compile(r"(?:\.\./){2}specs/([^\s\)\"']+)") @@ -79,6 +91,80 @@ def _repo_relative(path: Path) -> str: return path.as_posix() +def _load_decision_impact() -> tuple[dict[str, Any], str]: + """Load and validate the canonical decision-impact instruction module.""" + if not DECISION_IMPACT_PATH.is_file(): + raise ValueError( + f"decision-impact instruction is missing: {_repo_relative(DECISION_IMPACT_PATH)}" + ) + text = _normalized_text(DECISION_IMPACT_PATH).strip() + if text.count(DECISION_IMPACT_START) != 1 or text.count(DECISION_IMPACT_END) != 1: + raise ValueError("decision-impact instruction must contain exactly one managed marker pair") + if text.index(DECISION_IMPACT_START) > text.index(DECISION_IMPACT_END): + raise ValueError("decision-impact instruction markers are out of order") + + match = INSTRUCTION_METADATA_RE.search(text) + if match is None: + raise ValueError("decision-impact instruction is missing aether-instruction metadata") + try: + metadata = json.loads(match.group(1)) + except json.JSONDecodeError as exc: + raise ValueError(f"decision-impact instruction metadata is invalid JSON: {exc}") from exc + if not isinstance(metadata, dict): + raise ValueError("decision-impact instruction metadata must be an object") + for field in ("id", "version", "status", "inherits"): + if field not in metadata: + raise ValueError(f"decision-impact instruction metadata is missing {field}") + if metadata["id"] != "decision-impact": + raise ValueError("decision-impact instruction metadata has an unexpected id") + if not isinstance(metadata["inherits"], list) or not metadata["inherits"]: + raise ValueError("decision-impact instruction must inherit at least one pinned contract") + for inherited in metadata["inherits"]: + if not isinstance(inherited, dict) or not { + "contract", + "revision", + "source_url", + "status", + }.issubset(inherited): + raise ValueError( + "decision-impact inherited contracts require contract, revision, source_url, and status" + ) + return metadata, text + + +def _decision_impact_provenance() -> dict[str, Any]: + """Return provenance for the shared decision-impact module.""" + metadata, _module = _load_decision_impact() + source_text = _normalized_text(DECISION_IMPACT_PATH) + return { + "id": metadata["id"], + "version": metadata["version"], + "status": metadata["status"], + "source": _repo_relative(DECISION_IMPACT_PATH), + "source_digest": { + "algorithm": "sha256-utf8-lf", + "value": _sha256_text(source_text), + }, + "inherits": metadata["inherits"], + } + + +def _apply_decision_impact(body: str) -> str: + """Insert or refresh exactly one managed decision-impact block.""" + _metadata, module = _load_decision_impact() + start_count = body.count(DECISION_IMPACT_START) + end_count = body.count(DECISION_IMPACT_END) + if start_count != end_count or start_count > 1: + raise ValueError("projected guidance contains an invalid decision-impact marker set") + if start_count == 0: + return f"{body.rstrip()}\n\n{module}\n" + + start = body.index(DECISION_IMPACT_START) + end = body.index(DECISION_IMPACT_END, start) + len(DECISION_IMPACT_END) + parts = [body[:start].rstrip(), module, body[end:].lstrip()] + return "\n\n".join(part for part in parts if part).rstrip() + "\n" + + def load_registry() -> dict[str, Any]: """Load and validate the versioned provider registry.""" registry = json.loads(REGISTRY_PATH.read_text(encoding="utf-8")) @@ -91,6 +177,10 @@ def load_registry() -> dict[str, Any]: for error in errors ) raise ValueError(f"provider registry does not satisfy its schema: {details}") + if registry["interface_version"] != INTERFACE_VERSION: + raise ValueError( + "provider registry interface_version does not match the projection builder" + ) return registry @@ -136,6 +226,7 @@ def _projection_provenance(provider: str, source: Path, source_text: str) -> dic """Return deterministic provenance shared by every projected agent.""" return { "interface": INTERFACE_SCHEMA, + "interface_version": INTERFACE_VERSION, "provider": provider, "source": _repo_relative(source), "source_digest": { @@ -143,6 +234,7 @@ def _projection_provenance(provider: str, source: Path, source_text: str) -> dic "value": _sha256_text(source_text), }, "generator": GENERATOR_ID, + "instruction_modules": [_decision_impact_provenance()], } @@ -163,6 +255,25 @@ def _render_markdown(frontmatter: dict[str, Any], provenance: str, body: str) -> return f"---\n{yaml_text}\n---\n{provenance}\n\n{body.rstrip()}\n".encode("utf-8") +def _agents_guidance_fixture() -> bytes: + """Render an install-review fixture for repository-root AGENTS.md guidance.""" + _metadata, module = _load_decision_impact() + provenance = { + "interface": INTERFACE_SCHEMA, + "interface_version": INTERFACE_VERSION, + "kind": "repository-agents-guidance-fixture", + "instruction_modules": [_decision_impact_provenance()], + "generator": GENERATOR_ID, + } + return ( + "# AGENTS.md\n\n" + f"\n\n" + "> Generated integration fixture. Preserve consumer-owned repository commands, " + "boundaries, and nested instruction precedence when installing this managed module.\n\n" + f"{module}\n" + ).encode("utf-8") + + def _mapped_tools(canonical_tools: list[str], mapping: dict[str, tuple[str, ...]]) -> list[str]: """Map canonical Aether tool intent into a provider allowlist.""" result: list[str] = [] @@ -277,19 +388,20 @@ def _build_files(registry: dict[str, Any]) -> dict[str, bytes]: for agent_id, source in find_agents(): source_text = _normalized_text(source) frontmatter, body = _parse_agent(agent_id, source) + projected_body = _apply_decision_impact(body) source_provenance = _projection_provenance("canonical", source, source_text) source_records[agent_id] = source_provenance files[f"github/repository/.github/agents/{agent_id}.agent.md"] = _github_projection( frontmatter, - body, + projected_body, source, source_text, organization=False, ) files[f"github/organization/agents/{agent_id}.agent.md"] = _github_projection( frontmatter, - body, + projected_body, source, source_text, organization=True, @@ -297,13 +409,13 @@ def _build_files(registry: dict[str, Any]) -> dict[str, bytes]: files[f"claude/repository/.claude/agents/{agent_id}.md"] = _claude_projection( agent_id, frontmatter, - body, + projected_body, source, source_text, ) files[f"opencode/repository/.opencode/agents/{agent_id}.md"] = _opencode_projection( frontmatter, - body, + projected_body, source, source_text, ) @@ -314,11 +426,12 @@ def _build_files(registry: dict[str, Any]) -> dict[str, bytes]: "name": frontmatter["name"], "description": frontmatter["description"], "canonical_tools": list(frontmatter["tools"]), - "instructions": _rewrite_links(body, ".github/specs").rstrip(), + "instructions": _rewrite_links(projected_body, ".github/specs").rstrip(), "provenance": source_provenance, } ) + files["fixtures/repository-instructions/AGENTS.md"] = _agents_guidance_fixture() files["zencoder/manual-import/agents.json"] = _manual_zencoder_packet(zencoder_agents) for template in registry["mcp_templates"]: diff --git a/library/organization/projections/provider-registry.v1.json b/library/organization/projections/provider-registry.v1.json index 30fcba2..b24a371 100644 --- a/library/organization/projections/provider-registry.v1.json +++ b/library/organization/projections/provider-registry.v1.json @@ -1,7 +1,7 @@ { "$schema": "../../../catalog/schemas/aether.projection-interface.v1.schema.json", "schema_version": "aether.projection-interface/v1", - "interface_version": "1.0.0", + "interface_version": "1.1.0", "last_verified": "2026-08-23", "canonical_source": { "owner": "egohygiene/aether", diff --git a/library/organization/projections/templates/decision-impact.AGENTS.md b/library/organization/projections/templates/decision-impact.AGENTS.md new file mode 100644 index 0000000..c7524b7 --- /dev/null +++ b/library/organization/projections/templates/decision-impact.AGENTS.md @@ -0,0 +1,49 @@ + + +## Decision-impact checkpoint + +Before changing code, inspect the applicable repository instructions, roadmap, +local decisions, and relevant organization decisions. Classify the work as +`create`, `update`, `supersede`, `reference`, or `ADR not required`. Do not +silently make a consequential or ambiguous choice: surface it and request human +review. Automated agents never mark an ADR accepted. + +- **Create** a proposed ADR when no existing record governs a consequential + choice. +- **Update** an existing proposal, or add evidence/outcomes/corrections that do + not rewrite an accepted decision's historical meaning. +- **Supersede** when an accepted choice must change: propose a replacement, + preserve the old record, and link both directions after human approval. +- **Reference** the governing ADR when work implements an existing decision; + do not create a duplicate. +- Use **`ADR not required`** with one short reason for routine, local, reversible + work that follows accepted design. + +| Area | ADR required | ADR not required | +| --- | --- | --- | +| Dependencies | Adopt/remove a durable framework or make a compatibility-changing major upgrade | Apply a compatible patch within accepted dependency policy | +| Public contracts | Change API, CLI, schema, compatibility, or migration semantics | Clarify documentation or tests without changing the contract | +| Security | Change a trust boundary, authorization model, encryption, or secret handling | Implement or test an already accepted control | +| Data models | Change durable identity, persistence, or migration strategy | Refactor a transient local representation | +| Deployment | Change topology, hosting platform, release channel, or dependency direction | Tune retries or resources within the accepted topology | +| Reversible details | A trigger above still makes the choice consequential | Change a local algorithm, refactor, formatting, or test organization | + +When stable identifiers exist, connect the work with Git trailers or equivalent +pull-request fields: + +```text +Roadmap-Step: AET-Q07 +ADR-Ref: egohygiene/hygiene#ADR-002 +``` + +Use a local stable ID or a fully qualified `/#`; always +qualify cross-repository references. Do not invent missing IDs or evidence. + +This draft module inherits the proposed +[Hygiene ADR policy v1.0.0](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/decisions/POLICY.md) +and +[Repository Intelligence v1.0.0-alpha.1](https://github.com/egohygiene/hygiene/blob/5e0602265b6ac5e5165b89f418e55a3fd12f8a64/docs/ecosystem/REPOSITORY_INTELLIGENCE.md) +at immutable revision `5e0602265b6ac5e5165b89f418e55a3fd12f8a64`. +It grants no acceptance, implementation, or organization-wide authority while +those upstream contracts remain proposed. + diff --git a/tests/test_provider_projections.py b/tests/test_provider_projections.py index dea55b1..60953de 100644 --- a/tests/test_provider_projections.py +++ b/tests/test_provider_projections.py @@ -42,7 +42,7 @@ def test_registry_is_versioned_and_resolves_provider_states(self) -> None: providers = {provider["id"]: provider for provider in registry["providers"]} self.assertEqual(registry["schema_version"], "aether.projection-interface/v1") - self.assertEqual(registry["interface_version"], "1.0.0") + self.assertEqual(registry["interface_version"], "1.1.0") self.assertEqual( set(providers), {"github-copilot", "vscode-copilot", "claude-code", "opencode", "zencoder"}, @@ -62,7 +62,7 @@ def test_build_emits_native_manual_and_mcp_outputs(self) -> None: agents = projections.find_agents() self.assertGreaterEqual(len(agents), 1) - expected_count = (len(agents) * 4) + 3 + expected_count = (len(agents) * 4) + 4 generated_files = sorted(path for path in output.rglob("*") if path.is_file()) self.assertEqual(len(generated_files), expected_count) @@ -73,9 +73,93 @@ def test_build_emits_native_manual_and_mcp_outputs(self) -> None: self.assertTrue((output / "opencode/repository/.opencode/agents" / f"{agent_id}.md").is_file()) self.assertTrue((output / "zencoder/manual-import/agents.json").is_file()) + self.assertTrue((output / "fixtures/repository-instructions/AGENTS.md").is_file()) self.assertTrue((output / "mcp/github/.mcp.json").is_file()) self.assertTrue((output / "projections/manifest.v1.json").is_file()) + def test_decision_impact_module_pins_upstream_contracts_without_promoting_them(self) -> None: + metadata, text = projections._load_decision_impact() + inherited = {contract["contract"]: contract for contract in metadata["inherits"]} + + self.assertEqual(metadata["id"], "decision-impact") + self.assertEqual(metadata["version"], "0.1.0") + self.assertEqual(metadata["status"], "draft") + self.assertEqual( + inherited["egohygiene.architecture-decision/v1"]["policy_version"], + "1.0.0", + ) + self.assertEqual( + inherited["egohygiene.repository-intelligence/v1"]["contract_version"], + "1.0.0-alpha.1", + ) + self.assertTrue(all(contract["status"] == "proposed" for contract in inherited.values())) + self.assertTrue(all(len(contract["revision"]) == 40 for contract in inherited.values())) + self.assertTrue(all("/blob/" in contract["source_url"] for contract in inherited.values())) + self.assertIn("Automated agents never mark an ADR accepted", text) + provenance = projections._decision_impact_provenance() + self.assertEqual( + provenance["source_digest"]["value"], + projections._sha256_text(projections._normalized_text(projections.DECISION_IMPACT_PATH)), + ) + + def test_decision_impact_insertion_is_idempotent_and_rejects_duplicates(self) -> None: + body = "## Mission\n\nDo bounded work.\n" + once = projections._apply_decision_impact(body) + twice = projections._apply_decision_impact(once) + + self.assertEqual(once, twice) + self.assertEqual(once.count(projections.DECISION_IMPACT_START), 1) + self.assertEqual(once.count(projections.DECISION_IMPACT_END), 1) + + with self.assertRaisesRegex(ValueError, "invalid decision-impact marker set"): + projections._apply_decision_impact(once + once) + + def test_every_projection_contains_one_decision_impact_checkpoint(self) -> None: + with tempfile.TemporaryDirectory() as temporary_directory: + output = Path(temporary_directory) / "dist" + projections.build(output_directory=output) + + markdown_outputs = [ + path + for path in output.rglob("*.md") + if "/agents/" in path.as_posix() + or path == output / "fixtures/repository-instructions/AGENTS.md" + ] + self.assertGreaterEqual(len(markdown_outputs), 1) + for path in markdown_outputs: + text = path.read_text(encoding="utf-8") + self.assertEqual(text.count(projections.DECISION_IMPACT_START), 1, path) + self.assertEqual(text.count(projections.DECISION_IMPACT_END), 1, path) + + packet = json.loads((output / "zencoder/manual-import/agents.json").read_text(encoding="utf-8")) + for agent in packet["agents"]: + instructions = agent["instructions"] + self.assertEqual(instructions.count(projections.DECISION_IMPACT_START), 1) + self.assertEqual(instructions.count(projections.DECISION_IMPACT_END), 1) + + def test_generated_agents_fixture_covers_required_flows_and_examples(self) -> None: + with tempfile.TemporaryDirectory() as temporary_directory: + output = Path(temporary_directory) / "dist" + projections.build(output_directory=output) + fixture = (output / "fixtures/repository-instructions/AGENTS.md").read_text( + encoding="utf-8" + ) + + for flow in ("Create", "Update", "Supersede", "Reference", "ADR not required"): + self.assertIn(flow, fixture) + for area in ( + "Dependencies", + "Public contracts", + "Security", + "Data models", + "Deployment", + "Reversible details", + ): + self.assertIn(area, fixture) + self.assertIn("Roadmap-Step: AET-Q07", fixture) + self.assertIn("ADR-Ref: egohygiene/hygiene#ADR-002", fixture) + self.assertIn("qualify cross-repository references", fixture) + def test_markdown_outputs_include_source_provenance(self) -> None: with tempfile.TemporaryDirectory() as temporary_directory: output = Path(temporary_directory) / "dist" @@ -92,6 +176,7 @@ def test_markdown_outputs_include_source_provenance(self) -> None: ): self.assertIn("