Skip to content

Standardize Core Document maintenance headers and index output formats #1760

Description

@codeforester

Goal

Make Base's documentation maintenance metadata consistent and make the documentation index complete.

Background

Only a handful of docs currently carry Status: and Last reviewed: headers. The eight undated Core Documents are authoritative but provide no local freshness signal, while docs/output-formats.md exists and is linked from the command reference without appearing in the Core Documents index.

The review identified this as a small governance gap that compounds as the documentation set grows.

Scope

  • Apply the established maintenance-header convention to the eight undated Core Documents:
    • docs/why-base.md
    • docs/architecture.md
    • docs/technical-overview.md
    • docs/command-reference.md
    • docs/execution-model.md
    • docs/runtime-environment.md
    • docs/tool-boundaries.md
    • docs/stability-tiers.md
  • Use accurate status wording for each document and a common current review date.
  • Add docs/output-formats.md to the Core Documents index in docs/README.md.
  • Keep the index ordering and descriptions readable; do not duplicate entries added by Complete local operating contract positioning across docs and guidance #1757.
  • Document the chosen convention briefly if the existing index or workflow page needs clarification.

Acceptance Criteria

  • Every Core Document has a clear Status: and Last reviewed: header.
  • output-formats.md appears in the Core Documents index exactly once.
  • Header wording does not imply that a document is more or less authoritative than intended.
  • The review date is consistent with the documentation train.
  • No broken relative Markdown links are introduced.
  • git diff --check passes.

Validation

  • git diff --check
  • Existing documentation/link checks.
  • Targeted inspection of the Core Documents index and all Core Document headers.

Non-Goals

Project Fields

  • Status: Backlog
  • Priority: P2
  • Area: Docs
  • Initiative: Contract Hardening
  • Size: S

Agent Assignment

Agent-ready after #1757 and #1759 are merged or their content is settled. Use the existing headers in the product and boundary docs as the convention baseline. This is the third implementation PR in the documentation review train.

Source

Derived from the Documentation Review: Base attachment, findings "Inconsistent maintenance-header convention" and "Orphaned doc".

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

Status
In Review

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions