SLT.BETA.018 – Anchors lifecycle: commands and flow

[flyingrobots]

[SLT.BETA.018] Anchors lifecycle: commands and flow

Overview

Introduce first-class anchor commands for managing refs/_shiplog/anchors/<env> so operators can bookmark significant deployments and generate "since last anchor" reports.

References & Assets

• Figma / Design: N/A
• Product Spec (Notion / Confluence): N/A
• Related Issues / PRs: SLT.BETA.017
• Feature Flags / Experiments: N/A
• Other Assets: N/A

User Story

As a deploy operator, I want to create and move Shiplog anchors so that I can quickly diff or report changes since the last milestone deployment.

Acceptance Criteria

• git shiplog anchor create records a named anchor under refs/_shiplog/anchors/<env>
• Moving an anchor enforces fast-forward semantics and audit trail
• write/run flows can optionally reference anchors for reporting
• Documentation added covering anchor lifecycle and usage examples
• Tests cover create, move, show, and fast-forward enforcement

Definition of Done

Anchor commands implemented with tests and docs, and integration points surface anchor metadata for reporting.

Scope

In-Scope

• CLI commands for anchor lifecycle (create, move, show)
• Fast-forward enforcement and audit logging
• Documentation and tests

Out-of-Scope

• UI dashboards consuming anchors
• Automatic anchor scheduling

Deliverables

• Est. Lines of Code: ~220
• Est. Blast Radius: lib/commands.sh, new anchor scripts, docs

Implementation Details

High-Level Approach

Define anchor ref layout, implement helper functions, wire CLI commands, and integrate optional anchor references into reporting workflows.

Affected Areas

• lib/commands.sh
• scripts/anchors.sh
• docs/features/anchors.md
• tests/anchors.bats

Implementation Steps

• Define anchor ref schema and metadata
• Implement CLI commands (create/move/show)
• Enforce fast-forward semantics with helpful errors
• Update docs and examples for anchor usage
• Add Bats coverage for anchor operations

Test Plan

Happy Path

• Creating first anchor succeeds and logs location
• Moving anchor forward updates ref and audit note

Edge Cases

• Attempting to move anchor backwards is rejected
• Anchors interact correctly with multiple environments

Failure Cases

• Invalid anchor name surfaces descriptive error

Monitoring & Success Metrics

• CLI logs include anchor actions for audit

QA Sign-off Matrix

Environment	Surface	Owner	Status	Notes
Local Docker	CLI	TBD	Pending	Validated via make test

Requirements

Hard Requirements

• Anchor updates must be fast-forward only

Soft Requirements

• Provide convenience output for "since anchor" queries

Runtime Requirements

• Works in offline/local sandbox environments

Dependencies & Approvals

• Docs review for anchors guide

---

Production Notes

Priority: 2 / 5

Useful workflow enhancer (P3 roadmap item).

Complexity: 3 / 5

Requires new ref management and CLI features.

Estimate: 18 - 26 hours

Includes CLI work, docs, and tests.

Risk & Rollback

• Primary Risks: Anchor rewrites causing history confusion
• Mitigations: Enforce fast-forward, thorough docs
• Rollback / Kill Switch: Disable anchor commands via feature flag

---

Additional Notes

Coordinate with reporting tooling to leverage anchors post-release.

[flyingrobots]

Estimate: 3 hours.

Rationale:

• Define anchor semantics and UX
• Implement git shiplog anchor [create|move|show]
• Wire anchors into write/run flows as appropriate
• Add docs and examples