diff --git a/CHANGELOG.md b/CHANGELOG.md index f487ffe..61fd18b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ ## [Unreleased] +## [v1.10.0] + +- Define Architecture, Program governance, Evidence classification, and Governance decision types with a creation test that leaves ordinary maintenance in its owning guide. +- Add Governance Decision 0005 for the shared directory and identifier sequence, policy boundary, common record shape, supersession rules, and history-preserving migration. +- Expand the decision index with examples, counterexamples, maintainer workflow, research rationale, and the boundary between historical rationale and current operational truth. +- Derive canonical types and index coverage from the maintained guide, then validate discovered record filenames, identifiers, titles, common sections, exact index membership, duplicate numbers, and stale links without hard-coding historical records. +- Preserve records 0001 through 0004, every published filename and link, the runtime skill, activation and output behavior, safety contract, fixtures, and package formats. +- Record the primary research sources and the limit that no unnamed private portfolio inventory or unrelated repository was inspected for this implementation. + ## [v1.9.0] - Replace the generic founding-case landing copy with a concrete account of release knowledge reused from three repositories across two organizations. diff --git a/README.md b/README.md index d489f10..588a1e2 100644 --- a/README.md +++ b/README.md @@ -135,7 +135,7 @@ Each release provides a standalone Agent Skill ZIP, a Codex plugin ZIP, a Claude Start with [Contributing](CONTRIBUTING.md) for the repository workflow and definition of done. -Use the [Roadmap](docs/ROADMAP.md) for program direction, [Architecture](docs/ARCHITECTURE.md) for durable design, [Governance](docs/GOVERNANCE.md) for decision authority, [Testing](docs/TESTING.md) for evidence, and [Releasing](docs/RELEASING.md) for delivery. Read [Maintenance](docs/MAINTENANCE.md) for health review and [Support](SUPPORT.md) for help routes. +Use the [Roadmap](docs/ROADMAP.md) for program direction, [Architecture](docs/ARCHITECTURE.md) for durable design, [Governance](docs/GOVERNANCE.md) for decision authority, [Decision Records](docs/decisions/README.md) for durable rationale, [Testing](docs/TESTING.md) for evidence, and [Releasing](docs/RELEASING.md) for delivery. Read [Maintenance](docs/MAINTENANCE.md) for health review and [Support](SUPPORT.md) for help routes. ### Development @@ -150,6 +150,6 @@ Generated ZIP files are written to `dist/assets/`. ## Status and License -Current version: `1.9.0`. +Current version: `1.10.0`. The repository is maintained by TechSpokes and licensed under [MIT](LICENSE). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9fbeedb..7e6a758 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -161,4 +161,6 @@ Refresh `agent-capability-adapters.md` when hosts change skill paths, connector Use the [threat model](THREAT-MODEL.md), [governance contract](GOVERNANCE.md), [maintenance health](MAINTENANCE.md), [decision classification](decisions/README.md), and [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md) when a change affects privileged tools, public output, feedback, portal handoff, recommendation independence, contribution quality, roadmap claims, or release identity. +Decision records use one shared directory and identifier sequence with explicit Architecture, Program governance, Evidence classification, and Governance types. Current runtime, policy, evidence, and procedure documents remain the operational sources of truth; [Governance Decision 0005](decisions/0005-use-one-typed-decision-registry.md) records the taxonomy, history-preserving migration, and validation boundary. + Keep project scripts platform-neutral where Node.js provides the needed capability. Validation, checksum generation, and the dependency-free stored ZIP implementation use Node.js standard library APIs and do not depend on host archive commands or shell-specific path behavior. diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index 4b5dccd..125edaf 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -8,7 +8,7 @@ Protect the skill's portability, safety, evidence discipline, teaching value, fr The repository maintainers may accept reversible implementation and documentation decisions that preserve the published contracts. Require an accountable human review for activation or safety contract changes, public release, security acceptance, organization access, paid conflicts, major interoperability commitments, and decision supersession. -Classify durable decisions through the [decision record guide](decisions/README.md). Reserve architecture decisions for system structure and runtime boundaries, use program decisions for roadmap or governance rules, use evidence decisions for claim classification, and keep ordinary procedures in their owning guides. Preserve superseded records. +Classify durable decisions through the [decision record guide](decisions/README.md). Reserve architecture decisions for product structure and runtime contracts, use program decisions for bounded roadmap and delivery coordination, use evidence decisions for evidence acceptance and permitted claims, and use governance decisions for durable authority or repository-wide policy. Keep ordinary procedures in their owning guides and preserve superseded records. ## Definition of Done diff --git a/docs/PROVENANCE.md b/docs/PROVENANCE.md index c0b66bb..2e1274b 100644 --- a/docs/PROVENANCE.md +++ b/docs/PROVENANCE.md @@ -56,6 +56,14 @@ GitHub's dependency graph defines structural evidence from manifests, lock files The runtime adopts the smaller design conclusion: preserve only the evidence and uncertainty needed for the current decision. It does not implement the external vocabularies, claim standards conformance, impose a relationship taxonomy, or require a graph. +## Decision Record Sources + +Decision-record research for issue #19 was checked on 2026-07-19 against the current repository records, procedure and governance guides, validator, Git history, and related roadmap issues. Public primary sources included [Michael Nygard's original ADR description](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), [MADR 4.0](https://adr.github.io/madr/), the [UK Government ADR Framework](https://www.gov.uk/government/publications/architectural-decision-record-framework/architectural-decision-record-framework), the [ISO/IEC/IEEE 42010 conceptual model](http://www.iso-architecture.org/42010/cm), [Python PEP 1](https://peps.python.org/pep-0001/), the [Open Decision Framework](https://github.com/open-organization/open-decision-framework/blob/master/ODF-community.md), and the [GRADE Working Group](https://www.gradeworkinggroup.org/). + +The sources support a narrow architecture category, short records with explicit status and rationale, preserved supersession history, a shared typed registry, a threshold that excludes ordinary fixes, transparent governance context, and separation of evidence certainty from the resulting decision. [Governance Decision 0005](decisions/0005-use-one-typed-decision-registry.md) applies those precedents to this repository without claiming conformance to an external format. + +No exact private portfolio inventory or additional portfolio repository was named as an authorized evidence source for this implementation. Existing public portfolio summaries support concern separation, but the release does not claim that the complete portfolio uses the same taxonomy. + ## Writing Quality Sources The writing quality decision was reviewed on 2026-07-19 against the repository corpus, issue #15 maintainer feedback, professional edit research, empirical studies of generated prose and model preference, and authoritative technical style guidance. The public source hierarchy and limits are recorded in [Writing Quality](WRITING.md). diff --git a/docs/TESTING.md b/docs/TESTING.md index 456bcc9..937e372 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -25,7 +25,7 @@ npm run package -- vX.Y.Z npm run release:verify-assets -- vX.Y.Z ``` -The validator checks metadata, direct links, required maintenance files, versions, manifests, release notes, workflow mode, Markdown structure, runtime path leakage, placeholders, installation-version synchronization, feedback, decisions, writing-corpus structure, and the 500-line core limit. It also runs `scripts/validate-evaluations.mjs`, which requires every activation row and scenario heading to have a stable registry entry and every required segment to retain coverage. +The validator checks metadata, direct links, required maintenance files, versions, manifests, release notes, workflow mode, Markdown structure, runtime path leakage, placeholders, installation-version synchronization, feedback, decisions, writing-corpus structure, and the 500-line core limit. Decision validation derives canonical types and index coverage from marked blocks in `docs/decisions/README.md`, discovers records dynamically, and checks stable filenames, unique identifiers, matching titles, common sections, exact index membership, and stale links without hard-coding historical record names. The validator also runs `scripts/validate-evaluations.mjs`, which requires every activation row and scenario heading to have a stable registry entry and every required segment to retain coverage. For a release cut, `npm run release:preflight -- vX.Y.Z` snapshots every tracked and nonignored untracked candidate file, runs the complete final-tree gate, builds the assets twice, requires stable checksums, and verifies that the gate does not change the candidate tree. diff --git a/docs/VERSION.md b/docs/VERSION.md index b940cfa..c495dbf 100644 --- a/docs/VERSION.md +++ b/docs/VERSION.md @@ -1,6 +1,6 @@ # Version -Current version: `1.9.0`. +Current version: `1.10.0`. ## Source of Truth diff --git a/docs/decisions/0005-use-one-typed-decision-registry.md b/docs/decisions/0005-use-one-typed-decision-registry.md new file mode 100644 index 0000000..33157c5 --- /dev/null +++ b/docs/decisions/0005-use-one-typed-decision-registry.md @@ -0,0 +1,73 @@ +# Governance Decision 0005: Use One Typed Decision Registry + +Decision type: Governance. + +## Status + +Accepted on 2026-07-19 through [issue #19](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/19) and the v1.10.0 implementation. + +## Context + +The repository originally numbered roadmap sequencing and evidence acceptance records as architecture decisions even though they did not change system structure. Version 1.2.0 corrected the labels and added a small index, but issue #19 intentionally deferred the full taxonomy, procedure boundary, migration, and validation design. + +The current record set shares one directory and four-digit sequence. Published documentation and GitHub history link to those filenames, so reorganizing or renumbering the files would create broken references and obscure why earlier choices were made. + +The validator discovers all record files, but its recognized type list is hard-coded and it checks only whether each file declares a type and appears somewhere in the index. It does not verify stable identifiers, title and type agreement, the common record shape, exact index coverage, or stale index entries. + +Primary architecture guidance favors short records with status, context, decision, consequences, rationale, stable identifiers, and preserved supersession history. Python's PEP registry demonstrates that different decision types can share one numbered index. Open governance and evidence-to-decision guidance support explicit authority, stakeholder, evidence, limitation, and review information for decisions outside architecture. + +## Options + +- Keep the minimal three-type guide and hard-coded validator. +- Keep one directory and sequence, define four explicit types, and make the index the maintained type and discovery registry. +- Split architecture, program, evidence, and governance records into separate directories and identifier sequences. +- Rename or renumber the existing files around the new taxonomy. +- Remove separate records and keep every rationale in its owning guide. + +## Decision + +Keep one `docs/decisions/` directory and one monotonically increasing four-digit identifier sequence for Architecture, Program governance, Evidence classification, and Governance records. Use Governance as the repository term for durable policy decisions about authority, ownership, approval, security acceptance, contribution, release, recommendation independence, or another repository-wide obligation. + +Keep routine testing, release, feedback, maintenance, security, and other operational steps in their owning guides. Create a separate record only when the procedure embodies a durable tradeoff, authority rule, cross-cutting invariant, or recovery constraint whose rationale future maintainers need before changing it. + +Require every record to declare a canonical type and matching title identifier. Require Status, Context, Decision, Consequences, Links, and Review Trigger sections. Include options, rationale, decision makers, consulted stakeholders, evidence, confirmation, and supersession information when they affect the decision. + +Preserve historical filenames and identifiers. Never reuse a number. Keep superseded records, link both directions, and create a new record for a material replacement while maintaining current operating truth in the owning guide. + +Make `docs/decisions/README.md` the maintained type registry, creation guide, migration note, and record index. Validation derives allowed types and index coverage from marked blocks in that guide, discovers record files dynamically, and rejects malformed identifiers, mismatched headings, missing common sections, duplicate identifiers, missing index entries, duplicate index entries, and stale index links. + +## Rationale + +One typed registry preserves every existing URL and keeps the collection easy to scan at its current scale. Explicit types prevent architecture from becoming a generic label while allowing all records to reuse one small format and sequence. + +The creation test keeps ordinary maintenance in the document that owns current behavior. Dynamic validation protects the system's shape without making today's five records permanent dependencies of future releases. + +## Consequences + +Maintainers receive a concrete test, examples, counterexamples, format, status model, supersession rule, migration plan, and creation workflow in one discovery surface. Governance decisions become a supported record type rather than an unused validator value. + +The validator becomes stricter, so a new record must follow the naming, heading, section, and index contracts. It still does not judge whether the decision was wise, whether a body of evidence is true, or whether human approval exists. + +All existing records remain valid without renaming or content migration. Separate type directories remain available as a later change if scale, ownership, access, or lifecycle evidence justifies the additional structure. + +The research did not inspect an unnamed private portfolio inventory or unrelated repositories. The selected taxonomy is justified for this repository and does not claim portfolio-wide adoption. + +## Links + +- [Decision record guide](README.md) +- [Issue #19](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/19) +- [Architecture](../ARCHITECTURE.md) +- [Governance](../GOVERNANCE.md) +- [Testing](../TESTING.md) +- [Releasing](../RELEASING.md) +- [Program Evidence](../PROGRAM-EVIDENCE.md) +- [Michael Nygard's ADR description](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) +- [MADR 4.0](https://adr.github.io/madr/) +- [UK Government ADR Framework](https://www.gov.uk/government/publications/architectural-decision-record-framework/architectural-decision-record-framework) +- [Python PEP 1](https://peps.python.org/pep-0001/) +- [Open Decision Framework](https://github.com/open-organization/open-decision-framework/blob/master/ODF-community.md) +- [GRADE Working Group](https://www.gradeworkinggroup.org/) + +## Review Triggers + +Review this decision when the record index becomes difficult to maintain, one type develops a distinct owner or access boundary, records need different lifecycles, routine changes create excessive record ceremony, validation blocks valid historical forms, a stable redirect mechanism makes reorganization beneficial, or observed maintenance contradicts the four-type boundary. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index a92393a..c97af33 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -2,35 +2,98 @@ ## Purpose -Keep durable decisions reviewable while distinguishing architecture from program governance, evidence classification, and procedure. +Keep durable choices reviewable without calling every important document an architecture decision. A decision record preserves why a choice was made, while the owning runtime, policy, specification, or procedure remains the source for current behavior. + +## Creation Test + +Create a decision record when all of these conditions apply: + +- A specific choice is ready for durable review, accepted, rejected, or superseded. An open question or implementation plan belongs in an issue or pull request until a decision exists. +- The choice changes a durable contract, authority rule, evidence boundary, or cross-cutting program rule rather than one local implementation detail. +- Future maintainers will need the rationale, alternatives, or consequences before they can change the choice responsibly. +- The rationale cannot remain clear enough in the owning architecture, governance, evidence, or procedure guide alone. + +Use a normal documentation or implementation change when the edit corrects facts, applies an accepted decision, changes one local detail, or updates routine steps without creating a new durable tradeoff or authority boundary. This threshold keeps the record set small enough to review and prevents ordinary maintenance from becoming governance ceremony. ## Decision Types -### Architecture Decision +The values between the markers are the canonical `Decision type` values used by validation. + + +- `Architecture`: A durable choice about system structure, component or source boundaries, runtime contracts, quality-attribute tradeoffs, integration shape, dependencies, interfaces, or a significant technical constraint. +- `Program governance`: A cross-cutting choice about roadmap sequencing, delivery coordination, program review, or how a bounded program uses evidence without changing product structure or permanent repository authority. +- `Evidence classification`: A choice that accepts, rejects, classifies, or limits a body of evidence and states the claims that evidence may support. +- `Governance`: A durable policy choice about decision authority, ownership, approval, security acceptance, contribution rules, release authority, recommendation independence, or another repository-wide obligation. + + +Use `Governance` as this repository's policy-decision type. A program decision coordinates a bounded delivery or learning program; a governance decision controls authority or obligations that continue independently of that program. + +## Examples and Counterexamples + +| Type or owner | Record-worthy example | Keep in the owning artifact | +|---|---|---| +| Architecture | Add a focused runtime reference instead of expanding the always-loaded core. | Reword one paragraph without changing behavior or source boundaries. | +| Program governance | Separate repository delivery from external outcome evidence across the roadmap. | Update one issue checklist or release date. | +| Evidence classification | Accept a founding trial for one claim while excluding it from unsolicited-adoption claims. | Add a source link or correct an observation date without changing the accepted claim. | +| Governance | Change who may approve public releases or accept security risk. | Clarify a contributor step without changing authority or obligations. | +| Procedure guide | Record a release immutability or recovery tradeoff that future maintainers must understand before changing the steps. | Update a command, tool version, or routine sequence in `TESTING.md`, `RELEASING.md`, `FEEDBACK.md`, or `MAINTENANCE.md`. | + +## Record Format -Use an architecture decision when a choice changes durable system structure, component or source boundaries, runtime contracts, quality-attribute tradeoffs, integration shape, or a technically significant constraint. Architecture decisions belong in this directory with `Decision type: Architecture`. +Use the next unused four-digit identifier and a lowercase dashed filename: `NNNN-short-title.md`. Keep all types in this directory and one shared sequence. Never reuse an identifier, even when a draft is rejected or a record is superseded. -### Program Decision +Start the title with the display type and matching identifier, such as `# Governance Decision 0005: Use One Typed Decision Registry`. Declare the canonical type on the next line as `Decision type: Governance.` -Use a program decision when a choice changes roadmap sequencing, delivery governance, evidence use, review policy, or another cross-cutting program rule without changing system structure. Program decisions belong in this directory with `Decision type: Program governance`. +Every record contains these sections: -### Evidence Decision +- `Status` states whether the choice is proposed, accepted, rejected, deprecated, or superseded and gives the relevant date or replacement. +- `Context` states the problem, constraints, and relevant evidence without presenting inference as fact. +- `Decision` states the chosen rule or response in current, explicit language. +- `Consequences` records beneficial, adverse, and neutral effects that matter to later work. +- `Links` connects the owning issue, implementation, current guidance, and related or superseding records. +- `Review Trigger` or `Review Triggers` states which changed evidence or operating condition should reopen the choice. -Use an evidence decision when a choice accepts, rejects, classifies, or limits a body of evidence and its permitted claims. Evidence decisions belong in this directory with `Decision type: Evidence classification`. +Add options, rationale, decision makers, consulted stakeholders, confirmation, or a supersession section when they improve reviewability. Do not copy the current procedure into the record; link the owning guide instead. -### Procedure +## Status and Supersession -Put ordinary steps in their owning guide, such as `TESTING.md`, `RELEASING.md`, `FEEDBACK.md`, or `MAINTENANCE.md`. Create a decision record only when the procedure reflects a durable tradeoff, authority rule, or cross-cutting policy that future maintainers must understand before changing it. +Preserve accepted, rejected, deprecated, and superseded records as history. Correct factual errors and maintain status, replacement, and link information, but create a new record when the decision itself changes materially. -## Current Records +The replacement links back with `Replaces`, and the older record links forward with `Superseded by`. Current runtime, governance, evidence, and procedure documents must state the rule that applies now so an agent does not need every historical record to perform ordinary work. +## Record Index + +The index is the discovery surface for every record. Validation discovers record files from this directory and requires each file to appear exactly once between these markers. + + - [Program Decision 0001](0001-evidence-gated-roadmap.md) records the original evidence-gated roadmap model and is superseded. - [Evidence Decision 0002](0002-accept-founding-use-case-for-phase-0.md) classifies the founding target use case and its claim boundary. - [Program Decision 0003](0003-separate-delivery-from-outcome-evidence.md) separates repository delivery from external outcome evidence. - [Architecture Decision 0004](0004-separate-benefit-discovery-from-inventory.md) separates focused benefit discovery from inventory administration and persistent relationship storage. +- [Governance Decision 0005](0005-use-one-typed-decision-registry.md) defines the shared taxonomy, procedure boundary, identifier policy, index, and validation contract. + + +## Maintainer Workflow + +1. Link the proposed choice to an issue and confirm that it passes the creation test. +2. Compare the current system and no change with the serious alternatives. +3. Select the decision type and next unused identifier without renaming historical files. +4. Add the record, update its owning current guide, and add one index entry in the same pull request. +5. Run `npm run validate` and the release checks required by the change. +6. After acceptance, keep implementation and current operating truth in their owning artifacts and use a later record for material replacement. + +## Migration + +The v1.10.0 migration is additive. Records 0001 through 0004 retain their filenames, identifiers, type labels, links, and history. Record 0005 adds the previously documented but unused `Governance` type and formalizes the shared registry. + +Separate directories or per-type sequences would add navigation and collision rules without improving the current five-record collection. Revisit categorization only when the index becomes difficult to maintain or one type develops a distinct owner, audience, access boundary, or lifecycle. + +## Research Basis + +Research for [issue #19](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/19) was reviewed on 2026-07-19. The repository audit covered all current records, procedure and governance guides, validation, Git history, and related roadmap issues. -## Maintenance +Primary sources support short records with status, context, decision, consequences, rationale, stable identifiers, and preserved supersession history. [Michael Nygard's original ADR description](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), [MADR 4.0](https://adr.github.io/madr/), [the UK Government ADR Framework](https://www.gov.uk/government/publications/architectural-decision-record-framework/architectural-decision-record-framework), and the [ISO/IEC/IEEE 42010 conceptual model](http://www.iso-architecture.org/42010/cm) define the architecture boundary and common record shape. -Preserve superseded records and link their replacement. Each record states its decision type, status, context, decision, consequences, links, and review or supersession trigger. +[Python PEP 1](https://peps.python.org/pep-0001/) demonstrates one indexed sequence with explicit record types and a threshold that leaves ordinary fixes outside the proposal system. The [Open Decision Framework](https://github.com/open-organization/open-decision-framework/blob/master/ODF-community.md) informs the governance fields for authority, stakeholders, constraints, research, impact, and review. The [GRADE Working Group](https://www.gradeworkinggroup.org/) supports keeping evidence certainty and limitations separate from the recommendation or decision made from that evidence. -The deeper research into decision types, naming, storage, and procedure boundaries is tracked in [issue #19](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/19) and does not block the current roadmap delivery. +No exact private portfolio inventory or additional portfolio repository was named as an authorized evidence source for this implementation. Existing public repository summaries corroborate the value of separating architecture, evidence, governance, and procedure concerns, but this release does not claim that the complete portfolio uses the same four-type taxonomy. diff --git a/docs/releases/v1.10.0.md b/docs/releases/v1.10.0.md new file mode 100644 index 0000000..7e21d2d --- /dev/null +++ b/docs/releases/v1.10.0.md @@ -0,0 +1,48 @@ +# Coordinate GitHub Repositories v1.10.0 + +Version `1.10.0` completes issue #19 with a researched decision-record taxonomy, a history-preserving migration, maintainer guidance, and proportionate validation. + +## Decision Taxonomy + +- Define Architecture decisions for product structure, runtime contracts, quality attributes, source boundaries, integration shape, interfaces, dependencies, and significant technical constraints. +- Define Program governance decisions for bounded roadmap, delivery, review, and program-evidence coordination. +- Define Evidence classification decisions for accepting, rejecting, classifying, or limiting evidence and its permitted claims. +- Define Governance decisions as the repository's policy type for durable authority, ownership, approval, security acceptance, contribution, release, recommendation-independence, and repository-wide obligations. +- Keep routine testing, release, feedback, maintenance, security, and other operational steps in their owning guides unless a change creates a durable tradeoff, authority rule, cross-cutting invariant, or recovery constraint. + +## Stable Migration + +- Add [Governance Decision 0005](../decisions/0005-use-one-typed-decision-registry.md) for the taxonomy, shared sequence, procedure boundary, record format, supersession rule, and validation design. +- Keep all record types in `docs/decisions/` with one monotonically increasing four-digit sequence. +- Preserve records 0001 through 0004 without renaming, renumbering, or changing their published URLs. +- Make the [decision record guide](../decisions/README.md) the creation test, type registry, record index, migration note, and maintainer workflow. +- Keep current behavior and procedures in their owning runtime, governance, evidence, and operational documents so ordinary work does not depend on reading every historical record. + +## Deterministic Validation + +- Derive allowed decision types from marked content in the maintained guide instead of a list embedded in the validator. +- Discover decision files dynamically and require stable filenames, unique identifiers, titles that match type and identifier, and the common Status, Context, Decision, Consequences, Links, and Review Trigger sections. +- Require every record to appear exactly once in the marked index and reject index links that do not resolve to a record. +- Keep historical files out of the repository's fixed current-file dependency list. + +## Research and Scope + +The research reviewed the current record set, procedure and governance guides, validation, Git history, and related roadmap issues on 2026-07-19. Primary sources included Michael Nygard's original ADR description, MADR 4.0, the UK Government ADR Framework, ISO/IEC/IEEE 42010 material, Python PEP 1, the Open Decision Framework, and GRADE evidence-to-decision guidance. + +No exact private portfolio inventory or additional portfolio repository was named as an authorized evidence source. Existing public summaries support separating architecture, evidence, governance, and procedure concerns, but this release does not claim that the full portfolio uses the same four-type taxonomy. + +## Compatibility + +This minor release adds a backward-compatible maintainer decision workflow and stronger repository validation. It leaves `skills/coordinate-github-repositories/SKILL.md`, every runtime reference, activation and output behavior, safety and permission boundaries, evaluation fixtures, package formats, installation paths, and the conversation-only fallback unchanged. + +## Verification + +Run the final release gate with the intended tag: + +```bash +npm run release:preflight -- v1.10.0 +``` + +Inspect all three ZIP files under `dist/assets/`. Confirm that runtime content remains byte-identical across packages and that documentation, decision records, fixtures, temporary research, private intake, credentials, local paths, and unrelated repository material remain excluded. + +Release tag: `v1.10.0`. diff --git a/package.json b/package.json index 6058fd6..f63cfbc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "coordinate-github-repositories-skill", - "version": "1.9.0", + "version": "1.10.0", "private": true, "type": "module", "scripts": { diff --git a/packaging/claude-plugin/.claude-plugin/plugin.json b/packaging/claude-plugin/.claude-plugin/plugin.json index 1807af6..83a72a6 100644 --- a/packaging/claude-plugin/.claude-plugin/plugin.json +++ b/packaging/claude-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "coordinate-github-repositories", "displayName": "Coordinate GitHub Repositories", - "version": "1.9.0", + "version": "1.10.0", "description": "GitHub repository access, benefit discovery, inventory, routing, coordination, and tool selection across code and non-code work.", "author": { "name": "TechSpokes", diff --git a/packaging/codex-plugin/.codex-plugin/plugin.json b/packaging/codex-plugin/.codex-plugin/plugin.json index d7b1df8..0793059 100644 --- a/packaging/codex-plugin/.codex-plugin/plugin.json +++ b/packaging/codex-plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "coordinate-github-repositories", - "version": "1.9.0", + "version": "1.10.0", "description": "GitHub repository access, benefit discovery, inventory, routing, coordination, and tool selection across code and non-code work.", "author": { "name": "TechSpokes", diff --git a/scripts/validate-skill.mjs b/scripts/validate-skill.mjs index 8445297..04fc3fa 100644 --- a/scripts/validate-skill.mjs +++ b/scripts/validate-skill.mjs @@ -694,19 +694,79 @@ function validateFeedbackContract() { } function validateDecisionRecords() { - // @constraints Historical records are indexed by decision type instead of being hard-coded as current repository dependencies. + // @constraints Issue #19 requires validation to discover historical records instead of hard-coding the files from one release. const index = readText("docs/decisions/README.md"); - const allowedTypes = new Set(["Architecture", "Program governance", "Evidence classification", "Governance"]); + const markedBlock = (startMarker, endMarker, label) => { + const start = index.indexOf(startMarker); + const end = index.indexOf(endMarker); + if (start === -1 || end === -1 || end <= start) { + fail(`docs/decisions/README.md must contain the ${label} markers in source order.`); + return null; + } + return index.slice(start + startMarker.length, end); + }; + + const typeBlock = markedBlock("", "", "decision type registry"); + const recordIndexBlock = markedBlock("", "", "decision index"); + if (typeBlock === null || recordIndexBlock === null) { + return; + } + + const declaredTypes = [...typeBlock.matchAll(/^- `([^`\n]+)`:/gm)].map((match) => match[1]); + const allowedTypes = new Set(declaredTypes); + if (declaredTypes.length === 0 || allowedTypes.size !== declaredTypes.length) { + fail("docs/decisions/README.md must declare unique canonical decision types inside the type registry markers."); + } + const records = walk("docs/decisions").filter((file) => file.endsWith(".md") && path.basename(file) !== "README.md"); + const recordNames = new Set(records.map((file) => path.basename(file))); + const indexedNames = [...recordIndexBlock.matchAll(/\]\((\d{4}-[a-z0-9]+(?:-[a-z0-9]+)*\.md)\)/g)].map((match) => match[1]); + const numberOwners = new Map(); for (const file of records) { const text = readText(file); + const filename = path.basename(file); + const filenameMatch = filename.match(/^(\d{4})-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/); + if (!filenameMatch) { + fail(`${file} must use the stable NNNN-lowercase-dashed-title.md filename format.`); + continue; + } + + const identifier = filenameMatch[1]; + if (numberOwners.has(identifier)) { + fail(`${file} reuses decision identifier ${identifier} already owned by ${numberOwners.get(identifier)}.`); + } else { + numberOwners.set(identifier, file); + } + const type = text.match(/^Decision type:\s*([^\n.]+)\.?$/m)?.[1]; if (!type || !allowedTypes.has(type)) { fail(`${file} must declare a recognized Decision type.`); + } else { + const displayType = type.split(/\s+/)[0]; + if (!text.startsWith(`# ${displayType} Decision ${identifier}: `)) { + fail(`${file} title must match its Decision type and identifier.`); + } + } + + for (const section of ["Status", "Context", "Decision", "Consequences", "Links"]) { + if (!new RegExp(`^## ${section}$`, "m").test(text)) { + fail(`${file} must contain a ${section} section.`); + } } - if (!index.includes(`(${path.basename(file)})`)) { - fail(`${file} must be linked from docs/decisions/README.md.`); + if (!/^## Review Triggers?$/m.test(text)) { + fail(`${file} must contain a Review Trigger or Review Triggers section.`); + } + + const indexEntryCount = indexedNames.filter((name) => name === filename).length; + if (indexEntryCount !== 1) { + fail(`${file} must appear exactly once inside the decision index markers.`); + } + } + + for (const filename of indexedNames) { + if (!recordNames.has(filename)) { + fail(`docs/decisions/README.md indexes missing decision record ${filename}.`); } } }