docs: correct stale references in canonical specs and permanent docs

[kakadlec]

Audit of all six canonical specs against the six permanent docs and the running code. Eight corrections, no behavior change — every edit aligns text with code that is already merged.

Canonical specs

File	Was	Now
video-frame-extraction/spec.md	Purpose read TBD - created by archiving change add-integration-tests. Update Purpose after archive.	A real purpose, which also names where access control is specified (identity-authentication, video-processing-access)
video-frame-extraction/spec.md	Processed Files Listing said /api/status returns "the list of zip files currently present in outputs/"; Processed File Download gated only on existence	Both amended to the owner-scoped contract Phase 2 actually shipped (main.go:416-422, main.go:448-453), with new scenarios
ddd-architecture/spec.md	"exactly eight phases" scenario asserted docs/roadmap.md cites openspec/changes/establish-ddd-architecture-foundation/design.md	Cites openspec/specs/ddd-architecture/spec.md, which is what the file actually says since that change archived

The video-frame-extraction one is the substantive fix. Phase 2 changed /api/status and /download/:filename from "anyone sees everything" to owner-scoped, wrote its delta into two new specs, and left this older spec asserting the pre-Phase-2 contract. It is written as amended requirements with added scenarios rather than a sentence patch, so the spec doesn't read as though ownership was always specified there.

Permanent docs

File	Correction
domain-model.md	UserID was described as defined in pkg/. pkg/ doesn't exist; UserID is in internal/identity/domain/user_id.go:15. Now split into target vs. current state — the section had no phase label, so it read as current, which ddd-architecture:243 forbids
domain-model.md	Cited implement-videojob-persistence and implement-notifications; neither exists in the Change Backlog. Phase 3 is decomposed into five differently-named rows, Phases 4–8 aren't decomposed at all
architecture.md	docker-compose.yml described as "Local/CI PostgreSQL service for identity persistence tests"; it has three services (postgres, app, app-test)
architecture.md	Workflow list omitted auto-update-pr-branches.yml
flows.md	API compatibility table said GET /api/status "Lists all ZIPs in outputs/", contradicting architecture.md:73 and README.md:73, which correctly scope it to the caller

Roadmap

Removed the fix-stale-roadmap-link-in-ddd-architecture-spec Change Backlog row — its entire scope is the ddd-architecture fix above. Leaving it would advertise finished work as not-started.

Deliberately not touched

container-image/spec.md:35 says the image must "require no environment variables to start". That is currently accurate — setupIdentity returns a nil module and no error when both identity variables are unset. It only becomes false when enforce-mandatory-identity-config ships, and editing it now would make a canonical spec describe unimplemented behavior. That change's tasks.md has no container-image delta and needs one — flagging it here rather than pre-emptively breaking the spec.

Verification

• All six touched files keep their ### Requirement: / #### Scenario: structure and GIVEN/WHEN/THEN shape — video-frame-extraction parses as 8 requirements / 14 scenarios with no incomplete scenario. This matters because openspec validate targets changes, not openspec/specs/, so these files get no schema check; the archive/promotion logic parses that structure.
• No dangling references to the removed backlog row anywhere in tracked files.
• git diff --check clean.
• No Go module input (.go/go.mod/go.sum) in the diff, so the local go test ./... -v gate does not apply and was not run.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Corrects stale specifications and documentation to match the current owner-scoped video-processing behavior and repository structure.

Changes:

• Documents owner-scoped status and download behavior.
• Corrects architecture, domain-model, workflow, and roadmap references.
• Removes a completed documentation-hygiene backlog item.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
openspec/specs/video-frame-extraction/spec.md	Updates purpose and ownership contracts.
openspec/specs/ddd-architecture/spec.md	Corrects the canonical roadmap link.
docs/roadmap.md	Removes the documentation-hygiene entry.
docs/flows.md	Documents owner-scoped endpoints.
docs/domain-model.md	Corrects phase and UserID details.
docs/architecture.md	Updates Compose and workflow inventory.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.