traverse-framework · enricopiovesan · Jul 3, 2026 · Jul 3, 2026
@@ -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

@@ -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
-
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->
@@ -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.

@@ -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)

@@ -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