SLT.BETA.017 – Enforce policy fields: require_ticket/require_where/ff_only

[flyingrobots]

[SLT.BETA.017] Enforce policy fields: require_ticket/require_where/ff_only

Overview

Align runtime enforcement with documented policy fields by validating required metadata (ticket, where) and honoring ff_only rules in both CLI and hooks.

References & Assets

• Figma / Design: N/A
• Product Spec: N/A
• Related Issues / PRs: SLT.ALPHA.021, SLT.ALPHA.030
• Feature Flags / Experiments: N/A
• Other Assets: docs/features/policy.md

User Story

As a deployment approver, I want Shiplog to enforce required policy fields and fast-forward rules so that every entry meets governance expectations before it's recorded.

Acceptance Criteria

• CLI rejects write/run commands missing required policy fields (ticket, where, service, etc.)
• Pre-receive hook validates trailer JSON and enforces configured requirements
• Policy-level ff_only toggle respected alongside existing ref protections
• Documentation updated with enforcement behavior and examples
• Tests cover allow/deny cases for each requirement

Definition of Done

Policy enforcement implemented across CLI and hooks with comprehensive tests and documentation updates.

Scope

In-Scope

• CLI validation for required policy fields
• Hook enforcement for trailer data
• Honor policy ff_only switch
• Documentation updates

Out-of-Scope

• GUI tooling for policy editing
• Automated ticket lookup integrations

Deliverables

• Est. Lines of Code: ~260
• Est. Blast Radius: lib/policy.sh, hooks, docs, tests

Implementation Details

High-Level Approach

Extend policy loader to expose required fields, enforce in CLI before commit creation, reuse validation logic in pre-receive hook, and respect ff_only setting when evaluating pushes.

Affected Areas

• lib/policy.sh
• contrib/hooks/pre-receive.shiplog
• docs/features/policy.md
• tests/policy_enforcement.bats

Implementation Steps

• Extend policy schema/validator with enforcement metadata
• Update CLI write/run to enforce required fields with clear errors
• Update hook to parse trailers and enforce requirements
• Wire policy ff_only to existing push protections
• Document behavior and add tests

Test Plan

Happy Path

• Entry with all required fields succeeds locally and in hook
• Push respecting ff_only passes

Edge Cases

• Policy requiring multiple fields enforces each individually
• Allowlist or environment overrides handled correctly

Failure Cases

• Missing required field triggers actionable error message
• Non fast-forward update rejected when ff_only true

Monitoring & Success Metrics

• Hook logs include enforcement outcome per push

QA Sign-off Matrix

Environment	Surface	Owner	Status	Notes
Local Docker	CLI + Hook	TBD	Pending	Covered via make test

Requirements

Hard Requirements

• Policy-defined requirements must block non-compliant writes/pushes

Soft Requirements

• Errors reference docs for remediation

Runtime Requirements

• Enforcement works offline and in Docker matrix hosts

Dependencies & Approvals

• Policy schema review
• Security/compliance sign-off

---

Production Notes

Priority: 3 / 5

Important to align docs with enforcement (P2).

Complexity: 4 / 5

Touches CLI, hooks, and policy schema.

Estimate: 22 - 30 hours

Includes implementation, tests, and docs.

Risk & Rollback

• Primary Risks: False positives blocking releases
• Mitigations: Feature flag to relax enforcement; thorough tests
• Rollback / Kill Switch: Policy switch to disable enforcement per env

---

Additional Notes

Depends on policy schema improvements (SLT.ALPHA.030) landing first.

[flyingrobots]

Estimate: 3 hours.

Rationale:

• CLI: validate required fields before composing commit
• Hook: enforce required fields by parsing trailer JSON
• Hook: enforce ff_only via policy switch (keep current FF checks as baseline)
• Docs: examples and guidance