From 45be3e809dc59b70ac4c25d8666ddd9e813a4781 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 3 Jul 2026 10:43:37 -0600 Subject: [PATCH] Adopt shared governance repo; draft spec 051 (registry extraction) --- .specify/memory/constitution.md | 2 + CLAUDE.md | 39 +++--- CONTRIBUTING.md | 11 +- docs/antipatterns.md | 174 +------------------------- docs/compatibility-policy.md | 75 +---------- docs/exception-process.md | 43 +------ docs/quality-standards.md | 102 +-------------- specs/051-registry-extraction/spec.md | 45 +++++++ 8 files changed, 81 insertions(+), 410 deletions(-) create mode 100644 specs/051-registry-extraction/spec.md diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 328ec052..2f05010d 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,5 +1,7 @@ # Traverse Constitution +> **Governance note**: this repo's constitution is now also mirrored as the shared, org-wide constitution in [`traverse-framework/.github`](https://github.com/traverse-framework/.github) (governance version 1.0.0), so other repos (`registry`, etc.) can adopt the same principles without duplicating them independently. This copy remains authoritative for this repo and satisfies this repo's own CI content checks — update both together if you amend a shared principle. + ## Core Principles ### I. Capability-First Boundaries diff --git a/CLAUDE.md b/CLAUDE.md index 003d981f..cb65db2b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,12 @@ # Traverse Development Guidelines -Auto-generated. Last updated: 2026-04-07 +Auto-generated. Last updated: 2026-07-03 + +## Governance + +This repo's constitution, NFRs, quality standards, antipatterns, compatibility policy, exception process, and CLA are **not** duplicated here — they live in [`traverse-framework/.github`](https://github.com/traverse-framework/.github), pinned at **governance version 1.0.0**. Read that repo's `constitution.md` before any implementation work. + +Repo-specific product scope stays here: see `specs/001-foundation-v0-1/spec.md` for this repo's v0.1 scope, and `specs/051-registry-extraction/spec.md` for the in-progress registry extraction. ## Active Technologies @@ -16,14 +22,14 @@ Auto-generated. Last updated: 2026-04-07 crates/ traverse-runtime/ # Core execution engine traverse-contracts/ # Contract definitions and validation - traverse-registry/ # Capability and event registries + traverse-registry/ # Capability and event registries (moving to traverse-framework/registry — see spec 051) traverse-cli/ # Command-line interface traverse-mcp/ # Model Context Protocol (stub) specs/ # Versioned, immutable governing specs contracts/ # Capability and event contracts -docs/ # ADRs, quality standards, policies -.specify/ # Speckit: constitution, scripts, templates -scripts/ci/ # Deterministic spec-alignment gate +docs/ # Repo-specific docs (shared governance docs live in traverse-framework/.github) +.specify/ # Speckit: scripts, templates (constitution lives in traverse-framework/.github) +scripts/ci/ # Deterministic spec-alignment gate (vendored, pinned copy of traverse-framework/.github's version) ``` ## Commands @@ -41,14 +47,16 @@ bash scripts/ci/spec_alignment_check.sh # Spec-alignment gate - 100% test coverage for core business and runtime logic - Deterministic: same inputs must produce same outputs -## Governance +## Development Workflow -Read `.specify/memory/constitution.md` before any implementation work. Key rules: +1. Clarify capability boundary +2. Define or amend governing spec +3. Define contracts +4. Write tests +5. Implement smallest change satisfying spec + contract +6. Verify CI gate passes -1. Every feature starts with a spec in `specs/` — no spec, no merge -2. Contracts are source of truth — code conforms to contracts, not vice versa -3. Spec-alignment CI gate blocks PRs that drift from approved specs (`specs/governance/approved-specs.json`) -4. All work must be tracked: GitHub issue + Project 1 item + PR +All work must be tracked: GitHub issue + Project 1 item + PR. ## Approved Specs @@ -64,14 +72,5 @@ Read `.specify/memory/constitution.md` before any implementation work. Key rules | 008 | expedition-example-domain | | 009 | expedition-example-artifacts | -## Development Workflow - -1. Clarify capability boundary -2. Define or amend governing spec -3. Define contracts -4. Write tests -5. Implement smallest change satisfying spec + contract -6. Verify CI gate passes - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af731b0a..79a902a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,12 +6,8 @@ Thanks for contributing to Traverse. Please read: -- [README.md](/Users/piovese/Documents/cogolo/README.md) -- [.specify/memory/constitution.md](/Users/piovese/Documents/cogolo/.specify/memory/constitution.md) -- [docs/quality-standards.md](/Users/piovese/Documents/cogolo/docs/quality-standards.md) -- [docs/antipatterns.md](/Users/piovese/Documents/cogolo/docs/antipatterns.md) -- [docs/compatibility-policy.md](/Users/piovese/Documents/cogolo/docs/compatibility-policy.md) -- [docs/exception-process.md](/Users/piovese/Documents/cogolo/docs/exception-process.md) +- [README.md](README.md) +- [traverse-framework/.github](https://github.com/traverse-framework/.github) — constitution, quality standards, antipatterns, compatibility policy, exception process, CLA (this repo has adopted governance version 1.0.0) ## Core Rules @@ -20,13 +16,14 @@ Please read: - Core runtime and business logic require 100% automated coverage. - Material architecture changes require an ADR. - Portability exceptions must be explicit and reviewed. +- All contributions are governed by the CLA at `traverse-framework/.github/CLA.md`. ## Workflow 1. Start from the governing approved spec. 2. Confirm whether an issue already exists. 3. Open or link the work item in the project board: - [GitHub Project](https://github.com/orgs/traverse-framework/projects) + [GitHub Project](https://github.com/orgs/traverse-framework/projects/1) 4. If needed, add or update an ADR before implementation. 5. Implement with tests and validation evidence. 6. Make sure the change passes the required validation flow. diff --git a/docs/antipatterns.md b/docs/antipatterns.md index efc3d81e..78a69f45 100644 --- a/docs/antipatterns.md +++ b/docs/antipatterns.md @@ -1,176 +1,8 @@ -# Traverse Development Antipatterns +# Development Antipatterns -This guide collects the main repo-specific shortcuts and habits that make Traverse harder to govern, harder to merge, or harder to trust. +The shared antipatterns guide lives in [`traverse-framework/.github`](https://github.com/traverse-framework/.github)'s `docs/antipatterns.md`. This repo has adopted **governance version 1.0.0**. -These are not generic style preferences. They are the patterns most likely to create spec drift, CI failures, hidden coupling, or confusing contributor experience. - -## 1. Writing Code Before The Governing Slice Is Clear - -Antipattern: - -- implementing behavior first and hoping the spec or ticket can be updated later - -Why it is a problem: - -- Traverse is spec-governed -- CI checks expect the PR body and changed files to align with approved spec ids -- post-hoc governance almost always produces drift or misleading PR metadata - -Do instead: - -- start from the approved governing spec -- if the slice truly has no missing governance work, label it `no-spec-needed` -- keep the PR `## Governing Spec` section narrow and accurate - -## 2. Declaring Stale Or Extra Specs In A PR Body - -Antipattern: - -- copying an old PR body and leaving unrelated spec ids in place - -Why it is a problem: - -- `spec-alignment` validates the declared specs -- stale declarations create false governance claims and can fail CI even when the code is fine - -Do instead: - -- declare only the approved spec ids actually needed for the files you changed -- update the PR body after rebases or scope changes - -## 3. Using `in-progress` As A Placeholder - -Antipattern: - -- marking a ticket `in-progress` just because it looks like the next good candidate - -Why it is a problem: - -- the Project 1 status is the repo’s actionability signal -- fake `in-progress` state creates board drift and hides what is truly ready - -Do instead: - -- keep a ticket `Ready` until someone is actively executing it -- add a blocker note when something is blocked instead of leaving the state ambiguous - -## 4. Leaving Hidden Placeholder Paths In Docs - -Antipattern: - -- letting docs imply a path is supported when it is still partial, inert, or only test scaffolding - -Why it is a problem: - -- developers and agents will follow the wrong path first -- this wastes time and creates incorrect assumptions about the supported surface - -Do instead: - -- point to the supported path explicitly -- make unsupported commands or bootstrap ideas fail loudly -- distinguish normative runtime behavior from fixtures and examples - -## 5. Depending On Internal Knowledge Instead Of Public Docs - -Antipattern: - -- assuming contributors will infer the right command, file, or release surface from repo familiarity - -Why it is a problem: - -- Traverse is trying to be consumable by both humans and coding agents -- “just know where to look” is not a stable interface - -Do instead: - -- add docs for public entry paths -- link new docs from the README, quickstart, tutorial index, or getting-started flow when they matter to first-time users - -## 6. Using `unwrap`, `panic!`, Or TODO-Driven Control Flow - -Antipattern: - -- relying on crashes, unchecked assumptions, or TODO comments in production code - -Why it is a problem: - -- Traverse expects predictable failure behavior and actionable error states -- panic-driven code undermines runtime trust and makes automation harder to reason about - -Do instead: - -- return explicit errors -- document the failure mode -- capture follow-up work as a real issue instead of a lingering TODO comment - -## 7. Sneaking In Demo-Only Hacks - -Antipattern: - -- adding one-off behavior that only works for an example but lives in foundation code - -Why it is a problem: - -- foundation crates are supposed to stay portable and governed -- demo shortcuts become accidental product behavior if they survive one merge - -Do instead: - -- keep example-specific logic in examples, fixtures, or dedicated docs -- keep core runtime and registry behavior generic and explainable - -## 8. Treating Tests As Optional Around Core Runtime Logic - -Antipattern: - -- landing core runtime, registry, or contract logic without exhaustive automated validation - -Why it is a problem: - -- Traverse keeps `100%` coverage expectations for core business and runtime logic -- missing tests usually mean missing determinism guarantees too - -Do instead: - -- add or update the tests in the same slice -- use the repository checks and coverage gate as design feedback, not as an afterthought - -## 9. Opening A PR Without The Full Traceability Chain - -Antipattern: - -- code change without a durable issue, Project 1 item, and PR linkage - -Why it is a problem: - -- the repo’s governance model depends on issue + project item + PR traceability -- missing links make later review, release prep, and audit work harder - -Do instead: - -- keep every meaningful slice tied to: - - a GitHub issue - - a Project 1 item - - a pull request - -## 10. Letting “Behind Main” Sit Unresolved - -Antipattern: - -- waiting too long to restack a green PR after another docs or onboarding PR merges - -Why it is a problem: - -- GitHub branch protection blocks merges on stale heads -- queue latency grows fast when docs slices all touch the same top-level files - -Do instead: - -- rebase promptly when the PR becomes `BEHIND` -- rerun the checks on the updated head instead of trying to merge around the branch protection - -## Related Docs +## Related Docs (repo-specific) - [docs/quality-standards.md](quality-standards.md) - [docs/project-management.md](project-management.md) diff --git a/docs/compatibility-policy.md b/docs/compatibility-policy.md index df30d3eb..02945db5 100644 --- a/docs/compatibility-policy.md +++ b/docs/compatibility-policy.md @@ -1,64 +1,8 @@ # Compatibility Policy -This document defines compatibility expectations for versioned Traverse artifacts. +The shared, org-wide compatibility policy lives in [`traverse-framework/.github`](https://github.com/traverse-framework/.github)'s `docs/compatibility-policy.md`. This repo has adopted **governance version 1.0.0**. -## Governed Versioned Surfaces - -The following surfaces are versioned and compatibility-sensitive: - -- feature specs -- capability contracts -- event contracts -- runtime surface -- MCP surface -- workflow definitions where versioned behavior is exposed - -## General Rules - -- Backward-compatible changes should use minor or patch version increments as appropriate. -- Breaking changes must use major version increments. -- Reusing the same identity and version with changed meaning or structure is forbidden. -- Compatibility expectations must be explicit in the artifact or related documentation. - -## Capability Contracts - -Backward-compatible examples: - -- additive metadata that does not change required behavior -- new optional fields -- clarifications that do not alter contract meaning - -Breaking examples: - -- removing required fields -- changing input or output meaning incompatibly -- changing required events, permissions, or constraints incompatibly - -## Event Contracts - -Backward-compatible examples: - -- adding optional metadata -- documentation-only clarifications - -Breaking examples: - -- incompatible schema changes -- changed semantic meaning -- incompatible publication or subscription rules - -## Runtime and MCP Surface - -Backward-compatible examples: - -- additive endpoints, commands, or fields -- optional trace/evidence enrichments - -Breaking examples: - -- removed or renamed required fields -- incompatible invocation behavior -- changed failure semantics without version change +## Repo-Specific Compatibility Statements The boundary between governed core runtime responsibilities and optional adapters is documented in: @@ -71,18 +15,3 @@ The release-facing downstream compatibility statement for the current `youaskm3` The current Traverse release notes are: - `docs/releases/v0.7.0.md` - -## Specs - -Approved specs are immutable once they govern implementation. - -If meaning changes materially, create a new version or successor spec rather than mutating the approved one in place. - -## Validation Expectations - -Changes to versioned surfaces should be validated by: - -- schema or structure validation -- compatibility checks -- tests covering old and new expected behavior where relevant -- CI merge gates diff --git a/docs/exception-process.md b/docs/exception-process.md index 2436feae..17edb1b4 100644 --- a/docs/exception-process.md +++ b/docs/exception-process.md @@ -1,44 +1,5 @@ # Exception Process -This document defines how Traverse handles exceptions to its normal engineering and governance rules. +The shared, org-wide exception process lives in [`traverse-framework/.github`](https://github.com/traverse-framework/.github)'s `docs/exception-process.md`. This repo has adopted **governance version 1.0.0**. -## Purpose - -Exceptions exist to make unusual cases explicit, reviewable, and temporary where possible. - -An exception is not silent permission to ignore a rule. - -## Exceptions Requiring Review - -Review is required for exceptions involving: - -- portability or host coupling -- unsafe or privileged code paths -- spec-alignment or merge-gating deviations -- reduced coverage for core logic -- compatibility rule exceptions -- bypass of normal contract, policy, constraint, or trace handling - -## Required Exception Content - -Every exception should document: - -- title -- affected rule -- reason -- scope -- owner -- risk -- mitigation -- review date or expiry expectation - -## Review Expectations - -- Exceptions should be approved before merge. -- Exceptions should be narrow in scope. -- Exceptions should be revisited when their review date arrives. -- Expired or obsolete exceptions should be removed. - -## Default Rule - -If a change requires an exception and no approved exception exists, the change should not merge. +Exceptions for this repo are reviewed and tracked the same way as any other repo under `traverse-framework` — see that document for required content and review expectations. diff --git a/docs/quality-standards.md b/docs/quality-standards.md index 3201e748..94406f15 100644 --- a/docs/quality-standards.md +++ b/docs/quality-standards.md @@ -1,71 +1,16 @@ # Quality Standards -This document defines the operational quality standards for Traverse. +The shared, org-wide quality standards live in [`traverse-framework/.github`](https://github.com/traverse-framework/.github)'s `docs/quality-standards.md`. This repo has adopted **governance version 1.0.0**. -These standards work together with the constitution and feature specs. If there is a conflict, the constitution and approved governing spec take precedence. +## What's Repo-Specific Here -## Core Rule - -Code is not considered mergeable unless it is: - -- aligned with the approved governing spec -- aligned with capability, event, and workflow contracts -- validated by the required automated checks -- maintainable at production quality - -## Engineering Standards - -All in-scope code must meet these standards: - -- Clear module boundaries -- Clear ownership of responsibilities -- Deterministic behavior where practical -- Actionable error handling -- Structured runtime and validation evidence -- Testability by design -- No hidden contract bypasses -- No demo-only hacks in foundation code - -## Required Validation Gates - -The default validation flow should include: - -- spec-alignment validation -- contract validation -- formatting -- linting -- tests -- coverage checks for core logic -- dependency/security checks -- required work-traceability through issue, project item, and pull request linkage where applicable -- ticket-level definition of done and validation instructions for meaningful work - -Spec-alignment gate implementation: +Spec-alignment gate implementation is vendored locally (CI needs it in-repo to run): - approved spec registry: `specs/governance/approved-specs.json` - workflow job: `spec-alignment` - script: `scripts/ci/spec_alignment_check.sh` -## Coverage Standard - -Required: - -- `100%` automated coverage for core business and runtime logic - -Core logic includes: - -- contract validation -- semver enforcement -- registry behavior -- discovery logic -- ambiguity handling -- workflow traversal -- runtime state machine -- trace generation - -Coverage outside core logic should remain appropriate for risk and maintainability. - -Coverage gate implementation: +Coverage gate implementation, specific to this repo's crates: - workflow job: `coverage-gate` - script: `scripts/ci/coverage_gate.sh` @@ -73,38 +18,6 @@ Coverage gate implementation: The coverage gate is merge-safe even before core logic exists. It passes when no protected crates are configured, and becomes enforcing as soon as core crates are added to `ci/coverage-targets.txt`. -## Reproducibility Standard - -Build and validation flows should be reproducible from pinned inputs: - -- pinned toolchain -- pinned dependencies -- documented commands -- CI using the same default validation flow expected locally - -## Documentation Standard - -Public modules and runtime surfaces should document: - -- purpose -- inputs and outputs -- major constraints -- failure modes -- examples when useful - -## Merge Blocking Conditions - -A change must not merge when any of the following are true: - -- spec drift is detected -- contract drift is detected -- tests fail -- required validation gates fail -- required coverage for core logic fails -- an unreviewed portability exception exists -- a material architecture change lacks a required ADR -- the change lacks the required traceability artifacts under the project-management policy - ## Nightly CI Gate In addition to PR-gated checks, a nightly scheduled CI job runs the full golden-path acceptance suite independently of any PR activity. @@ -123,10 +36,3 @@ In addition to PR-gated checks, a nightly scheduled CI job runs the full golden- **Manual trigger**: the workflow supports `workflow_dispatch` — trigger it from the GitHub Actions tab to validate a fix before the next scheduled run. **Notification**: GitHub Actions sends an email to the repository owner on failure by default. No additional configuration required. - -## Problem Handling Rule - -When active work reveals a problem: - -- must-fix issues must be resolved in the current PR when they are required for correctness, mergeability, governance, or stated acceptance criteria -- nice-to-have improvements and non-blocking follow-ups must be captured as `future` tickets instead of being left implicit diff --git a/specs/051-registry-extraction/spec.md b/specs/051-registry-extraction/spec.md new file mode 100644 index 00000000..37c92f1d --- /dev/null +++ b/specs/051-registry-extraction/spec.md @@ -0,0 +1,45 @@ +# Feature Specification: Registry Extraction + +**Feature Branch**: `051-registry-extraction` +**Created**: 2026-07-03 +**Status**: Draft +**Input**: Brainstorm session establishing `traverse-framework/registry` as a dedicated repo for the public capability registry, extracted from this repo's `crates/traverse-registry`. Full narrative record: `traverse-framework/registry`'s `docs/decision-log.md`. Companion foundation spec: `traverse-framework/registry`'s `specs/001-registry-foundation/spec.md`. + +## Purpose + +This spec is the decision record required by this repo's constitution ("no unreviewed architectural change without a decision record when the change affects... registry behavior") for moving `crates/traverse-registry` — and the specs that govern it — out of this repo into `traverse-framework/registry`. + +This spec does not redesign registry behavior. It documents what moves, what stays, what becomes an external dependency, and how governance is adopted going forward. Implementation (the actual crate/spec move) is tracked separately (see `## Follow-up Work`) and is blocked on this spec being approved. + +## What Moves + +- `crates/traverse-registry/` (the entire crate) moves to `traverse-framework/registry`. +- The specs that currently govern it move with it, adopted as that repo's own governing specs: `005-capability-registry`, `007-workflow-registry-traversal`, `011-event-registry`, `034-programmatic-registration`, `035-multi-agent-isolation`, `036-event-subscription-replay`, `037-semver-range-resolution`, `039-connector-plugin-architecture`, `041-workflow-composition-api`, `043-module-dependency-management`. +- Once the move lands, this repo's `specs/governance/approved-specs.json` entries for those spec ids are updated: their `governs` paths pointing at `crates/traverse-registry/` are removed (the path no longer exists in this repo), since those specs' substance is now governed by their re-adopted counterparts in `traverse-framework/registry`. + +## What Stays + +- `crates/traverse-contracts/` stays in this repo. It is the schema every consumer — this repo's runtime/CLI/MCP, and `traverse-framework/registry` — depends on symmetrically. Moving it would make this repo external to its own capability schema, which is backwards given the runtime is what actually executes against that schema. +- `crates/traverse-runtime/`, `crates/traverse-cli/`, `crates/traverse-mcp/` stay. `traverse-cli capability publish` (the PR-automation command described in `traverse-framework/registry`'s spec 001, User Story 1) is implemented here, not in the registry repo, since the CLI is this repo's control surface. + +## Dependency Change + +Once the extraction lands, `Cargo.toml` depends on `traverse-registry` as an external crate (crates.io or git dependency, consistent with this repo's existing spec `048-semver-publishing-pipeline`, which already treats `traverse-registry` as an independently-versioned, separately-published crate in the workspace's publish order: `traverse-contracts` → `traverse-registry` → `traverse-runtime` → `traverse-mcp` → `traverse-cli` → `traverse-expedition-wasm`). This spec does not change that publish order — it changes where `traverse-registry`'s source of truth lives. + +## Governance Adoption + +This repo adopts shared governance from `traverse-framework/.github` at version 1.0.0. Once this spec is approved: + +- `CLAUDE.md`, `CONTRIBUTING.md`, `docs/quality-standards.md`, `docs/antipatterns.md`, `docs/compatibility-policy.md`, `docs/exception-process.md` are replaced with thin pointers to `traverse-framework/.github` rather than kept as independently-maintained local copies. +- `scripts/ci/spec_alignment_check.sh` continues to be vendored locally (CI needs it in-repo to run), but is treated as a pinned copy of the canonical version in `traverse-framework/.github`, not an independently-evolved fork. + +## Follow-up Work (tracked separately, blocked on this spec's approval) + +- Extract `crates/traverse-registry` source and its governing specs into `traverse-framework/registry` (tracked as a `needs-spec` ticket in that repo — see its ticket "Extract `traverse-registry` crate + content from `Traverse` into this repo"). +- Update this repo's `Cargo.toml` to depend on the externally-published crate. +- Update `specs/governance/approved-specs.json` to remove the now-inapplicable `crates/traverse-registry/` `governs` entries from specs 005/007/011/034-037/039/041/043. +- Implement `traverse-cli capability publish` (PR-automation for publishing to the registry repo). + +## Compatibility Impact + +None to public runtime behavior — this is a source-location and governance change, not a behavioral one. `traverse-registry`'s public API surface is unaffected; only its repository of record changes. Downstream consumers depending on `traverse-registry` via crates.io are unaffected, since the crate continues to be published under the same name and semver line per spec `048-semver-publishing-pipeline`.