quality-sync

$quality-sync
$quality-sync "--since HEAD~5"
$quality-sync "--full"
$quality-sync "--dry-run"
$quality-sync "--since abc123 --dry-run"

Flags:

• --full -- Complete resync of all tracked files (ignores git diff)
• --since <commit|HEAD~N> -- Diff since specific commit (default: last sync timestamp)
• --dry-run -- Show what would be updated without writing

Output boundary: ALL file writes MUST target .workflow/codebase/, .workflow/state.json, or doc-index.json only. NEVER modify source code or files outside .workflow/. --dry-run MUST suppress all writes.

Phase Gates (MANDATORY, BLOCKING)

GATE 1: Diff → Impact Trace

• REQUIRED: Git diff computed (or --full flag set for all files).
• BLOCKED if no diff and no --full: nothing to sync (W001).

GATE 2: Impact Trace → Refresh

• REQUIRED: Affected components traced via doc-index.json.
• BLOCKED if trace fails: cannot refresh docs without impact mapping.

GATE 3: Refresh → Completion

• REQUIRED: .workflow/codebase/ docs refreshed for affected components.
• REQUIRED: If --dry-run is set, skip state.json write and report what would change. Otherwise, update state.json with sync timestamp.
• BLOCKED if missing: do not report completion without updated docs.

Step 1: Validate

Verify .workflow/ directory exists — if missing, raise E001.

Step 2: Detect Changes

If --full: skip diff, mark all tracked files as changed.

Otherwise:

1. Read last sync commit from state.json field last_synced_commit (a git commit hash). If last_synced_commit is missing, fall back to git log --reverse --format=%H | head -1 (first commit) as baseline.
2. If --since provided, use that as baseline (overrides last_synced_commit)
3. Run git diff --name-only {baseline} HEAD to get changed files

If no changes and not --full, report clean state (W001) and exit.

Step 3: Trace Impact Chain

For each changed file, trace through doc-index.json impact layers:

1. File layer -- Which doc entries reference this file directly
2. Component layer -- Which components contain this file
3. Feature layer -- Which features depend on affected components
4. Requirement layer -- Which requirements trace to affected features

Build the full set of affected documentation entries.

Step 4: Update Documentation

If --dry-run: display affected entries and exit.

For each affected entry:

1. Re-read source files
2. Regenerate the documentation section in .workflow/codebase/
3. Update doc-index.json with new timestamp and content hash

Step 5: Update State

Update state.json:

• last_synced: "{ISO timestamp}"
• last_synced_commit: "{HEAD commit hash}"

Update affected index.json files in phase directories if task files were modified.

Step 6: Tech Stack Refresh (Conditional)

If dependency manifests changed (package.json, Cargo.toml, go.mod, pyproject.toml, pom.xml):

• Re-read manifest files
• Update project.md Tech Stack section with current dependencies/versions
• Update doc-index.json tech-registry entries

Step 7: Report & Routing

Display summary: files changed, components affected, features affected, docs updated, tech stack refreshed (if applicable).

Next-step routing:

Result	Next Step
Docs refreshed successfully	$manage-status
Major structural changes detected (new modules, removed dirs)	$manage-codebase-rebuild (full rebuild recommended)
Dependency manifests changed significantly	Review project.md Tech Stack for accuracy

<error_codes>

Code	Severity	Description
E001	error	.workflow/ not initialized -- run $maestro-init first
W001	warning	No changes detected since last sync

</error_codes>

<success_criteria>

• Changed files detected (or full resync triggered)
• Impact chain traced through all layers (file → component → feature → requirement)
• Documentation entries updated in .workflow/codebase/
• doc-index.json reflects current file state with updated hashes
• state.json updated with sync timestamp and commit hash
• If dependency manifests changed: project.md Tech Stack section refreshed
• Summary report with next-step routing displayed </success_criteria>