update specify

Author: f5epcim

.specify/memory/constitution.md

@@ -1,87 +1,141 @@
-<!--
-Sync Impact Report
-Version change: 0.0.0 → 1.0.0
-Modified Principles: Principle I – Upstream-First Patching; Principle II – Worktree Hygiene; Principle III – Portable Bash Discipline; Principle IV – Transparent Automation; Principle V – Verification & Release Confidence
-Added sections: Operational Constraints; Workflow & Quality Gates
-Removed sections: None
-Templates requiring updates: .specify/templates/plan-template.md ✅ updated, .specify/templates/spec-template.md ✅ updated, .specify/templates/tasks-template.md ✅ updated
-Follow-up TODOs: None
--->
-
 # git-cross Constitution
 
+**Version**: 1.0  
+**Last Updated**: 2025-12-01
+
+## Purpose
+
+This constitutional document establishes the core principles governing the design, implementation, and evolution of `git-cross`. These principles ensure the tool remains simple, transparent, and reliable for vendoring parts of git repositories.
+
 ## Core Principles
 
-### Principle I – Upstream-First Patching
-cross exists to mix sparse directories while keeping upstream repositories the source of truth.
+### Principle I: Upstream-First Patching
+
+**git-cross SHALL maintain a direct link to upstream repositories through git worktrees.**
+
+- Vendored files originate from real git commits in upstream repositories
+- Sparse checkout enables selective vendoring of subdirectories
+- Local modifications remain traceable to upstream sources
+- Bidirectional sync (pull and push) maintains relationship with upstream
+- No duplication of git history in the consuming repository
+
+**Rationale**: Submodules force entire-repo checkouts and create gitlinks instead of real files. git-cross provides physical files while preserving the upstream connection, enabling both local edits and upstream contributions.
+
+### Principle II: Worktree Hygiene
+
+**git-cross SHALL protect worktree cleanliness and prevent data loss.**
+
+- Hidden worktrees (`.git/cross/worktrees/`) store upstream state
+- Automatic stashing before pulls preserves local modifications in worktrees
+- Commands abort on dirty state when modifications could be lost
+- Explicit confirmation required for destructive operations
+- `rsync` provides safe, predictable file synchronization
+
+**Rationale**: Developer trust depends on predictable behavior. The tool must never silently discard work or leave repositories in inconsistent states.
+
+### Principle III: Portable Bash Discipline
+
+**git-cross implementation SHALL prioritize portability and maintainability.**
+
+**Current implementation**: `just` + `fish` (complex logic delegated to fish shell scripts)
+
+**Standards**:
+- Justfile for command dispatch and workflow orchestration
+- Fish shell (≥3.0) for complex string manipulation and conditionals  
+- POSIX-compatible workflows where possible for broad compatibility
+- Clear separation between user-facing commands (Justfile) and internal helpers
+- No external dependencies beyond: `git`, `just`, `fish`, `rsync`, core utilities
+
+**Code style**:
+- Lower_snake_case for fish functions and variables
+- Inline comments for non-obvious logic (especially index calculations)
+- Helper functions (`_sync_from_crossfile`, `_resolve_context`) for modularity
+- Four-space indentation, grouped exports/constants
+
+**Rationale**: The tool must run on contributor machines (macOS, Linux) without complex installation. `just` provides excellent command-running ergonomics while `fish` handles complex data manipulation cleanly.
+
+### Principle IV: Transparent Automation
+
+**git-cross SHALL make implicit behavior explicit and observable.**
+
+- Commands document themselves via `just help` and `just --list`
+- `Crossfile` provides human-readable, reproducible configuration
+- `just replay` reconstructs vendoring from `Crossfile` alone
+- Operations log actions clearly (what's being fetched, synced, etc.)
+- Environment knobs (e.g., `CROSS_NON_INTERACTIVE`) are documented
+- `verbose` mode available for debugging
+
+**Auto-save behavior**:
+- `use` and `patch` commands automatically append to `Crossfile`
+- Idempotent: running same command twice doesn't duplicate entries
+- Crossfile structure: plain text, one command per line, comments allowed
+
+**Rationale**: "Magic" automation breeds distrust. Users should understand what the tool does, how to reproduce it, and how to debug it.
 
-- Patch operations MUST preserve remote alias metadata and branch naming derived from `alias/branch/path`, avoiding rewrites that break contribution flows.
-- All git interactions inside the script MUST flow through the `_git` wrapper so logging stays verbose and behaviour remains observable.
-- Crossfile definitions MUST rely on the `use` and `patch` helpers; custom fetch flows demand documented governance approval inside the feature plan.
+### Principle V: Verification & Release Confidence
 
-Rationale: Maintaining upstream-first behaviour keeps external projects healthy and ensures contributors can upstream their improvements without friction.
+**git-cross SHALL provide built-in verification mechanisms.**
 
-### Principle II – Worktree Hygiene
-Reliable worktrees keep cross trustworthy for both the root repository and every patched remote.
+**Testing strategy**:
+- Bash test scripts (`test/bash/examples/`) for realistic scenario coverage
+- Fixture repositories (`test/fixtures/remotes/`) simulate upstreams
+- `test/run-all.sh` orchestrates full test suite
+- Tests verify both happy paths and error handling
 
-- The script MUST execute with `set -euo pipefail`, guarding non-fatal lookups with `|| true` so failures are explicit.
-- Root and patch worktrees MUST be clean before cross mutates files; violations exit via `say "ERROR: …" <exit>` rather than continuing silently.
-- `./cross status --refresh` MUST be the canonical smoke check before distributing changes or releases.
+**Pre-release checks**:
+- Syntax validation: `just check-deps` verifies required tools
+- Example validation: All `examples/Crossfile-*` must execute successfully
+- Shellcheck linting (when applicable to wrapper scripts)
+- Manual verification of `README` examples
 
-Rationale: Enforcing cleanliness avoids hidden conflicts and gives contributors immediate feedback about repository health.
+**Crossfile reproducibility**:
+- `just replay` must reconstruct identical state from `Crossfile`
+- Version pinning supported via branch/tag specifications
+- Hash-based worktree naming prevents collisions
 
-### Principle III – Portable Bash Discipline
-Portability protects the script across environments and shell versions.
+**Rationale**: Contributors and users need confidence that changes don't break core workflows. Automated testing and clear verification steps enable fearless iteration.
 
-- Implementation MUST target Bash ≥4 syntax, relying on `[[` tests, `local` variables, and other portable constructs.
-- Indentation MUST remain four spaces; functions stay lower_snake_case; constants and exported variables stay grouped near the top of the script.
-- Direct `git` invocations are forbidden unless a documented exception is granted; `_git` handles instrumentation and future enhancements.
-- New external dependencies beyond the established coreutils MUST NOT be introduced without explicit governance approval and documentation.
+## Decision Framework
 
-Rationale: A disciplined style ensures the tool remains approachable, reviewable, and easy to extend.
+When evaluating new features or changes, assess against these questions:
 
-### Principle IV – Transparent Automation
-Users and automations need predictable prompts and output.
+1. **Upstream-First**: Does it maintain/improve the upstream relationship?
+2. **Hygiene**: Does it protect user data and worktree cleanliness?
+3. **Portability**: Does it run on macOS/Linux without exotic dependencies?
+4. **Transparency**: Can users understand and reproduce what it does?
+5. **Verification**: Can we test it automatically or document manual verification?
 
-- Prompts MUST use the shared `ask` helper and honour `CROSS_NON_INTERACTIVE` so non-interactive runs fail fast and predictably.
-- Human-facing output MUST route through `say` to maintain consistent messaging for both humans and AI-assisted tooling.
-- Reusable helpers MUST live alongside related utilities and be sourced explicitly to keep automation discoverable.
-- Any new environment knob (for example `CROSS_FETCH_DEPTH`) MUST ship with documentation updates in README, plan, and spec artifacts.
+**If any answer is "no"**, re-design the feature or document the trade-off explicitly.
 
-Rationale: Clear automation patterns reduce surprises and make integration with other tooling straightforward.
+## Extension Points
 
-### Principle V – Verification & Release Confidence
-Confidence comes from repeatable verification gates.
+The constitution permits controlled extensions:
 
-- `bash -n cross` and `shellcheck cross` MUST pass with zero warnings before any change is merged.
-- `./cross status --refresh` MUST succeed for the root and every patch before publishing releases or artifacts.
-- New executable variants (e.g., `cross_v<semver>.sh`) MUST mirror the primary `cross` script and be marked executable with `chmod +x`.
-- Manual test coverage remains the default; introducing automated suites demands documentation in this constitution, AGENTS, and the Sync Impact Report.
+- **Post-hooks**: `cross exec <command>` allows user-defined automation
+- **Custom commands**: Users can add recipes to their own `Justfile` that compose `cross` commands
+- **Plugin remotes**: Future support for `just <plugin> <cmd>` to delegate to vendored Justfiles
 
-Rationale: Mandatory verification keeps the project reliable even without a large automated test harness.
+Extensions MUST NOT violate core principles (e.g., post-hooks cannot bypass worktree hygiene checks).
 
-## Operational Constraints
+## Constitutional Amendments
 
-- Git 2.20 or newer is a hard requirement; the script MUST fail fast with actionable guidance when the version check fails.
-- cross MUST continue to support sparse checkout and partial fetch workflows, preserving alias-derived branch naming to avoid collisions.
-- Crossfile entries MUST keep comments short and aligned, always declaring destinations with the canonical `alias:path [local] [--branch]` syntax.
-- Constants and exported environment toggles (for example `CROSS_FETCH_DEPTH`) MUST live near the top of the script with defaults and rationale.
-- Remote metadata stored under `.git/cross/` MUST remain backwards compatible; migrations require explicit mention in the plan and the Sync Impact Report.
+This document may be amended when:
 
-## Workflow & Quality Gates
+1. A principle proves infeasible in practice
+2. Ecosystem changes render a principle obsolete (e.g., git internals evolve)
+3. Community consensus emerges on a superior approach
 
-- Implementation plans MUST document how they satisfy every principle, including the exact verification commands contributors will run.
-- Developers MUST stage outputs with git after running `./cross` so the root repository captures all generated changes.
-- Before requesting review, contributors MUST record the results of `bash -n`, `shellcheck`, and `./cross status --refresh`.
-- Preparing a release requires copying `cross` to `cross_v<semver>.sh`, updating documentation, and verifying `./cross version --current` reports the new version.
-- Feature work MUST avoid adding new dependencies; when new helpers are introduced they MUST include explicit `source` statements and rationale in the plan.
+**Amendment process**: Propose changes via issue/PR with:
+- Problem statement
+- Specific principle(s) affected
+- Alternative wording or new principle
+- Impact assessment on existing users
 
-## Governance
+**Approval**: Requires maintainer consensus + backward compatibility plan or major version bump.
 
-- This constitution supersedes conflicting project guidance; compliance is mandatory for every contribution.
-- Amendments require maintainer approval, an updated Sync Impact Report, and a refreshed audit of affected templates.
-- Versioning follows Semantic Versioning: MAJOR for principle changes, MINOR for new sections or material expansions, PATCH for clarifications.
-- Ratification or amendment MUST capture the verification commands mandated by Principle V as part of the review record.
-- Maintainers MUST block merges that omit constitution gates or introduce regressions against these principles.
+## Acknowledgments
 
-**Version**: 1.0.0 | **Ratified**: 2025-11-28 | **Last Amended**: 2025-11-28
+Principles inspired by:
+- Git's own design philosophy (simplicity, transparency, data integrity)
+- The Unix philosophy (do one thing well, compose with other tools)
+- [Spec-kit](https://github.com/github/spec-kit) governance patterns

specs/001-cross-test-strategy/plan.md

@@ -17,15 +17,15 @@ Build a repeatable automated test strategy for the `cross` CLI that:
 
 ## Technical Context
 
-**Language/Version**: Bash 5.x (POSIX-compatible) and Rust 1.75 (for the parallel harness)  
-**Primary Dependencies**: git ≥2.20, `shellcheck`, Rust crates `assert_cmd`, `predicates`, `tempfile`, `camino`  
-**Storage**: N/A (tests operate on temporary filesystem directories only)  
-**Testing**: Bash scripts executed via `test/run-default.sh` plus `cargo test` for Rust harness; both invoked from `test/run-all.sh`  
-**Target Platform**: macOS and Linux shells with GNU coreutils (matching existing cross usage)  
-**Project Type**: Single CLI project with dedicated `test/` and `examples/` directories  
-**Performance Goals**: Full suite completes within 5 minutes on contributor hardware; individual fixtures materialise in <60 seconds  
-**Constraints**: Tests MUST run in temporary directories outside the repo, avoid network calls by using local git fixtures, honour `_git` wrapper, and configure sparse checkout prior to fetch operations  
-**Scale/Scope**: Cover every Crossfile in `examples/` plus the documented `use`/`patch` flows, producing consolidated reports in `test/`
+**Implementation**: Justfile + Fish shell (December 2025 migration complete)  
+**Language/Version**: Fish 3.x for complex logic, Bash for test harness  
+**Primary Dependencies**: `git` ≥2.20, `just` (command runner), `fish` shell, `rsync`  
+**Testing**: Bash test scripts in `test/bash/examples/` exercising Crossfile-001 through 005  
+**Target Platform**: macOS and Linux with Homebrew support  
+**Project Type**: Single CLI tool with `cross` wrapper script and vendorable `Justfile`  
+**Performance Goals**: Full test suite <5 min; individual patches <60s  
+**Constraints**: Must be vendorable into user repos, support `cross` command prefix, allow post-hooks via `exec`  
+**Scale/Scope**: Cover all example Crossfiles plus core use/patch/sync/exec workflows
 
 ## Constitution Check
 

specs/001-cross-test-strategy/quickstart.md

@@ -2,10 +2,11 @@
 
 ## Prerequisites
 - Git ≥ 2.20
-- Bash ≥ 5.0 with coreutils (`mktemp`, `realpath`, `tee`)
-- `shellcheck`
-- Rust toolchain ≥ 1.75 (for Rust harness)
-- `cargo` with crates cached locally (`assert_cmd`, `predicates`, `tempfile`, `camino`)
+- `just` (command runner) - install via Homebrew or cargo
+- `fish` shell ≥ 3.0
+- `rsync`
+- Bash ≥ 3.2 (for test harness, macOS default is fine)
+- Homebrew (macOS/Linux) for PATH setup
 
 ## Environment Setup
 1. Install dependencies listed above.
@@ -16,18 +17,24 @@
 ## Running the Suite
 ```bash
 # From repository root
-test/run-all.sh
+./test/run-all.sh
 ```
+
 The script performs:
-- README default testcase in Bash (`test/bash/default-test.sh`).
-- Rust parity harness via `cargo test` under `test/rust/`.
-- Alias and patch scenario checks (`test/bash/use-alias.sh`, `test/bash/patch-workflow.sh`).
-- Constitution verification commands: `bash -n cross`, `shellcheck cross`, `./cross status --refresh`.
+- Example Crossfile tests via `test/bash/examples/crossfile-{001,002,003,005}.sh`
+- Each test clones repo, copies `Justfile` and `.env`, runs commands via `./cross`
+- Validates expected files exist and sparse checkout works correctly
+- Note: Rust harness tests are not yet implemented
+
+**Current status**: Tests require fixture seeding (see Maintenance section)
 
 ## Results
 - Consolidated output stored in `test/results/verification.json` and human-readable logs in `test/results/*.log`.
 - CI must fail if any scenario reports non-zero status, missing files, or mismatched artifact hashes.
 
 ## Maintenance
-- Update fixtures via `scripts/fixture-tooling/seed-fixtures.sh` when README examples change.
-- Document any new environment knobs in README, spec, and plan as required by Principle IV.
+- **Fixture seeding**: Run `scripts/fixture-tooling/seed-fixtures.sh` to populate `test/fixtures/remotes/` with content
+  - Currently missing: needs implementation to create bare repos with `/metal`, `/setup/flux`, `/asciinema` paths
+- Update examples in `examples/Crossfile-*` when adding new features
+- Copy modified `Justfile` and `.env` to test repos via test scripts
+- Document environment knobs (`CROSS_NON_INTERACTIVE`, `CROSS_FETCH_DEPENDENCIES`) per Principle IV

specs/001-cross-test-strategy/research.md

@@ -1,5 +1,22 @@
 # Research Notes: cross command test strategy
 
+## Implementation Update: 2025-12-01
+
+### Decision: Justfile + Fish Shell implementation
+- **Rationale**: Provides excellent command-running ergonomics (`just` list, help) while delegating complex logic to fish. Vendorable into user repos via `import?` directive.
+- **Migration completed**: All commands (`use`, `patch`, `sync`, `diff`, `push`, `list`, `status`, `exec`, `replay`) now in Justfile.
+- **Trade-offs**: Requires `just` and `fish` as dependencies (added to constitution Principle III).
+
+### Decision: `cross` command prefix in Crossfile
+- **Rationale**: Extensibility for future plugin support (e.g., `just <plugin> <cmd>`). Makes git-cross commands explicit vs. potential user recipes.
+- **Implementation**: All Crossfile lines start with `cross` (e.g., `cross use`, `cross patch`, `cross exec`).
+
+### Decision: Post-hooks via `cross exec`
+- **Rationale**: Delegates flexibility to users rather than hardcoding hook logic. Allows calling user's own Justfile recipes or arbitrary shell commands.
+- **Implementation**: `_sync_from_crossfile` helper evaluates `cross exec <command>` lines from Crossfile.
+
+## Original Research (2025-11-28)
+
 ## Decision: Local git fixtures for examples and regression coverage
 - **Rationale**: Avoids network dependency while replicating README scenarios, enabling deterministic tests for `bill:/setup/flux` and other aliases. Local bare repositories can be seeded with required directories and commits.
 - **Alternatives considered**: (a) Hitting live upstreams (rejected: flaky, credentials), (b) Mocking git commands (rejected: misses integration).

specs/001-cross-test-strategy/spec.md

@@ -2,11 +2,20 @@
 
 **Feature Branch**: `001-cross-test-strategy`  
 **Created**: 2025-11-28  
-**Status**: Draft  
+**Status**: In Progress  
+**Last Updated**: 2025-12-01  
+**Implementation**: Justfile + Fish (migration complete)  
 **Input**: User description: "Implement test strategy for core functions in cross especially use and patch and any time later all documented functions and callables from usage documentation."
 
 ## Clarifications
 
+### Session 2025-12-01
+
+- Q: How should the tool handle command prefixes in Crossfile? → A: All commands use `cross` prefix for extensibility (e.g., `cross use`, `cross patch`, `cross exec`).
+- Q: How should post-hooks be implemented? → A: Via `cross exec <command>` to allow users to call their own Justfile recipes or shell scripts.
+- Q: What's the correct location for constitution.md? → A: `.specify/memory/constitution.md` for spec-kit compatibility.
+- Q: Should tests handle the Justfile implementation? → A: Yes, test scripts must copy `Justfile` and `.env` to test repositories.
+
 ### Session 2025-11-28
 
 - Q: Where must automated cross tests execute relative to the repository? → A: In a temporary directory outside the project workspace.