[shiplog/plan] Add schema versioning and compatibility policy for artifact envelopes

[devallibus]

Context

Artifact envelopes are becoming a real protocol surface for shiplog, not just an internal formatting trick. The current schema is forward-friendly in one narrow sense (unknown fields must be ignored), but there is still no explicit way for an agent or integration to know which schema revision an artifact targets, what compatibility guarantees exist across revisions, or how a mixed-version repository should be interpreted during migration.

That becomes more important as shiplog adds triage fields, edit provenance, and retrieval behaviors: without a versioning policy, even small future changes risk ambiguous reads, brittle parsers, and uncertainty about whether a missing field means "old artifact" or "malformed artifact".

Design Summary

• Add an explicit schema field to the envelope format, using an integer version (schema: 1) at the top-level alongside kind
• Define a compatibility contract: missing schema means version 1 for back-compat, additive fields within a schema version must be safely ignorable, and breaking semantic changes require a new schema version
• Document migration guidance for mixed-version repos so agents know when to default, warn, or fall back to visible prose
• Update envelope examples so the canonical examples actually show the version marker

Approach

This should stay documentation-first. No parser or automation is required to get the benefit; the important step is making schema evolution explicit in �rtifact-envelopes.md and reflecting it in the examples and retrieval guidance. Keep the contract simple enough that a human can apply it by inspection.

Alternatives Considered

Alternative	Why not
Keep relying on "ignore unknown fields" only	Helps additive changes, but does not explain missing fields, semantic redefinitions, or mixed-version artifacts
Put versioning in repo-level config only	Parsers need to reason about individual artifacts, including historical ones copied across repos or viewed out of context
Use date-based schema evolution with no explicit field	Harder to reason about, test, and document than a single visible version field

Tasks

• T1: Add schema to the envelope field schema and normalization rules [tier-3]

  • What: Update skills/shiplog/references/artifact-envelopes.md so the field table includes schema, with integer semantics and a back-compat rule that omitted schema is interpreted as version 1.
  • Files: skills/shiplog/references/artifact-envelopes.md (modify)
  • Allowed to change: Field schema table, normalization rules, minimal envelope example, full examples
  • Must not change: Canonical artifact kinds, supersession rules, or retrieval order
  • Forbidden judgment calls: Do not rename existing fields or introduce multiple version fields
  • Stop and ask if: The repo already adopted a conflicting version field name outside this issue
  • Verification: Read the updated file and confirm schema appears in the field table, normalization rules, and examples
  • Return artifact: Diff summary for �rtifact-envelopes.md
  • Decision budget:
    one
  • Accept when: A reader can tell what schema means, what omitted schema means, and how to write a versioned envelope
  • Context: Use schema: 1 as the concrete convention in this issue

• T2: Add a compatibility and evolution policy section [tier-3]

  • What: Add a short section to skills/shiplog/references/artifact-envelopes.md that defines the compatibility contract: additive fields are safe within a schema version, semantic or structural breaks require a version increment, and agents encountering a newer schema should prefer envelope fields they recognize and fall back to visible prose when required semantics are unknown.
  • Files: skills/shiplog/references/artifact-envelopes.md (modify)
  • Allowed to change: New subsection near normalization or retrieval guidance
  • Must not change: Existing retrieval examples beyond minimal version-marker updates
  • Forbidden judgment calls: Do not invent a major/minor system; keep the contract to a single integer schema version
  • Stop and ask if: Another open issue lands a different compatibility policy first
  • Verification: Read the new section and confirm it answers back-compat, forward-compat, and mixed-version behavior
  • Return artifact: Diff summary for the new policy section
  • Decision budget:
    one
  • Accept when: The schema evolution rules are explicit enough that another tool could implement them without guessing
  • Context: The goal is protocol stability, not maximum theoretical flexibility

• T3: Thread schema-awareness into retrieval guidance and examples [tier-3]

  • What: Update the retrieval guidance in skills/shiplog/references/artifact-envelopes.md so envelope-first lookup explicitly mentions schema handling, and refresh the example envelopes in that file to include schema: 1.
  • Files: skills/shiplog/references/artifact-envelopes.md (modify)
  • Allowed to change: Retrieval guidance wording and example blocks only
  • Must not change: The overall retrieval strategy or command patterns
  • Forbidden judgment calls: Do not add new commands or widen scope into implementation tooling
  • Stop and ask if: Updating examples would conflict with another open documentation rewrite touching the same sections
  • Verification: Read the examples and retrieval section and confirm schema-handling is visible and consistent
  • Return artifact: Diff summary for the touched sections
  • Decision budget:
    one
  • Accept when: A reader sees versioning both in the schema docs and in the practical retrieval flow
  • Context: This issue is only about making schema evolution explicit; keep it tight

Open Questions

None ? the issue intentionally pre-decides the field name (schema) and baseline convention (schema: 1) so execution can stay tier-3.

---

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