chore: sync local Mosaic changes

templates/docs/DOCUMENTATION-CHECKLIST.md

@@ -0,0 +1,49 @@
+# Documentation Completion Checklist
+
+Use this checklist for every task that changes code, API contracts, auth, or operations.
+
+## Required Artifacts
+
+- [ ] `docs/PRD.md` or `docs/PRD.json` exists and is current
+- [ ] `docs/USER-GUIDE/` updated as needed
+- [ ] `docs/ADMIN-GUIDE/` updated as needed
+- [ ] `docs/DEVELOPER-GUIDE/` updated as needed
+- [ ] `docs/API/OPENAPI.yaml` (or `.json`) updated for API changes
+- [ ] `docs/API/ENDPOINTS.md` updated for API changes
+- [ ] `docs/SITEMAP.md` updated for navigation changes
+
+## API Coverage
+
+- [ ] All public endpoints are documented
+- [ ] All private/internal endpoints are documented
+- [ ] All API input schemas are documented
+- [ ] All API output schemas are documented
+- [ ] All endpoint auth/permission requirements are documented
+- [ ] Error codes and failure behavior are documented
+
+## Structural Standards (Book/Chapter/Page)
+
+- [ ] `docs/USER-GUIDE/README.md` indexes user chapters/pages
+- [ ] `docs/ADMIN-GUIDE/README.md` indexes admin chapters/pages
+- [ ] `docs/DEVELOPER-GUIDE/README.md` indexes developer chapters/pages
+
+## Docs Root Hygiene
+
+- [ ] `docs/` root is clean and only contains canonical root docs (PRD, TASKS when active, SITEMAP, optional README) plus category directories
+- [ ] Reports are under `docs/reports/<category>/` (not `docs/` root)
+- [ ] Deferred findings are under `docs/reports/deferred/`
+- [ ] Orchestrator learnings are under `docs/tasks/orchestrator-learnings.json`
+- [ ] Release notes are under `docs/releases/`
+- [ ] Archived task snapshots are under `docs/tasks/`
+- [ ] Scratchpads are under `docs/scratchpads/`
+
+## Review Gate
+
+- [ ] Documentation changes are in the same logical change set as code/API changes
+- [ ] Code review verified documentation completeness
+- [ ] Missing docs were treated as blocker findings
+
+## Publishing
+
+- [ ] Publishing target was confirmed with user if unspecified
+- [ ] Canonical source remains in-repo unless user explicitly declares otherwise

templates/docs/PRD.md.template

@@ -0,0 +1,75 @@
+# PRD: {PROJECT_OR_FEATURE_NAME}
+
+## Metadata
+
+- Owner: {owner}
+- Date: {yyyy-mm-dd}
+- Status: draft|approved|in-progress|completed
+- Best-Guess Mode: true|false
+
+## Problem Statement
+
+{what problem is being solved and why now}
+
+## Objectives
+
+1. {objective-1}
+2. {objective-2}
+
+## Scope
+
+### In Scope
+
+1. {in-scope-item}
+
+### Out of Scope
+
+1. {out-of-scope-item}
+
+## User/Stakeholder Requirements
+
+1. {requirement}
+
+## Functional Requirements
+
+1. {functional-requirement}
+
+## Non-Functional Requirements
+
+1. Security: {requirements}
+2. Performance: {requirements}
+3. Reliability: {requirements}
+4. Observability: {requirements}
+
+## Acceptance Criteria
+
+1. {ac-1}
+2. {ac-2}
+
+## Constraints and Dependencies
+
+1. {constraint-or-dependency}
+
+## Risks and Open Questions
+
+1. Risk: {risk}
+2. Open Question: {question}
+
+## Testing and Verification Expectations
+
+1. Baseline checks: {lint/type/unit/integration expectations}
+2. Situational testing: {required situational checks}
+3. Evidence format: {how verification will be reported}
+
+## Milestone / Delivery Intent
+
+1. Target milestone/version: {e.g., 0.0.2}
+2. Definition of done: {completion conditions}
+
+## Assumptions
+
+List only if Best-Guess Mode is true.
+Prefix each entry with `ASSUMPTION:`.
+
+1. ASSUMPTION: {guessed decision and rationale}
+

templates/docs/TASKS.md.template

@@ -0,0 +1,17 @@
+# TASKS
+
+Canonical tracking for active work. Keep this file current.
+
+## Rules
+
+1. Update status as work progresses.
+2. Link every non-trivial task to a provider issue (`#123`) or internal ref (`TASKS:T1`) if no provider is available.
+3. Keep one row per active task.
+4. Do not set `status=done` for source-code work until PR is merged, CI/pipeline is terminal green, and linked issue/ref is closed.
+5. If merge/CI/issue closure fails, set `status=blocked` and record the exact failed wrapper command in `notes`.
+
+## Tasks
+
+| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| T1 | not-started | Example task description | TASKS:T1 | app | feat/example | | | | | | | | |