diff --git a/CHANGELOG.md b/CHANGELOG.md index 61fd18b..6feb33e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ ## [Unreleased] +## [v1.11.0] + +- Replace the completed seven-phase roadmap as current direction with an ordered, outcome-led roadmap for transferability, value reuse, host and release trust, and maintenance continuity. +- Keep exact delivery state in GitHub issues and pull requests, preserve the founding phase program in its historical delivery record, and avoid a duplicated Markdown backlog. +- Define how observations, outcome evidence, quality findings, and maintainer reviews become candidates without promoting them into accepted work automatically. +- Add Program Decision 0006 for the living roadmap, canonical delivery state, evidence boundary, ownership, review triggers, and recovery path. +- Validate current roadmap structure, review metadata, open-issue routing, historical phase separation, and the evidence-to-priority boundary instead of requiring stale completion phrases. +- Preserve runtime activation, user-facing coordination behavior, safety and permission boundaries, fixtures, package formats, and conversation-only usefulness. + ## [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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 308b425..b47176d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ Explain: - Which fixtures changed or still pass. - Commands and manual checks used for validation. - Product facts that need a source date or future refresh. -- Affected roadmap phase, threat, evaluation case, decision, and release links. +- Affected roadmap direction, threat, evaluation case, decision, and release links. ## Source and Privacy Rules diff --git a/README.md b/README.md index 588a1e2..d97b685 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, [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. +Use the [Roadmap](docs/ROADMAP.md) for current product direction and work selection, [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.10.0`. +Current version: `1.11.0`. The repository is maintained by TechSpokes and licensed under [MIT](LICENSE). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7e6a758..1c71594 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -68,11 +68,13 @@ The skill can execute user-authorized changes through available tools, but mutat ### Delivery and Evidence -The [roadmap](ROADMAP.md) separates repository delivery from outcome evidence. Founding validation is documented in [Evidence That Shaped the Design](#evidence-that-shaped-the-design). Missing external adoption evidence limits claims and identifies future learning without freezing unrelated work whose authority, sources, safety boundary, dependencies, and validation are ready. +The [roadmap](ROADMAP.md) maintains current outcome priorities and work-selection rules. GitHub issues and pull requests own active delivery state, while the [founding delivery record](ROADMAP-DELIVERY.md) preserves the completed phase program without presenting it as current work. + +Repository delivery remains separate from outcome evidence. Founding validation is documented in [Evidence That Shaped the Design](#evidence-that-shaped-the-design). Missing external adoption evidence limits claims and identifies future learning without freezing unrelated work whose authority, sources, safety boundary, dependencies, and validation are ready. Architecture, security, privacy, evaluation, teaching, governance, and release integrity remain quality controls. A red affected control blocks the release or public action; an unknown outside outcome does not compensate for that regression and is not itself a quality failure. -Roadmap phase numbers do not determine release versions. Versions describe runtime and package contract impact, while adoption and other outcomes remain recorded in issues and evidence records. +Founding roadmap phase numbers do not determine release versions. Versions describe runtime, maintainer workflow, and package contract impact, while adoption and other outcomes remain recorded in issues and evidence records. ### Teaching Without Runtime Bloat @@ -159,7 +161,7 @@ Keep the main skill under 500 lines and direct references one level deep. Add a Refresh `agent-capability-adapters.md` when hosts change skill paths, connector permissions, CLI publication, or access behavior. Revisit the core only when the goal, activation boundary, workflow, safety contract, feedback contract, or output contract changes. -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. +Use the [threat model](THREAT-MODEL.md), [governance contract](GOVERNANCE.md), [maintenance health](MAINTENANCE.md), [decision classification](decisions/README.md), [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md), and [Program Decision 0006](decisions/0006-maintain-a-living-outcome-led-roadmap.md) when a change affects privileged tools, public output, feedback, portal handoff, recommendation independence, contribution quality, roadmap direction, 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. diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index 125edaf..77ae073 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -28,6 +28,12 @@ A change is done only when all applicable conditions pass: - User-facing guidance names the risk reduced by a security practice when that reason aids future judgment. - Release, roadmap, architecture, and decision trace links are updated. +## Roadmap Governance + +The [Roadmap](ROADMAP.md) owns current product outcomes, selection rules, evidence boundaries, review ownership, and refresh triggers. GitHub issues and pull requests own exact delivery state, [Program Evidence](PROGRAM-EVIDENCE.md) owns publishable outcome observations, and the [Founding Roadmap Delivery Record](ROADMAP-DELIVERY.md) owns completed phase history. + +Do not copy an issue backlog into the roadmap or promote feedback into accepted work automatically. A maintainer accepts a candidate only after its benefit, evidence, target, authority, risk, completion evidence, and owner are clear enough for the proposed change. + ## Contribution Review Rubric ### Architecture and Maintainability @@ -52,7 +58,7 @@ Name the owner, maintenance burden, release impact, review trigger, and conflict ## Maintainer Model -Maintainers are responsible for issue enrichment, feedback routing, security handling, classified decision records, fixture review, release validation, package inspection, and source refreshes. Agents should perform routine discovery, structuring, duplicate checks, routing, and verification when authorized so human attention stays focused on judgment and authority. Add a maintainer only after repeated, reviewable contributions demonstrate judgment across these responsibilities. +Maintainers are responsible for roadmap review, issue enrichment, feedback routing, security handling, classified decision records, fixture review, release validation, package inspection, and source refreshes. Agents should perform routine discovery, structuring, duplicate checks, routing, and verification when authorized so human attention stays focused on judgment and authority. Add a maintainer only after repeated, reviewable contributions demonstrate judgment across these responsibilities. At least two authorized maintainers should be able to perform the release process before the project claims succession resilience. Record who may approve releases, handle private vulnerability reports, change repository settings, and supersede durable decisions without publishing personal schedules or credentials. diff --git a/docs/MAINTENANCE.md b/docs/MAINTENANCE.md index 44492bb..ff29030 100644 --- a/docs/MAINTENANCE.md +++ b/docs/MAINTENANCE.md @@ -2,12 +2,14 @@ ## Purpose -Keep the runtime, evidence, security, releases, and maintainer responsibilities reviewable without turning maintenance into ceremony. +Keep the roadmap, runtime, evidence, security, releases, and maintainer responsibilities reviewable without turning maintenance into ceremony. ## Current Health The package manifest is the current release identity source, with synchronized plugin manifests, changelog, version policy, and release notes. The canonical portable runtime remains useful with conversation alone, every focused reference is linked directly from `SKILL.md`, and deterministic Node.js validation checks the maintained agent surface against the actual runtime tree. +The living roadmap owns current outcome priorities and work-selection rules. GitHub issues and pull requests own delivery state, while the founding delivery record preserves completed phase history. + The evaluation registry covers activation, behavior, goal survival, feedback, access denial, write capability, platform fit, non-code work, writing quality, and adversarial containment. The writing corpus protects accepted repairs and legitimate technical language without adding grammar scoring. The threat model covers untrusted repository content, privileged tools, workspace and authority drift, private context, public output, and release artifacts. Volatile host behavior remains isolated in the dated capability adapter. Release packages remain deterministic, carry SHA-256 checksums, and receive GitHub artifact attestations. @@ -20,7 +22,7 @@ The missing second maintainer is a continuity risk, not a reason to withhold doc ## Review Cadence -Review maintenance after a runtime release, security report, evaluation regression, material writing defect, goal or authority drift, host capability change, stale public source, package mismatch, repeated feedback pattern, maintainer change, or failed release handoff. +Review maintenance after a product-direction change, runtime release, security report, evaluation regression, material writing defect, goal or authority drift, host capability change, stale public source, package mismatch, repeated feedback pattern, maintainer change, or failed release handoff. ## Fast Health Check @@ -28,4 +30,4 @@ Run `npm run validate`, package the intended tag, inspect all three ZIPs and `SH ## Ownership -Maintainers own issue enrichment, feedback routing, security handling, decision records, fixture review, release approval, package inspection, and correction. Agents may prepare and verify this work within explicit authority, leaving humans to make publication, privacy, security-acceptance, and governance decisions. +Maintainers own roadmap review, issue enrichment, feedback routing, security handling, decision records, fixture review, release approval, package inspection, and correction. Agents may prepare and verify this work within explicit authority, leaving humans to make publication, privacy, security-acceptance, and governance decisions. diff --git a/docs/PROGRAM-EVIDENCE.md b/docs/PROGRAM-EVIDENCE.md index a1b25d7..097f2ac 100644 --- a/docs/PROGRAM-EVIDENCE.md +++ b/docs/PROGRAM-EVIDENCE.md @@ -2,7 +2,7 @@ ## Purpose -Use these records to run the roadmap without turning attention, recruited praise, or maintainer judgment into false product evidence. Store only sanitized, consented, publishable information in the public repository. +Use these records to inform product claims and roadmap priorities without turning attention, recruited praise, or maintainer judgment into false product evidence. Store only sanitized, consented, publishable information in the public repository. Keep raw volunteer repository maps, account topology, local paths, private issue content, credentials, and contact details outside this repository. Do not create a durable participant profile unless the participant approves its fields, location, visibility, owner, and retention. @@ -173,6 +173,12 @@ Unknown outcome evidence is valid and limits the claim rather than blocking unre Historical `phase_gate` records remain valid evidence of the decision model used at the time. Do not rewrite them; use `phase_review` for new decisions. +## Roadmap Use + +Outcome evidence may change a claim, reveal a product gap, or change the order of roadmap priorities. It does not become accepted work automatically. + +When evidence justifies implementation, enrich one canonical GitHub issue with the intended benefit, scope, owner, authority, risks, completion evidence, and verification. Keep observation records here, current product direction in the [Roadmap](ROADMAP.md), exact delivery state in GitHub, and completed founding program history in the [Founding Roadmap Delivery Record](ROADMAP-DELIVERY.md). + ## Baseline and Skill-Assisted Review Use the registered cases under `tests/evals/`. Run a bare-agent response and a fresh skill-assisted response under comparable capability assumptions. Score both against the fixture invariants without expecting exact wording. diff --git a/docs/PROVENANCE.md b/docs/PROVENANCE.md index 2e1274b..a491f3c 100644 --- a/docs/PROVENANCE.md +++ b/docs/PROVENANCE.md @@ -4,7 +4,7 @@ The skill was designed from user requirements for adaptive repository coordination across personal accounts, organizations, non-code work, coding agents, and general agents. The user required context-sensitive tool advice that does not harm established workflows or silently persist a personal profile. -Issue #6 supplied a public strategy attachment with market observations, seven growth phases, and five cross-cutting quality tracks. The repository preserves the durable phase objectives and quality controls while separating repository deliverables from external evidence that maintainers cannot manufacture. +Issue #6 supplied a public strategy attachment with market observations, seven growth phases, and five cross-cutting quality tracks. The repository preserves the completed program, durable outcome priorities, and quality controls while separating repository deliverables from external evidence that maintainers cannot manufacture. ## Founding Lineage @@ -76,9 +76,11 @@ The complete research notes, confidence records, contradictions, and source extr ## Roadmap Source Treatment -The issue #6 attachment is authoritative for the requested program direction, not for every market or security claim it cites. Phase plans use its durable objectives, safety principles, and evidence controls. Publishable market claims, community rules, product behavior, pricing, and host capabilities must be verified from current primary sources when they affect an action. +The issue #6 attachment was authoritative for the requested founding program direction, not for every market or security claim it cited. The completed phase plans preserved its durable objectives, safety principles, and evidence controls. Publishable market claims, community rules, product behavior, pricing, and host capabilities still require current primary sources when they affect an action. -The attachment is not installed as runtime content. The reviewed program contract lives in `docs/ROADMAP.md`, phase plans live in issues #7 through #13, and the classified program decisions live in `docs/decisions/`. +The attachment is not installed as runtime content. The completed phase plans remain in issues #7 through #13, the delivery result remains in `docs/ROADMAP-DELIVERY.md`, and the classified program decisions remain in `docs/decisions/`. + +Issue #46 and Program Decision 0006 moved `docs/ROADMAP.md` to a living outcome-led maintenance model on 2026-07-19. This repository audit used public files, issues, pull requests, tags, and release history; it did not inspect an unnamed private portfolio inventory or another repository. ## Installation Usability Comparison diff --git a/docs/ROADMAP-DELIVERY.md b/docs/ROADMAP-DELIVERY.md index 9294bac..a4d6e99 100644 --- a/docs/ROADMAP-DELIVERY.md +++ b/docs/ROADMAP-DELIVERY.md @@ -1,6 +1,8 @@ -# Roadmap Delivery Record +# Founding Roadmap Delivery Record -## Claim +## Historical Scope + +This record preserves the repository delivery completed under issue #6 and roadmap issues #7 through #13. Use the [Roadmap](ROADMAP.md) for current product direction and GitHub issues for active delivery state. The work maintained in this repository for roadmap issues #7 through #13 is complete. External adoption, launch attention, retention, portal recommendation, derivative work, outside contribution, and second maintainer evidence remain unknown or unobserved and are not claimed. @@ -34,7 +36,7 @@ Delivered a free MIT core, release checksums and attestations, rules that preser ## Cross-Cutting Review -Architecture remains portable with one canonical skill and references linked directly from `SKILL.md`. Security and privacy keep retrieved content untrusted, mutation authorized, feedback sanitized, and tests contained. Evaluation registers all affected scenarios. Teaching keeps human intake simple and delegates enrichment to agents. Governance keeps claims, evidence relationships, publication authority, and commercial interests explicit. +Architecture remained portable with one canonical skill and references linked directly from `SKILL.md`. Security and privacy kept retrieved content untrusted, mutation authorized, feedback sanitized, and tests contained. Evaluation registered every affected scenario. Teaching kept human intake simple and delegated enrichment to agents. Governance kept claims, evidence relationships, publication authority, and commercial interests explicit. ## Deferred Outcome Evidence @@ -42,4 +44,6 @@ Future observations may establish outside usefulness, attention, retention, reco ## Decision Basis -[Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md) separates repository delivery from outcome evidence. [Roadmap issue #6](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/6) and the phase issues retain the complete public history. +[Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md) separated repository delivery from outcome evidence. [Program Decision 0006](decisions/0006-maintain-a-living-outcome-led-roadmap.md) preserved this record as history when the active roadmap moved to ongoing outcome-led maintenance. + +[Roadmap issue #6](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/6) and the phase issues retain the complete public delivery history. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 9f978a7..8359767 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,106 +1,65 @@ # Roadmap -## Program Goal +## Purpose -Make Coordinate GitHub Repositories a trusted, useful, free, and maintainable option for repository coordination across code and non-code work. Growth is valid only when the runtime, security posture, evaluation evidence, teaching value, and governance remain healthy. +This living roadmap states the current product outcomes and the rules used to select work after the founding phase program finished. GitHub issues and pull requests are the canonical delivery state; this document does not copy their task status. -This roadmap implements [issue #6](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/6). It transforms the attached strategy into a delivery program guided by evidence that fits the current portable architecture and release process. +Last reviewed: `2026-07-19`. -## Scope Boundary +Owner: repository maintainers. -The repository can supply runtime behavior, tests, documentation, release controls, and evidence formats. It cannot manufacture volunteer insight, unsolicited adoption, third-party recommendations, outside contributions, or additional maintainers. Missing external adoption evidence limits claims and identifies future learning work, but it does not freeze unrelated repository work that is authorized, sourced, contained, and testable. +## Product Goal -Use the founding portfolio and its roughly 340 repository observations as deep product evidence while preserving its disclosed builder and maintainer relationship. This founding validation is documented in [Architecture](ARCHITECTURE.md#evidence-that-shaped-the-design). Do not relabel recruited or founding evidence as unsolicited. +Help people and agents preserve and reuse repository-centered value with less human administration while maintaining a portable, trustworthy, free, and maintainable skill that respects authority, privacy, evidence integrity, ownership, and existing workflows. -## Operating Model +## Current Outcome Priorities -### Execution Readiness +The priorities are ordered. A lower priority may move first when it addresses an urgent quality risk or when the higher priority lacks evidence, authority, or an implementation owner. -Start any roadmap workstream when its authority, source, privacy, security, dependency, and validation needs are satisfied. Do not require a star, issue, testimonial, recommendation, outside contribution, or second maintainer before beginning authorized repository work that does not depend on that person. +### 1. Establish Transferability Through Real Use -### Outcome Evidence +Learn whether people beyond the founding maintainer can reach useful outcomes across software, documentation, writing, research, data, operations, and mixed work. Prefer observations from real runs, preserve participant relationships, and improve the product without presenting recruited or founding evidence as unsolicited adoption. -Classify outcome evidence as founding, recruited, unsolicited, operational, or mixed. Record the source, observation window, participant relationship, limitations, owner, privacy review, and release identity. Outcome evidence changes claim strength and learning priorities; it does not determine whether unrelated implementation may proceed. +### 2. Improve Value Preservation and Reuse -### Quality Review +Reduce the effort required to find, understand, apply, and preserve useful functionality, knowledge, practices, and relationships across repositories. Prioritize observed gaps that the portable reasoning layer can solve without imposing a taxonomy, persistent profile, graph, connector, portal, or manager application. -Review all five cross-cutting tracks for every affected release or public action: +### 3. Maintain Trust Across Hosts and Releases -- Architecture and maintainability. -- Security and privacy. -- Agent behavior and evaluation. -- Teaching and user learning. -- Governance, contribution quality, and sustainability. +Keep conversation-only usefulness, least privilege, privacy, untrusted-content handling, evaluation coverage, package identity, installation paths, and recovery healthy as agent hosts and GitHub capabilities change. Treat a red security, privacy, evaluation, release-integrity, or values result as a blocker for the affected release or public action. -A red security, privacy, evaluation, release-integrity, or values result blocks the affected release or public action until corrected or accepted by an accountable reviewer. An unknown adoption result does not compensate for a quality regression, and a quality result does not prove adoption. +### 4. Reduce Maintenance and Continuity Risk -### Completion Rule +Keep decisions, tests, documentation, release controls, support routes, and ownership understandable enough for another qualified maintainer to review and operate. Simplify recurring work before adding automation, and do not claim succession resilience until at least two authorized maintainers can perform the release process. -Close a phase issue when its feasible repository deliverables are complete, any deferred work has a recorded reason and trigger, affected checks pass, and the public claim matches the available evidence. Continue collecting outcome observations through evidence records without reopening completed implementation by default. +## Work Selection -## Roadmap Workstreams +Candidate work may come from a real run, a sanitized feedback observation, a security report, an evaluation failure, a host change, a release failure, a maintainer review, or outcome evidence. An observation is not automatically an accepted task. -The phase numbers preserve the strategy's learning sequence. They are not hard dependencies between repository workstreams. +Compare each candidate with the current system and no change. Rank it by expected user benefit, evidence quality, affected risk, frequency, reach across work types, urgency, reversibility, maintenance burden, dependency readiness, and available ownership. -### Phase 0: Foundation +Accept work only when the target, authority, source, privacy boundary, security impact, dependencies, completion evidence, and owner are clear enough for the proposed change. Record accepted work in a GitHub issue and route implementation through a pull request. -[Issue #7](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/7) establishes trust, evaluation, and evidence from the founding outcome. The founding builder used the skill through an agent on the real portfolio that motivated the repository and confirmed a previously unnoticed insight. Phase 0 is complete with the participant relationship and limitations recorded. +Use the repository's [open issues](https://github.com/TechSpokes/skill-github-repositories-coordination/issues?q=is%3Aissue%20state%3Aopen) for current work. An empty issue list may mean that no candidate is ready; it does not justify inventing work or weakening evidence. -### Phase 1: Proof +## Evidence and Claim Boundary -[Issue #8](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/8) makes the founding result transferable through a reviewed case study, discoverable security guidance, newcomer entry points, and honest evidence records. Unsolicited signals remain useful later observations and do not block delivery. +Repository delivery and outcome evidence remain separate under [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md). Missing external adoption evidence limits claims. It does not block unrelated repository work whose authority, inputs, safety boundary, dependencies, and validation are ready. -### Phase 2: Secure Launch +Classify outcome evidence as founding, recruited, unsolicited, operational, or mixed. Record publishable observations through [Program Evidence](PROGRAM-EVIDENCE.md), and use [Feedback From Humans and Agents](FEEDBACK.md) for low-friction intake. Neither surface grants publication authority or promotes an observation into accepted work. -[Issue #9](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/9) prepares a secure coordinated launch with bounded messages, verified proof links, support ownership, correction paths, and measurement records. A red security or evaluation board blocks the launch action; missing attention does not block preparation or later product work. +Quality evidence and outcome evidence cannot substitute for each other. A passing validator does not prove user benefit, and an adoption signal does not excuse a security, privacy, evaluation, or release-integrity regression. -### Phase 3: Teaching +## Historical Program -[Issue #10](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/10) teaches beginners and non-code users through installation, first run, security concepts, work habits, accessibility criteria, and comprehension evaluations. Outside completion and return behavior remain ongoing learning evidence. +Issue [#6](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/6) and phase issues #7 through #13 delivered the founding seven-phase program. The [Founding Roadmap Delivery Record](ROADMAP-DELIVERY.md) preserves what the repository delivered and which external outcomes remained unproven. -### Phase 4: Portal Interoperability +The completed phase program is evidence and history, not the active backlog. [Program Decision 0006](decisions/0006-maintain-a-living-outcome-led-roadmap.md) records the transition to this living outcome-led model. -[Issue #11](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/11) defines honest portal positioning, bounded handoff, fully qualified tool routing, and graceful access failure. Adoption by an engineering organization remains an outcome observation rather than an implementation dependency. +## Review and Recovery -### Phase 5: Skill Constellation +Review this roadmap when evidence changes a priority, accepted work does not map to an outcome, open issues repeatedly drift from the stated direction, a serious quality finding appears, a material host or maintainer change occurs, or the selection model creates unnecessary administration. -[Issue #12](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/12) defines contribution quality, decision records, and a minimal cross-skill handoff contract. Complementary skills are created only when a distinct repeated job has enough evidence; the absence of a justified new skill is a valid no-change result. +Review the roadmap during every minor or major release that changes product direction or the maintainer workflow. Change the review date only after reassessing the priorities, selection rules, evidence boundary, ownership, and historical links. -### Phase 6: Sustainability - -[Issue #13](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/13) protects the free core and establishes recommendation independence, release provenance, health review, succession responsibilities, and continuous maintenance. Current maintainer coverage remains a disclosed continuity risk, but the documented controls still reduce that risk. - -## Work Scheduling - -Prioritize by user value, risk, dependency, and reversibility. Threat modeling, evaluations, teaching, contribution review, release provenance, governance, proof presentation, launch preparation, and interoperability may proceed in parallel when their sources and authority are ready. - -Public actions still require their own safety, consent, target, community rules, and correction checks. Completing a repository artifact never proves that an external audience adopted or recommended the skill. - -## Evidence Records - -Use [Program Evidence](PROGRAM-EVIDENCE.md) for volunteer trials, case studies, launch observations, phase reviews, and accepted risks. Keep founding, recruited, unsolicited, and operational evidence distinct, and keep generated snapshots separate from reviewed meaning. - -Every active workstream needs a named owner. Every completion or claim decision needs a reviewer, evidence, status, date, limitations, downstream action, and review trigger. - -## Release Strategy - -Do not assign one version per phase automatically. Use semantic versioning according to behavior impact: - -- Use a patch release for corrections, refreshed volatile guidance, documentation fixes, or packaging fixes that do not intentionally change the runtime contract. -- Use a minor release for a backward-compatible workflow, reference, evaluation behavior, or optional interoperability capability. -- Use a major release for an activation, required-input, safety, workflow, or output-contract break. -- Use no release for outreach or evidence collection when the installable runtime is unchanged. - -Version `1.1.0` establishes foundations shared across the phases: executable evaluation coverage, adversarial cases, threat modeling, teaching guidance, portal handoff, governance rules, checksums, and release provenance. - -## Current State - -All seven roadmap workstreams are complete for the scope maintained in this repository and documented in [Roadmap Delivery](ROADMAP-DELIVERY.md). Phase 0 has founding product evidence from the real multi-organization portfolio. Later external adoption, attention, retention, recommendation, contribution, and maintainer observations remain open evidence opportunities rather than delivery blockers. - -This status does not claim that outside adoption, a coordinated external launch, portal recommendation, derivative work, or succession resilience has occurred. The repository records those unknowns explicitly and will update them when evidence appears. - -## Review Triggers - -Review this roadmap after a completion decision, serious security report, evaluation regression, material host change, maintainer change, conflict in a recommendation, contradictory external evidence, or evidence that a workstream objective no longer fits users. - -Preserve prior issue and decision history when the roadmap changes. Update the phase issue, this file, and any affected program, evidence, governance, or architecture decision in the same change. [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md) records why external adoption evidence now limits claims instead of blocking repository delivery. +Preserve issue, decision, and release history when direction changes. Use a new decision record when the selection model or evidence boundary changes materially; use an ordinary roadmap edit when evidence changes priority without changing the durable model. Git history and the founding delivery record provide recovery if a revision loses necessary context. diff --git a/docs/TESTING.md b/docs/TESTING.md index 937e372..f193f96 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. 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. +The validator checks metadata, direct links, required maintenance files, versions, manifests, release notes, workflow mode, Markdown structure, runtime path leakage, placeholders, installation-version synchronization, the living roadmap and historical delivery boundary, 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 c495dbf..787d8f4 100644 --- a/docs/VERSION.md +++ b/docs/VERSION.md @@ -1,6 +1,6 @@ # Version -Current version: `1.10.0`. +Current version: `1.11.0`. ## Source of Truth @@ -20,4 +20,4 @@ The tag, `package.json`, both plugin manifests, the `CHANGELOG.md` heading, and Host paths and preview features may change between skill releases. Their checked date belongs in `skills/coordinate-github-repositories/references/agent-capability-adapters.md`. -Roadmap phases do not determine versions. Outreach and evidence collection may need no release, while a phase that changes the backward-compatible runtime contract may justify a minor release. +Roadmap priorities and founding phase numbers do not determine versions. Outreach and evidence collection may need no release, while a backward-compatible runtime or maintainer workflow may justify a minor release. diff --git a/docs/decisions/0006-maintain-a-living-outcome-led-roadmap.md b/docs/decisions/0006-maintain-a-living-outcome-led-roadmap.md new file mode 100644 index 0000000..7d79004 --- /dev/null +++ b/docs/decisions/0006-maintain-a-living-outcome-led-roadmap.md @@ -0,0 +1,65 @@ +# Program Decision 0006: Maintain a Living Outcome-Led Roadmap + +Decision type: Program governance. + +## Status + +Accepted for implementation on 2026-07-19 through [issue #46](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/46) and the maintainer's request for v1.11.0. + +## Context + +The original roadmap implemented issue #6 as a finite seven-phase program. The repository completed those deliverables in v1.2.0, preserved them in `docs/ROADMAP-DELIVERY.md`, closed issues #7 through #13, and continued to deliver v1.3.0 through v1.10.0 through separately justified issues. + +`docs/ROADMAP.md` still described the completed phases as the roadmap, `README.md` still sent maintainers there for program direction, and validation required phrases tied to that completed program. The record remained accurate history but no longer told maintainers which outcomes guide current work, how candidates become accepted tasks, or where active delivery state belongs. + +The repository instructions require GitHub issue and pull request state to remain in GitHub instead of becoming a second backlog in documentation. Program Decision 0003 also requires delivery and outcome evidence to remain separate so missing adoption evidence limits claims without freezing unrelated authorized work. + +## Options + +- Keep the completed phase roadmap as the current direction. +- Delete the roadmap and rely only on issues. +- Maintain a detailed task and status table in Markdown. +- Preserve the completed program as history and maintain a living roadmap of current outcomes, selection rules, evidence boundaries, and review triggers while GitHub owns delivery state. + +## Decision + +Use the fourth option. Maintain `docs/ROADMAP.md` as the current outcome and work-selection contract after the founding program. + +Keep concrete work, ownership, status, and completion state in GitHub issues and pull requests. Link the roadmap to the canonical open-issue view instead of copying issue state into a Markdown task table. + +Keep `docs/ROADMAP-DELIVERY.md`, issue #6, and phase issues #7 through #13 as historical delivery evidence. Do not present the completed phases as the active backlog or erase their evidence and claim boundaries. + +Rank current outcomes while allowing an urgent quality risk to move first. Accept work only when its expected benefit, evidence, target, authority, privacy boundary, security impact, dependencies, completion evidence, and owner are clear enough for the proposed change. + +Treat feedback and outcome evidence as candidate inputs rather than automatic tasks. Preserve Program Decision 0003: missing external adoption limits claims, a red affected quality control blocks release or public action, and neither evidence class substitutes for the other. + +Record a review date and owner in the roadmap. Reassess the model when priorities lose evidence, accepted issues drift from the stated outcomes, quality or host conditions change materially, or the process adds administration without improving decisions. + +## Rationale + +The selected model keeps durable direction visible without duplicating a fast-changing backlog. It preserves the evidence and public history of the founding program while allowing later work to be justified by current outcomes and explicit issues. + +An issue-only model would hide the stable selection rules that maintainers need before creating work. A Markdown task table would duplicate GitHub state and become stale through ordinary issue changes. + +## Consequences + +Readers can distinguish current direction, active delivery, historical delivery, and outcome evidence. Maintainers can change issue state without editing the roadmap and can change priorities without rewriting completed phase history. + +The roadmap still requires judgment and periodic review. Its priority order may become stale, but the review date, triggers, issue-backed state, and decision history make that drift visible and reversible. + +The change adds a backward-compatible maintainer workflow and deterministic validation. It does not change runtime activation, user-facing coordination behavior, safety or permission boundaries, evaluation fixtures, package format, or conversation-only usefulness. + +## Links + +- [Issue #46](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/46) +- [Roadmap](../ROADMAP.md) +- [Founding Roadmap Delivery Record](../ROADMAP-DELIVERY.md) +- [Program Evidence](../PROGRAM-EVIDENCE.md) +- [Feedback From Humans and Agents](../FEEDBACK.md) +- [Program Decision 0001](0001-evidence-gated-roadmap.md) +- [Program Decision 0003](0003-separate-delivery-from-outcome-evidence.md) +- [Governance Decision 0005](0005-use-one-typed-decision-registry.md) + +## Review Triggers + +Review this decision when GitHub no longer serves as the delivery system, the roadmap repeatedly fails to guide issue selection, maintainers need a different owner or review cadence, outcome priorities become an unmaintainable taxonomy, historical and current state become confused again, or new evidence requires a different relationship between delivery and outcomes. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index c97af33..9325e86 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -71,6 +71,7 @@ The index is the discovery surface for every record. Validation discovers record - [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. +- [Program Decision 0006](0006-maintain-a-living-outcome-led-roadmap.md) replaces the completed phase list as current direction with a living outcome-led roadmap while GitHub retains delivery state. ## Maintainer Workflow @@ -86,7 +87,9 @@ The index is the discovery surface for every record. Validation discovers record 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. +Version 1.11.0 adds Program Decision 0006 through the same registry without changing the taxonomy or historical records. + +Separate directories or per-type sequences would add navigation and collision rules without improving the current six-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 diff --git a/docs/releases/v1.11.0.md b/docs/releases/v1.11.0.md new file mode 100644 index 0000000..82b0366 --- /dev/null +++ b/docs/releases/v1.11.0.md @@ -0,0 +1,40 @@ +# Coordinate GitHub Repositories v1.11.0 + +Version `1.11.0` completes [issue #46](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/46) with a living roadmap, a canonical boundary for delivery state, and validation that detects a return to the completed founding program as current direction. + +## Living Product Direction + +- Rank transferability through real use, value preservation and reuse, trust across hosts and releases, and maintenance continuity as the current outcomes. +- Select work through expected user benefit, evidence quality, affected risk, frequency, reach, urgency, reversibility, maintenance, dependency readiness, and ownership. +- Keep missing external adoption as a claim limit rather than a blocker for unrelated authorized work. +- Review direction after material evidence, quality, host, maintainer, or process changes and retain a dated owner and recovery path. + +## Canonical State and Preserved History + +- Keep active work, ownership, status, and completion state in GitHub issues and pull requests. +- Link the roadmap to the canonical open-issue view instead of copying an issue table into documentation. +- Preserve issue #6, phase issues #7 through #13, and `docs/ROADMAP-DELIVERY.md` as the founding program's delivery history. +- Keep feedback and program evidence as candidate inputs that require maintainer acceptance before they become implementation work. + +## Decision and Validation + +- Add [Program Decision 0006](../decisions/0006-maintain-a-living-outcome-led-roadmap.md) for the transition, alternatives, consequences, evidence boundary, review triggers, and relationship to Program Decision 0003. +- Extend the typed decision index without renaming or rewriting historical records. +- Validate living-roadmap sections, review-date format, the canonical open-issue link, historical phase separation, and the evidence-to-priority boundary. +- Separate roadmap validation from the existing low-friction feedback contract. + +## Compatibility + +This minor release adds a backward-compatible maintainer planning and validation workflow. The installed runtime tree remains unchanged from v1.10.0, including activation, the ten-stage user workflow, output behavior, safety and permission boundaries, focused references, fixtures, package formats, and conversation-only fallback. + +## Verification + +Run the final release gate with the intended tag: + +```bash +npm run release:preflight -- v1.11.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.11.0`. diff --git a/package.json b/package.json index f63cfbc..bc778c8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "coordinate-github-repositories-skill", - "version": "1.10.0", + "version": "1.11.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 83a72a6..7377f45 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.10.0", + "version": "1.11.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 0793059..460e688 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.10.0", + "version": "1.11.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 04fc3fa..d4b815b 100644 --- a/scripts/validate-skill.mjs +++ b/scripts/validate-skill.mjs @@ -651,23 +651,56 @@ function validateAgentSurfaceContract() { } } -function validateFeedbackContract() { - // @constraints Program Decision 0003 keeps missing external adoption evidence from freezing safe repository delivery. +/** + * Validates current roadmap ownership without turning historical phase state into a second backlog. + * @returns {void} + * @sideEffects Reads roadmap and evidence files and appends contract violations. + * @why Issue #46 and Program Decision 0006 replace the completed phase list as current direction while preserving its delivery record. + * @since 1.11.0 + */ +function validateRoadmapContract() { const roadmap = readText("docs/ROADMAP.md"); const delivery = readText("docs/ROADMAP-DELIVERY.md"); - const feedback = readText("docs/FEEDBACK.md"); - const skill = readText("skills/coordinate-github-repositories/SKILL.md"); - const reference = readText("skills/coordinate-github-repositories/references/feedback-and-improvement.md"); - const form = readText(".github/ISSUE_TEMPLATE/skill_run_feedback.yml"); - - for (const expected of ["Missing external adoption evidence limits claims", "They are not hard dependencies", "Program Decision 0003"]) { + const evidence = readText("docs/PROGRAM-EVIDENCE.md"); + + for (const expected of [ + "GitHub issues and pull requests are the canonical delivery state", + "## Current Outcome Priorities", + "## Work Selection", + "## Evidence and Claim Boundary", + "## Historical Program", + "## Review and Recovery", + "An observation is not automatically an accepted task", + "Missing external adoption evidence limits claims", + "Program Decision 0006", + "issues?q=is%3Aissue%20state%3Aopen" + ]) { if (!roadmap.includes(expected)) { - fail(`docs/ROADMAP.md is missing the evidence and claim boundary: ${expected}.`); + fail(`docs/ROADMAP.md is missing the living roadmap contract: ${expected}.`); } } - if (!delivery.includes("roadmap issues #7 through #13") || !delivery.includes("are not claimed")) { - fail("docs/ROADMAP-DELIVERY.md must separate delivered repository work from unproven external outcomes."); + + if (!/^Last reviewed: `\d{4}-\d{2}-\d{2}`\.$/m.test(roadmap)) { + fail("docs/ROADMAP.md must record its review date in YYYY-MM-DD form."); + } + if (roadmap.includes("All seven roadmap workstreams are complete") || /^### Phase \d+:/m.test(roadmap)) { + fail("docs/ROADMAP.md must not present the completed founding phases as current work."); + } + if (!delivery.startsWith("# Founding Roadmap Delivery Record") || !delivery.includes("roadmap issues #7 through #13") || !delivery.includes("are not claimed")) { + fail("docs/ROADMAP-DELIVERY.md must preserve the completed founding program and its unproven external outcomes."); + } + for (const expected of ["inform product claims and roadmap priorities", "does not become accepted work automatically"]) { + if (!evidence.includes(expected)) { + fail(`docs/PROGRAM-EVIDENCE.md is missing the evidence-to-roadmap boundary: ${expected}.`); + } } +} + +function validateFeedbackContract() { + const feedback = readText("docs/FEEDBACK.md"); + const skill = readText("skills/coordinate-github-repositories/SKILL.md"); + const reference = readText("skills/coordinate-github-repositories/references/feedback-and-improvement.md"); + const form = readText(".github/ISSUE_TEMPLATE/skill_run_feedback.yml"); // @constraints Feedback intake stays useful when a person knows only the observation; enrichment is agent or maintainer work. const requiredFields = form.match(/required:\s*true/g) ?? []; @@ -960,6 +993,7 @@ validateInstallationContract(); validateWorkflowMode(); validateRepositoryContract(); validateAgentSurfaceContract(); +validateRoadmapContract(); validateFeedbackContract(); validateDecisionRecords(); validateWritingContract();