[shiplog/plan] Add envelope consistency invariants and repair guidance

[devallibus]

Context

shiplog now carries current state in several places at once: hidden envelope fields, visible task checkboxes, lifecycle labels, and the human-readable issue or PR narrative. Each piece is documented, but the repo does not yet define a single consistency contract for how those views must agree or how an agent should repair drift when they do not.

That gap matters most for the smart parts of the system: low-token triage only works if ask_count, asks_complete,
eadiness, max_tier, and lifecycle labels reliably match the visible body. Without explicit invariants and a repair procedure, two models could both follow the docs and still leave an artifact in a partially stale state.

Design Summary

• Add a cross-artifact consistency section that defines the required relationships between envelope triage fields, visible task checklists, lifecycle labels, and status text
• Define precedence and repair rules: when to edit in place, when to post an amendment, and which representation is authoritative when values disagree
• Add a lightweight audit checklist to the workflow so agents verify these invariants during timeline maintenance or retrieval-sensitive updates
• Keep enforcement instructional, matching the existing docs-first philosophy from [shiplog/plan] Add tier-3 validation: Open Questions cross-check and full contract enforcement #114 rather than introducing new tooling

Approach

Document the invariants where they belong: envelope semantics in �rtifact-envelopes.md, lifecycle label expectations in labels.md, and the operational audit step in a workflow-facing shiplog doc. Focus on the highest-value drift cases: task counts, readiness, current status, and lifecycle labels.

Alternatives Considered

Alternative	Why not
Leave consistency implicit	Agents can infer some relationships, but not enough to produce predictable repair behavior across tools and sessions
Solve it only with labels	Labels are useful list-level signals, but they cannot replace the richer envelope fields or visible task state
Add a validator first	The protocol should define what "correct" means before any implementation tries to enforce it

Tasks

• T1: Document envelope-to-body invariants [tier-3]

  • What: Add a subsection to skills/shiplog/references/artifact-envelopes.md that defines concrete invariants for ask_count, asks_complete,
    eadiness, max_tier, and status relative to the visible issue or PR body.
  • Files: skills/shiplog/references/artifact-envelopes.md (modify)
  • Allowed to change: New subsection near triage fields or retrieval guidance
  • Must not change: Existing canonical kind taxonomy or supersession rules
  • Forbidden judgment calls: Do not redefine existing field meanings; only add cross-check rules
  • Stop and ask if: Another open issue changes the meaning of any triage field before this lands
  • Verification: Read the new subsection and confirm each triage field has at least one explicit cross-check against visible state
  • Return artifact: Diff summary for the invariants section
  • Decision budget:
    one
  • Accept when: A reader can inspect an issue body and tell whether the envelope triage fields are stale or consistent
  • Context: Prioritize the invariants that affect triage and retrieval quality, not every possible cosmetic mismatch

• T2: Define precedence and repair rules for drift [tier-3]

  • What: Add documentation that explains which representation is authoritative when envelope fields, lifecycle labels, and visible checklist state disagree, and whether the fix should be an in-place edit or an amendment artifact.
  • Files: skills/shiplog/references/artifact-envelopes.md (modify), skills/shiplog/references/labels.md (modify)
  • Allowed to change: New guidance sections only
  • Must not change: Existing label names, colors, or auto-label mapping signals beyond clarifying repair order
  • Forbidden judgment calls: Do not widen this into a tooling proposal or new label taxonomy
  • Stop and ask if: The repair rules would require changing the signing guidance instead of referencing it
  • Verification: Read both files and confirm they say how to repair stale labels and stale envelope fields without contradicting each other
  • Return artifact: Diff summary for both files
  • Decision budget:
    one
  • Accept when: An agent encountering drift has a single documented repair path instead of guessing
  • Context: Align with the existing edit-in-place vs amendment distinction rather than inventing a second repair model

• T3: Add an audit checkpoint to a workflow-facing doc [tier-3]

  • What: Add a short audit checklist to one workflow-facing shiplog document (skills/shiplog/SKILL.md, skills/shiplog/timeline.md, or another clearly appropriate entry point) telling agents to cross-check triage fields and lifecycle labels before posting or refreshing current-state artifacts.
  • Files: one workflow-facing shiplog doc (modify)
  • Allowed to change: Insert one concise checklist or paragraph in the most relevant maintenance-oriented section
  • Must not change: Phase ordering or unrelated workflow steps
  • Forbidden judgment calls: Do not duplicate the full schema rules in multiple files; add only the operational checkpoint and point back to the canonical references
  • Stop and ask if: More than one workflow doc seems equally authoritative for the checkpoint location
  • Verification: Read the updated doc and confirm the checkpoint is actionable, concise, and references the canonical consistency rules
  • Return artifact: Diff summary for the chosen file
  • Decision budget:
    one
  • Accept when: The workflow includes a clear moment where agents are told to repair stale triage metadata before relying on it
  • Context: This complements [shiplog/plan] Add triage-scan workflow with envelope triage fields and lifecycle labels #102 and [shiplog/plan] Add tier-3 validation: Open Questions cross-check and full contract enforcement #114 by covering post-write consistency, not tier assignment

Open Questions

None ? the issue is scoped to documenting invariants and repair behavior, not inventing enforcement tooling.

---

Authored-by: openai/gpt-5.4 (cursor)
Captain's log entry created by shiplog