Skip to content

spec 031-database-abstraction: 2958-line spec.md should be split, embedded agent-identity subsystem has no external references #6632

Description

@bug-ops

Description

`specs/031-database-abstraction/spec.md` is 2958 lines. The specs quality audit in PR #6629 found it bundles multiple concerns that should be separate documents:

  • Section 18, "Agent Identity in the Shared Data Model" (~900 lines, roughly lines 1941-2848), is a fully self-contained, independent subsystem (multi-tenant agent-scoped data isolation) with zero references to or from it anywhere else in `/specs/`.
  • Sections 1-17 contain a superseded RFC-style narrative with the feature-flag design restated multiple times and version numbers that had drifted from `Cargo.toml` over time (partially corrected in PR docs(specs): correct stale references, broken links, and formatting #6629, but the narrative duplication itself was left as-is).
  • Sections 19-20 (amendment log, implementation state) are accurate and should remain as the living reference.

A single 2958-line file is too large to serve as a coherent single implementation contract per the sdd skill's own size guidance, and section 18 in particular reads as a spec that was never given its own directory.

Expected Behavior

  • Section 18 ("Agent Identity in the Shared Data Model") extracted into its own `specs/0NN-agent-identity-data-isolation/spec.md`, registered in `specs/README.md` and `specs/MOC-specs.md`, with a cross-reference left in `031-database-abstraction/spec.md`.
  • Sections 1-17's restated RFC narrative consolidated to remove duplication, keeping one canonical statement of the feature-flag design.

Actual Behavior

Everything lives in one file, making it hard to review as a single contract and burying an independent subsystem's spec inside an unrelated document.

Environment

Logs / Evidence

See PR #6629 description, "Flagged, not executed" section, item 1.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P2High value, medium complexityarchArchitecture and designdocsDocumentationtech-debtTechnical debt

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions