Skip to content

I1310 — The subsystem is documented where a person looks, and the plan is closed against the repository

Write docs/WORKSPACES.md, add the row to the documentation index, and re-audit the repository against this milestone: what was reinvented, what legacy duplication survives, and which of the pack's phases turned out not to apply here.

BLOCKED wave 5 · p2 · deep-work profile · parallel safe

Part of external-workspaces — An external workspace is read the way this repository reads anything else, and its content never becomes public by accident.

Blocked. This issue cannot start until I1308, I1309 are done. The status is derived from that, not declared.

Objective

Write docs/WORKSPACES.md, add the row to the documentation index, and re-audit the repository against this milestone: what was reinvented, what legacy duplication survives, and which of the pack's phases turned out not to apply here.

Why

The pack this milestone came from assumes surfaces that the audit showed are unreachable for local content, and a later worker reading the pack rather than this milestone would rebuild that assumption. The documentation is where that is settled for whoever comes next.

Current state

ADR 0025 records the decision and its withdrawal of two earlier positions. Nothing in docs/ describes the subsystem.

Desired state

docs/WORKSPACES.md states what a workspace is, how it differs from a provider, the transport policy and its honesty about acquisition mode, the store and its boundary, what is deliberately not published, and how a second vendor is added. The index row exists; the site renders it; the re-audit is recorded.

Scope

  • docs
  • .ai/repo/adrs

Out of scope

  • Documenting a capability that does not exist yet

Dependencies

Acceptance criteria

  • docs/WORKSPACES.md exists, is linked from the documentation index, and renders on the site
  • The document states the distinction from ADR 0024's provider in its own words, so that a reader who never opens the ADR does not conflate them
  • The re-audit names every place a second implementation of an existing mechanism was avoided, and every place one survives
  • ADR 0025 is accepted or amended by a person, and its status reflects what was actually built

Validation

  • bash test/run.sh
  • majordomus generate --check

Evidence required

  • documented
  • indexed
  • reaudited
  • adr_settled

Evidence

None recorded. Every token above needs a command or an artifact behind it before this issue can be completed; narrative is refused.

Risk

Documentation written from the plan rather than from the built subsystem. It is written last for that reason.

Timeline

started
—
verified
—
completed
—

Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.

Canonical record: .ai/repo/project/issues/I1310.yaml. Read it back with majordomus plan show I1310.