architecture-doc-decisions

D1 — Homes after non-OpenSpec architecture RST retirement

Status: Ratified for this narrowed change.

Decision: After deleting non-OpenSpec architecture RST:

  1. Capability contracts that still use OpenSpec/OPSX remain under the existing buried home documentation/architecture/openspec/ (unchanged location in this change).

  2. Code-local constraints/rationale live in the nearest subsystem README under the project’s actual source layout (layout-agnostic for the fleet; this-repo apply note may name sources/agentsmgr/README.md).

  3. Root README is never the home for constraints/rationale.

  4. This repository may already publish separate Nbspec-managed docs under documentation/{specifications,designs,decisions}/ for unrelated changes (e.g. clone topology). That is project-local Sphinx content, not authorization of a fleet Nbspec cutover in this change.

D2 — Delete superseded and generic material rather than migrate

Status: Ratified.

Decision: Superseded ADR-001-class content, empty design/testplan shells, broken external link sections, stale file inventories, and generic test-process prose are deleted without new homes. Git history retains them. Still-current capability requirements stay in OpenSpec specs (currency edits only).

D3 — Capability spec currency audit only (no Nbspec migrate)

Status: Ratified (narrowed; supersedes earlier “migrate all six to documentation/specifications/” for this change id).

Decision: Audit all six OpenSpec capability specs for currency. Still-current requirements remain under documentation/architecture/openspec/specs/. Obsolete scenarios may be edited or deleted with reason. No migration of those specs into Nbspec documentation/specifications/ in this change. Full cutover is a separate proposal.

D4 — Agent command references via components + generate; remove cs-architect

Status: Ratified.

Decision:

  1. Fix citations to deleted architecture paths in components/contents/, then regenerate distribution/. Do not hand-edit distribution as source of truth.

  2. Formally remove cs-architect (component configuration, contents, and generated artifacts). No specification required its existence. Architecture work continues via OpenSpec/OPSX, subsystem READMEs, and remaining design/implementation commands. No Towncrier fragment (distribution command content is not on the agentsmgr Towncrier stream under current practice).

D5 — No coupling to issues/5 autosquash guidance

Status: Ratified.

Decision: Do not rewrite template/.auxiliary/agents/procedures/reviews.md autosquash inspect/apply guidance.

D6 — OpenSpec home location unchanged (deferred)

Status: Out of scope for this change (explicit deferral).

Decision: Do not implement guarded populate migration, symlink retarget to documentation/openspec/, template relocate, or stop creating documentation/architecture/openspec in this change. population.py and template OpenSpec scaffolding remain as today. Later work requires a new proposal (see follow-up todo). This change must not be cited as authorization for D6.

D7 — Sphinx: this-repo publication; stop OpenSpec capability glob

Status: Ratified (narrowed).

Decision:

  1. Stop documentation/specifications/index.rst from globbing ../architecture/openspec/specs/*/spec.

  2. Exclude the buried OpenSpec tree from the Sphinx HTML set as needed.

  3. Index this repository’s existing Nbspec-managed docs under documentation/{specifications,designs,decisions}/ for Sphinx only.

  4. Do not ship those paths as fleet architecture homes via template or distribution in this change.

D8 — Single package README first (layout-agnostic)

Status: Ratified.

Decision: Prefer one package-level README per subsystem package in the first pass. Nested READMEs only if unwieldy. This-repo apply-time destination for agentsmgr rationale: sources/agentsmgr/README.md.

D9 — Stop-ship architecture.rst via explicit docs-1 file map

Status: Ratified.

Decision:

  1. Explicit docs-1 file map omitting architecture.rst in Copier defaults and default/maximum test profiles.

  2. No new instruction-exclusion API.

  3. Intentionally remove tracked distribution/.../instructions/architecture.rst; validate non-reselect.

  4. Self-dogfood .auxiliary/configuration/copier-answers--agents.yaml remains Copier-owned; may still use *.rst until the next copier update picks up defaults (accepted residual).

  5. No provenance-safe downstream stale auto-removal claim (todos/agentsmgr/10 still open).

  6. Do not silently delete downstream copies.

D10 — Prompts and notes

Status: Ratified (narrowed).

Decision:

  1. Delete prompts/openspec-init.md.

  2. Keep prompts/migrate-to-openspec.md for unfinished fleet migrations.

  3. Clear project-local .auxiliary/notes after preserving useful open items in nb; retarget commands so they do not teach that path.