coding-os 0.3.2__py3-none-any.whl

templates/_base/Makefile.base

@@ -0,0 +1,353 @@
+# coding-os — Universal Make Targets
+# Include this in your project Makefile: include .coding-os/Makefile.base
+# Or copy to your project root.
+
+.DEFAULT_GOAL := help
+
+# ── Coding OS paths ─────────────────────────────────────────────────
+# Override these if your coding-os is in a non-standard location.
+# Portable resolution order:
+#   1. Installed `cos` binary on PATH (preferred)
+#   2. Adapter hook symlink back to the coding-os install
+# This keeps consumer projects runnable outside the coding-os repo itself.
+COS_HOOKS ?= $(shell if command -v cos >/dev/null 2>&1; then cos hooks-dir; elif [ -e .codex/hooks/cos-env.sh ]; then dirname "$$(realpath .codex/hooks/cos-env.sh)"; elif [ -e .claude/hooks/cos-env.sh ]; then dirname "$$(realpath .claude/hooks/cos-env.sh)"; fi)
+COS_ROOT ?= $(shell dirname "$$(dirname "$(COS_HOOKS)")")
+COS_SCRIPTS := $(COS_ROOT)/core/scripts
+
+export COS_STATE_DIR ?= .coding-os
+export COS_DB_PATH ?= $(COS_STATE_DIR)/coding-os.db
+export COS_BRAIN_DIR ?= $(COS_ROOT)/core/thinking_os
+
+# ── Session & Status ────────────────────────────────────────────────
+
+.PHONY: session-init
+session-init: ## Run ONCE per session: phase + recent changes + task summary
+	@echo "=== Project Status ==="
+	@echo ""
+	@echo "=== Recent Changes (last 3) ==="
+	@bash $(COS_SCRIPTS)/log-latest.sh --compact 3
+	@echo ""
+	@echo "=== Task Summary ==="
+	@OPEN=$$(grep -c '\- \[ \]' docs/tasks.md 2>/dev/null; true); \
+	WIP=$$(grep -c '\- \[/\]' docs/tasks.md 2>/dev/null; true); \
+	DONE=$$(grep -c '\- \[x\]' docs/tasks.md 2>/dev/null; true); \
+	BLOCKED=$$(grep -c '^- (BLOCKED:' docs/tasks.md 2>/dev/null; true); \
+	echo "Open: $${OPEN:-0} | In-progress: $${WIP:-0} | Done: $${DONE:-0} | Blocked: $${BLOCKED:-0}"; \
+	echo ""; \
+	echo "Next 5 open:"; \
+	grep '\- \[ \]' docs/tasks.md 2>/dev/null | head -5 | sed 's/^- \[ \] /  TODO: /' || echo "  (none)"
+	@echo ""
+	@echo "Next: make task-next"
+
+# ── Task Management ─────────────────────────────────────────────────
+
+.PHONY: task-next
+task-next: ## Show next recommended task
+	@cos task-pick
+
+.PHONY: task-start
+task-start: ## Start a task (TASK=043)
+	@if [ -z "$(TASK)" ]; then echo "Usage: make task-start TASK=<number>"; exit 1; fi
+	@cos task-start TASK-$(TASK)
+
+.PHONY: task-done
+task-done: ## Mark a task done (TASK=043)
+	@if [ -z "$(TASK)" ]; then echo "Usage: make task-done TASK=<number>"; exit 1; fi
+	@cos task-done TASK-$(TASK)
+
+.PHONY: task-block
+task-block: ## Block a task (TASK=024 REASON="why")
+	@if [ -z "$(TASK)" ] || [ -z "$(REASON)" ]; then echo "Usage: make task-block TASK=<number> REASON=\"why it is blocked\""; exit 1; fi
+	@cos task-block TASK-$(TASK) --reason "$(REASON)"
+
+.PHONY: task-create
+task-create: ## Create a new task — use the cos CLI directly
+	@echo "Create tasks with the cos CLI (it needs the required --swimlane / --kind flags):"
+	@echo "  cos task-create --title \"...\" --swimlane <lane> --kind <feature|bug|chore|spike|docs|refactor|test|security>"
+
+.PHONY: task-context
+task-context: ## Show task content + frontmatter (TASK=043) — alias for task-show
+	@if [ -z "$(TASK)" ]; then echo "Usage: make task-context TASK=<number>"; exit 1; fi
+	@cos task-show TASK-$(TASK)
+
+.PHONY: task-show
+task-show: ## Show task content + frontmatter (TASK=043)
+	@if [ -z "$(TASK)" ]; then echo "Usage: make task-show TASK=<number>"; exit 1; fi
+	@cos task-show TASK-$(TASK)
+
+.PHONY: task-list
+task-list: ## Show tasks (STATUS=open|wip|blocked|done|all)
+	@cos board
+
+# ── Scrumban board (Phase L) ──────────────────────────────────────
+# These thin wrappers delegate to the `cos` CLI (cli/board_commands.py).
+# They exist for muscle-memory parity with the legacy `make task-*`
+# commands above — agents and humans can keep using either.
+
+.PHONY: board
+board: ## Show the Scrumban board (ASCII). Use `cos board --web` for browser.
+	@cos board
+
+.PHONY: board-web
+board-web: ## Open the web Scrumban board at http://127.0.0.1:9000
+	@cos board --web
+
+.PHONY: daily
+daily: ## Daily standup summary (yesterday + today candidates + blockers)
+	@cos daily
+
+.PHONY: retro
+retro: ## Weekly retro — throughput + cycle time + emergency count
+	@cos retro
+
+.PHONY: wip
+wip: ## Current WIP counts vs caps from scrumban-config.yaml
+	@cos wip
+
+.PHONY: task-pick
+task-pick: ## Print top candidate tasks to work on next
+	@cos task-pick
+
+.PHONY: task-cancel
+task-cancel: ## Cancel a task (TASK=043)
+	@if [ -z "$(TASK)" ]; then echo "Usage: make task-cancel TASK=<number>"; exit 1; fi
+	@cos task-cancel TASK-$(TASK)
+
+.PHONY: task-log
+task-log: ## Show a task's Work Log (TASK=043)
+	@if [ -z "$(TASK)" ]; then echo "Usage: make task-log TASK=<number>"; exit 1; fi
+	@cos task-log TASK-$(TASK)
+
+.PHONY: task-history
+task-history: ## Show task status transitions (TASK=043)
+	@if [ -z "$(TASK)" ]; then echo "Usage: make task-history TASK=<number>"; exit 1; fi
+	@cos task-history TASK-$(TASK)
+
+.PHONY: task-validate
+task-validate: ## Lint all docs/tasks/*.md against the lean frontmatter schema
+	@cos task-validate
+
+# ── Logging ─────────────────────────────────────────────────────────
+
+.PHONY: log-latest
+log-latest: ## Show last N log entries (N=5)
+	@bash $(COS_SCRIPTS)/log-latest.sh "$(or $(N),1)"
+
+.PHONY: log-write
+log-write: ## Write structured log entry (TYPE+MSG+WHAT+FILES)
+	@if [ -z "$(TYPE)" ] || [ -z "$(MSG)" ]; then echo "Usage: make log-write [TASK=###] TYPE=<type> MSG=\"title\" [WHAT=\"impact\"] [FILES=\"files\"]"; exit 1; fi
+	@bash $(COS_SCRIPTS)/log-write.sh "$(TASK)" "$(TYPE)" "$(MSG)" "$(WHAT)" "$(FILES)"
+
+.PHONY: log-search
+log-search: ## Search changes.log (QUERY="stripe")
+	@if [ -z "$(QUERY)" ]; then echo "Usage: make log-search QUERY=\"search term\" [N=10]"; exit 1; fi
+	@bash $(COS_SCRIPTS)/log-search.sh "$(QUERY)" "$(or $(N),10)"
+
+# ── Docs ────────────────────────────────────────────────────────────
+
+.PHONY: docs-index
+docs-index: ## Index docs/ for RAG retrieval (incremental, mtime-aware)
+	@cos docs-index --project-dir $(CURDIR)
+
+.PHONY: docs-reindex
+docs-reindex: ## Force full re-index of docs/ (after model upgrade)
+	@cos docs-index --project-dir $(CURDIR) --force
+
+.PHONY: task-sync
+task-sync: ## Sync docs/tasks/*.md → coding-os.db (Phase C incremental)
+	@cos task-sync --project-dir $(CURDIR)
+
+.PHONY: task-resync
+task-resync: ## Force full re-sync of every task file (after schema or parser change)
+	@cos task-sync --project-dir $(CURDIR) --force
+
+# Skip in meta-repo (COS_META_REPO=1) — the meta Makefile provides a richer
+# docs-lint that runs link audit + frontmatter. Without this guard GNU make
+# warns "overriding commands for target `docs-lint'" on every invocation.
+ifndef COS_META_REPO
+.PHONY: docs-lint
+docs-lint: ## Lint markdown files in docs/ for SSOT contract compliance
+	@bash $(COS_SCRIPTS)/docs-lint.sh
+endif
+
+.PHONY: docs-nav-fix
+docs-nav-fix: ## Auto-add missing > Nav: breadcrumbs in docs/
+	@bash $(COS_SCRIPTS)/docs-nav-fix.sh
+
+.PHONY: docs-nav-check
+docs-nav-check: ## Report missing Nav breadcrumbs without modifying files
+	@bash $(COS_SCRIPTS)/docs-nav-fix.sh --check
+
+.PHONY: ref
+ref: ## Resolve REF code to file path (REF=PLAYBOOK-BACKEND [READ=1])
+	@if [ -n "$(READ)" ]; then \
+	  bash $(COS_SCRIPTS)/ref-resolve.sh "$(REF)" --read; \
+	else \
+	  bash $(COS_SCRIPTS)/ref-resolve.sh "$(REF)"; \
+	fi
+
+# ── Hooks & Health ──────────────────────────────────────────────────
+
+.PHONY: verify-hooks
+verify-hooks: ## Syntax-check + shellcheck (warning level) on all hook scripts
+	@FAIL=0; for f in $(COS_HOOKS)/*.sh; do bash -n "$$f" 2>&1 || FAIL=1; done; \
+	if [ $$FAIL -eq 1 ]; then echo "ERROR: Hook syntax errors found" >&2; exit 1; \
+	else echo "OK: All hooks pass syntax check"; fi
+	@if command -v shellcheck >/dev/null 2>&1; then \
+	  if shellcheck -S warning $(COS_HOOKS)/*.sh; then \
+	    echo "OK: shellcheck (warning level) clean"; \
+	  else \
+	    echo "ERROR: shellcheck warnings found" >&2; exit 1; \
+	  fi; \
+	else \
+	  echo "WARN: shellcheck not installed — install with 'brew install shellcheck' to enforce" >&2; \
+	fi
+	@MISSING=""; for f in $(COS_HOOKS)/block-*.sh; do \
+	  [ -e "$$f" ] || continue; \
+	  grep -q 'exit 2' "$$f" || MISSING="$$MISSING $$(basename $$f)"; \
+	done; \
+	if [ -n "$$MISSING" ]; then \
+	  echo "ERROR: block-* hook(s) missing 'exit 2' (enforcement disarmed):$$MISSING" >&2; exit 1; \
+	else echo "OK: all block-* hooks contain 'exit 2'"; fi
+
+.PHONY: cos-reindex
+cos-reindex: ## Re-embed all observations/patterns/outcomes (Phase B RAG)
+	@cos reindex --project-dir $(CURDIR) 2>&1 | tail -20
+
+.PHONY: cos-download-model
+cos-download-model: ## Pre-download the embedding model so first run is fast
+	@uv run --extra rag --directory $(COS_ROOT) python -c "import sys; sys.path.insert(0, '$(COS_ROOT)/core/thinking_os'); from embeddings import _get_model; m = _get_model(); print('OK: embedding model loaded' if m else 'WARN: model unavailable')"
+
+.PHONY: cos-health
+cos-health: ## Run coding-os health check
+	@echo "=== Coding OS Health ===" && \
+	echo "State dir: $(COS_STATE_DIR)" && \
+	echo "DB path:   $(COS_DB_PATH)" && \
+	if [ -f "$(COS_DB_PATH)" ]; then \
+	  echo "DB size:   $$(du -h "$(COS_DB_PATH)" | cut -f1)"; \
+	else echo "DB:        not initialized"; fi && \
+	echo "Hooks:     $$(ls $(COS_HOOKS)/*.sh 2>/dev/null | wc -l | tr -d ' ') scripts"
+
+.PHONY: doctor
+doctor: ## Deep health check: scaffold, DB schema, adapter, MCP, cron (cos doctor)
+	@cos doctor --project-dir $(CURDIR)
+
+# ── Hub (web UI + REST API) ──────────────────────────────────────────
+
+.PHONY: hub-start
+hub-start: ## Start the coding-os Hub daemon (port 9188 by default)
+	@cos hub start
+
+.PHONY: hub-stop
+hub-stop: ## Stop the Hub daemon
+	@cos hub stop
+
+.PHONY: hub-status
+hub-status: ## Show Hub daemon status + registered projects
+	@cos hub status
+
+# ── Verification (override in project Makefile) ─────────────────────
+
+ifndef COS_META_REPO
+.PHONY: verify
+verify: ## Run verification for a domain (DOMAIN=backend|frontend|docs|full)
+	@echo "No verification targets defined. Add your own in the project Makefile."
+	@echo "Example:"
+	@echo "  verify:"
+	@echo "    make lint && make test"
+endif
+
+# ── Phase M fast smoke (safe-test) ─────────────────────────────────
+
+.PHONY: safe-test
+safe-test: ## Fast smoke for thinking_os + graph_os + Phase M (≤30s, no network)
+	uv run --extra rag pytest -q \
+	  core/thinking_os/tests/test_db.py \
+	  core/thinking_os/tests/test_cognition_schemas.py \
+	  core/thinking_os/tests/test_cognition_supervisor.py \
+	  core/thinking_os/tests/test_cognition_tools.py \
+	  core/graph_os/tests/test_backend_factory.py \
+	  core/graph_os/tests/test_determinism.py \
+	  core/graph_os/tests/test_backend_parity.py \
+	  tests/test_hooks_phase_m.py \
+	  tests/test_codex_formula_commands.py
+
+# ── Nightly maintenance (CRON A) ────────────────────────────────────
+
+COS_CRON_HOUR ?= 3
+
+ifndef COS_META_REPO
+.PHONY: cron-install
+cron-install: ## Install nightly launchd job (macOS) — daily decay + learn
+	cos cron install --hour $(COS_CRON_HOUR)
+
+.PHONY: cron-uninstall
+cron-uninstall: ## Unload + remove nightly launchd job
+	cos cron uninstall
+
+.PHONY: cron-run
+cron-run: ## Run nightly maintenance now (dry-run safe to test)
+	cos cron run --verbose
+
+.PHONY: cron-status
+cron-status: ## Show last nightly run summary + plist status
+	cos cron status
+endif
+
+# ── Knowledge Graph (graph_os) ──────────────────────────────────────
+
+.PHONY: graph-reindex
+graph-reindex: ## Index codebase into the knowledge graph (incremental)
+	@cos graph-reindex
+
+.PHONY: graph-query
+graph-query: ## Semantic symbol search (QUERY="find all auth handlers")
+	@if [ -z "$(QUERY)" ]; then echo "Usage: make graph-query QUERY=\"...\""; exit 1; fi
+	@cos graph-query "$(QUERY)"
+
+.PHONY: graph-context
+graph-context: ## Callers + callees for a symbol (SYM=function_name)
+	@if [ -z "$(SYM)" ]; then echo "Usage: make graph-context SYM=<symbol>"; exit 1; fi
+	@cos graph-context "$(SYM)"
+
+.PHONY: graph-impact
+graph-impact: ## Blast-radius risk analysis for a symbol (SYM=function_name)
+	@if [ -z "$(SYM)" ]; then echo "Usage: make graph-impact SYM=<symbol>"; exit 1; fi
+	@cos graph-impact "$(SYM)"
+
+.PHONY: graph-contracts
+graph-contracts: ## List all HTTP / MCP / gRPC / event handlers in the codebase
+	@cos graph-contracts
+
+.PHONY: graph-entrypoints
+graph-entrypoints: ## Rank and show main / cli / http / cron / test entry points
+	@cos graph-entrypoints
+
+.PHONY: graph-communities
+graph-communities: ## Detect Louvain communities (logical module groups)
+	@cos graph-communities
+
+.PHONY: graph-export
+graph-export: ## Export the graph (FORMAT=json|mermaid|dot, default json)
+	@cos graph-export $(if $(FORMAT),--format $(FORMAT),)
+
+.PHONY: graph-stats
+graph-stats: ## Show knowledge graph DB statistics
+	@cos graph-stats
+
+# ── Help ────────────────────────────────────────────────────────────
+
+.PHONY: help
+help: ## Show all commands
+	@echo "=== coding-os Commands ==="
+	@echo ""
+	@echo "Session:   make session-init"
+	@echo "Tasks:     make task-start TASK=### | task-done ... | task-block ... | task-cancel ... | task-show ..."
+	@echo "Board:     make board | daily | retro | wip | task-pick | task-validate"
+	@echo "Graph:     make graph-reindex | graph-query QUERY=... | graph-context SYM=... | graph-impact SYM=..."
+	@echo "Logging:   make log-latest [N=5] | log-write TYPE=... MSG=... | log-search QUERY=..."
+	@echo "Health:    make doctor | cos-health | verify-hooks | hub-start | hub-status"
+	@echo "Cron:      make cron-install | cron-run | cron-status"
+	@echo ""
+	@echo "All targets:"
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*## "}; {printf "  %-22s %s\n", $$1, $$2}'

templates/_base/base.yaml

@@ -0,0 +1,59 @@
+version: 1
+id: base
+label: "Coding OS Base"
+
+# Default substitutions. These are overridden when stacks are installed:
+#  - STACK / DOMAIN_ROUTES / SKILL_ROUTES / ENGINEERING_RULE_ROUTING /
+#    TOOL_ROUTING_IMPL come from `_derive_substitutions` in the aggregator
+#    (joined from each installed stack).
+#  - VERIFY_BACKEND_* and VERIFY_FRONTEND_* are supplied by stacks that
+#    declare them (e.g. django stack sets VERIFY_BACKEND_GLOB). When no
+#    such stack is present, the "(none)" values below are used.
+#  - PROJECT_NAME is resolved from ${auto:project_name}.
+#  - DATE is resolved from ${auto:today}.
+substitutions:
+  PROJECT_NAME: "${auto:project_name}"
+  PROJECT_DESCRIPTION: "A software project managed by coding-os"
+  DATE: "${auto:today}"
+  DOMAIN: "ALL"
+  STACK: "Polyglot"
+  DOMAIN_ROUTES: "Any code change → `docs/governance/agent-workflow.md` § Domain Classification"
+  SKILL_ROUTES: "Any code → `clean-code`"
+  ENGINEERING_RULE_ROUTING: "(no engineering rules installed — add via `coding-os add-template`)"
+  VERIFY_BACKEND_GLOB: "(none)"
+  VERIFY_BACKEND_SUITES: "(none)"
+  VERIFY_BACKEND: "`make verify`"
+  VERIFY_FRONTEND_GLOB: "(none)"
+  VERIFY_FRONTEND_SUITES: "(none)"
+  VERIFY_FRONTEND: "(none)"
+  VERIFY_DOCS_GLOB: "`docs/`"
+  VERIFY_DOCS_SUITES: "docs-lint"
+  VERIFY_DOCS: "`make docs-lint`"
+  VERIFY_HOOKS_GLOB: "`.coding-os/hooks/` or `src/core/hooks/`"
+  TOOL_ROUTING_IMPL: "(no stack-specific tools installed)"
+  SSOT_MAP: "See `docs/_meta/foundation-map.md` for all REF shortcodes and SSOT locations."
+  QUICK_ROUTING: "- See `docs/governance/agent-workflow.md` for routing without playbooks"
+  STACK_REF_CODES: ""
+
+skills: [thinking_os, clean-code, codebase-explorer, graph-explorer, search, task-driver, testing-strategy, observability, incident-response]
+
+# AGENTS.md section registry — order determines rendered position.
+# Each entry references a fragment file relative to `src/templates/_base/`.
+agents_md_sections:
+  - {id: header,               order: 10, template: "fragments/header.md.tmpl"}
+  - {id: identity,             order: 20, template: "fragments/identity.md.tmpl"}
+  - {id: project-anatomy,      order: 25, template: "fragments/anatomy-map.md.tmpl"}
+  - {id: principles,           order: 30, template: "fragments/principles.md.tmpl"}
+  - {id: core-loop,            order: 40, template: "fragments/core-loop.md.tmpl"}
+  - {id: verification-matrix,  order: 50, template: "fragments/verification-matrix.md.tmpl"}
+  - {id: engineering-routing,  order: 60, template: "fragments/engineering-routing.md.tmpl"}
+  - {id: tool-routing,         order: 70, template: "fragments/tool-routing.md.tmpl"}
+  - {id: retrieval-routing,    order: 75, template: "fragments/retrieval-routing.md.tmpl"}
+  - {id: skills,               order: 80, template: "fragments/skills.md.tmpl"}
+  - {id: context-discipline,   order: 90, template: "fragments/context-discipline.md.tmpl"}
+  - {id: stop-conditions,      order: 100, template: "fragments/stop-conditions.md.tmpl"}
+  - {id: session-handoff,      order: 110, template: "fragments/session-handoff.md.tmpl"}
+  - {id: ssot-map,             order: 120, template: "fragments/ssot-map.md.tmpl"}
+  - {id: task-logging,         order: 130, template: "fragments/task-logging.md.tmpl"}
+  - {id: task-authoring,       order: 135, template: "fragments/task-authoring.md.tmpl"}
+  - {id: subagent-dispatch,    order: 140, template: "fragments/subagent-dispatch.md.tmpl"}

templates/_base/coding-os.yaml.template

@@ -0,0 +1,39 @@
+# coding-os configuration
+# Generated by: coding-os init
+version: "1.0"
+
+# Installed agent adapters
+agents: []
+
+# Stack templates applied
+templates: []
+
+# State directory for session files, gate, etc.
+state_dir: .coding-os
+
+# Code file extensions to enforce gates on
+code_extensions: [py, ts, tsx, js, jsx, go, rs, java, kt, rb, php]
+
+# Domain verification commands
+verify: {}
+#  backend: "make lint-backend && make test-backend"
+#  frontend: "cd frontend && npm run lint"
+#  docs: "make docs-lint"
+
+# Files that should not be edited by agents
+protected_files: []
+#  - "*/migrations/*.py"
+#  - "manage.py"
+
+# Web UI + Hub daemon settings (cos web / cos hub).
+# - web.port        port for the unified API + SPA.
+# - web.autostart   start the per-project server on the next session start.
+# - hub.enabled     register this project in the global hub at ~/.coding-os/.
+# - hub.port        port the global hub listens on (default 9188).
+web:
+  port: 9188
+  autostart: false
+
+hub:
+  enabled: true
+  port: 9188

templates/_base/dimension-registry.template.md

@@ -0,0 +1,68 @@
+---
+description: Dimension Type Registry — maps task dimensions to doc files for Classify phase Read List
+globs: "**/*"
+alwaysApply: true
+---
+
+# Dimension Type Registry
+
+Use during Classify phase to build your Read List. Each file must have a REASON from your Dimension Map. Fallback: if no row matches, search `docs/` with Grep/Glob.
+
+**Backend** — always include `engineering/backend-rules.md`
+
+- Schema/models → `PRD/12-schema-erd.md` + `PRD/12c-indexing-strategy.md`
+- Business logic → `PRD/08-functional-requirements.md`
+- API contract → `api-contracts/{domain}.md` + `PRD/09-data-model-apis.md`
+- Auth/security → `architecture/04a-auth-security.md`
+- Payments → `architecture/08-payment-architecture.md`
+- Scheduled tasks → `architecture/06c-scheduled-tasks.md`
+- Email/notifications → `architecture/07-email-notifications.md`
+- Analytics → `architecture/09-analytics-posthog.md`
+- Realtime/SSE → `architecture/11-realtime-sse.md`
+- Blog/i18n → `architecture/10-blog-content-i18n.md`
+- Performance → `engineering/backend-rules.md` § Performance
+- Error handling → `engineering/backend-rules.md` § Error Handling Policy
+- Testing → `engineering/backend-rules.md` § Edge Case Testing
+- App structure → `architecture/03a-monorepo-layout.md`
+- Dependencies → `architecture/02a-core-dependencies.md`
+
+**Frontend** — always include `engineering/frontend-rules.md`
+
+- Page layout → `pages-content-spec/{page}.md`
+- API integration → `api-contracts/{domain}.md`
+- Design/styling → `STYLE_GUIDE.md` + relevant `docs/design/` sub-file
+- Business logic → `PRD/08-functional-requirements.md`
+- Error states → `engineering/frontend-rules.md` § Error Handling
+- Responsive → `engineering/frontend-rules.md`
+- i18n → `engineering/i18n-policy.md`
+- Accessibility → `engineering/accessibility-web.md`
+- Rendering → `engineering/frontend-rendering-rules.md`
+- Testing → `engineering/frontend-rules.md` § Edge Case Testing
+
+**Content & SEO** — always include exact page spec
+
+- Content/copy → `pages-content-spec/{page}.md`
+- SEO metadata → `PRD/04-information-architecture.md`
+- Blog/i18n → `architecture/10-blog-content-i18n.md` + `engineering/i18n-policy.md`
+- Tone/voice → `engineering/copywriting-standard.md`
+
+**Infrastructure**
+
+- Docker → `architecture/06a-infrastructure.md` + `architecture/06b-docker-services.md`
+- CI/CD → `architecture/06a-infrastructure.md`
+- Deployment → `architecture/06-deployment-infra.md`
+- Logging → `engineering/logging-standards.md`
+
+**Docs & Governance** — always include `AGENTS.md` + `governance/docs-system.md`
+
+- Task system → `governance/task-lifecycle.md`
+- Doc structure → `governance/docs-system.md`
+- Workflow → `workflow-docs/workflow-guide.md`
+- Formatting → `engineering/formatting-rules.md`
+
+**Security Overlay** (add to any domain)
+
+- Auth/JWT → `architecture/04a-auth-security.md`
+- CSRF/CORS → `architecture/04b-web-security.md`
+- Downloads → `architecture/04c-download-security.md`
+- Compliance → `architecture/04d-compliance.md`

templates/_base/domain-config.template.json

@@ -0,0 +1,46 @@
+{
+  "refs_by_tag": {
+    "DOCS": ["REF:PLAYBOOK-DOCS", "REF:DOCS-SYSTEM", "REF:TASK-LIFECYCLE", "REF:TASKS", "REF:CHANGES"],
+    "BACKEND": ["REF:PLAYBOOK-BACKEND", "REF:TASKS", "REF:CHANGES"],
+    "FRONTEND": ["REF:PLAYBOOK-FRONTEND", "REF:TASKS", "REF:CHANGES"],
+    "UI": ["REF:PLAYBOOK-FRONTEND", "REF:TASKS", "REF:CHANGES"],
+    "CONTENT": ["REF:PLAYBOOK-CONTENT", "REF:TASKS", "REF:CHANGES"],
+    "SEO": ["REF:PLAYBOOK-CONTENT", "REF:TASKS", "REF:CHANGES"],
+    "FULL-STACK": ["REF:PLAYBOOK-BACKEND", "REF:PLAYBOOK-FRONTEND", "REF:TASKS", "REF:CHANGES"],
+    "ALL": ["REF:PLAYBOOK-BACKEND", "REF:PLAYBOOK-FRONTEND", "REF:TASKS", "REF:CHANGES"],
+    "INFRA": ["REF:TASKS", "REF:CHANGES"],
+    "LAUNCH": ["REF:PLAYBOOK-FRONTEND", "REF:PLAYBOOK-BACKEND", "REF:TASKS", "REF:CHANGES"],
+    "SECURITY": ["REF:PLAYBOOK-BACKEND", "REF:TASKS", "REF:CHANGES"]
+  },
+  "default_refs": ["REF:PLAYBOOK-RESEARCH", "REF:TASKS", "REF:CHANGES"],
+  "domain_map": {
+    "DOCS": "DOCS",
+    "BACKEND": "BACKEND",
+    "FRONTEND": "FRONTEND",
+    "UI": "FRONTEND",
+    "AUTH": "AUTH",
+    "PAYMENTS": "PAYMENTS",
+    "INFRA": "INFRA",
+    "CONTENT": "CONTENT",
+    "SEO": "CONTENT",
+    "FULL-STACK": "FULL-STACK",
+    "ALL": "ALL",
+    "LAUNCH": "LAUNCH",
+    "SECURITY": "SECURITY"
+  },
+  "default_domain": "ALL",
+  "playbook_map": {
+    "DOCS": "docs/playbooks/docs-governance.md",
+    "FRONTEND": "docs/playbooks/frontend-ui.md",
+    "UI": "docs/playbooks/frontend-ui.md",
+    "BACKEND": "docs/playbooks/backend-api.md",
+    "CONTENT": "docs/playbooks/content-seo.md",
+    "SEO": "docs/playbooks/content-seo.md",
+    "FULL-STACK": "docs/playbooks/backend-api.md",
+    "ALL": "docs/playbooks/backend-api.md",
+    "INFRA": "docs/playbooks/backend-api.md",
+    "LAUNCH": "docs/playbooks/frontend-ui.md",
+    "SECURITY": "docs/playbooks/backend-api.md"
+  },
+  "default_playbook": "docs/playbooks/research-validation.md"
+}

templates/_base/fragments/anatomy-map.md.tmpl

@@ -0,0 +1,11 @@
+## Project Anatomy
+
+Top-level subtrees of this project (SSOT: `docs/engineering/project-anatomy.md`). **One owner per subtree.** Cross-language types flow through `src/shared/contracts/` only — never direct cross-stack imports. Same-language code reused by a second service is promoted to `src/shared/<lang>/` (reuse-first).
+
+| Subtree | Owner | Convention |
+|---|---|---|
+{% for entry in anatomy -%}
+| `{{ entry.root }}` | {{ entry.label }} ({{ entry.category }}) | {{ entry.notes | replace('\n', ' ') | replace('|', '\\|') }} |
+{% endfor -%}
+| `src/shared/contracts/` | cross-language boundary | OpenAPI / proto / json-schema — the only cross-stack channel |
+| `src/shared/<lang>/` | same-language shared code | promote reused code here (reuse-first) |

templates/_base/fragments/context-discipline.md.tmpl

@@ -0,0 +1,3 @@
+## Context Discipline
+
+Note findings once, reference by path. Extract key result, discard raw output. Use `log-latest`/`log-search` not `cat changes.log`. Answer directly without restating background.

templates/_base/fragments/core-loop.md.tmpl

@@ -0,0 +1,52 @@
+## Request Routing
+
+**Gate 1 — Complexity Gate** (`$COS_STATE_DIR/rules/thinking_os.md`): Q1 Cynefin (CLEAR/COMPLICATED/COMPLEX/CHAOTIC) → Q2 Dimension count. Record classification.
+
+**Gate 2 — Request Type**: A (Question) → answer directly or Zoom. B (Task) → Core Loop. C (Ad-hoc) → trivial: inline{% if modules.tasks %}, else `make task-create` first{% else %}, else treat as a Task{% endif %}. D (Audit) → verify command or Zoom first. Details: `docs/governance/agent-workflow.md`
+
+## Core Loop
+
+Five phases: **Initialize → Classify → Orient → Plan → Execute → Verify & Close**. Think before reading, read before coding.
+
+### Initialize
+
+1. `make session-init` (ONCE per session).{% if modules.tasks %} 2. `make task-start TASK=<num>`.{% endif %}
+
+### Classify (dry — zero file reads)
+
+Use the SessionStart "Classify Read List" card (scoped to THIS project's installed stacks) to build the Read List; `$COS_STATE_DIR/rules/dimension-registry.md` is the full all-stacks reference:
+
+1. **Complexity Gate** — record: `bash $COS_STATE_DIR/hooks/write-state.sh $COS_STATE_DIR/.thinking_os-gate "COMPLICATED 3"`
+2. **Domain Route** — {{ substitutions.DOMAIN_ROUTES }}
+3. **Dimension Map** — per dimension: name, domain, depth (D/M/L), phase.
+4. **Read List** — from registry, each file with REASON. Do NOT read entire pack.
+
+For **CLEAR** 1-dim: skip to Execute. Output: Classify Checkpoint in task Notes.
+
+### Orient (targeted reads + memory)
+
+1. **Targeted Read** — ONLY files from Read List. Note findings in task Notes. [P3]
+{% if modules.memory %}2. **Memory Check** (500tok max): `cos_search` → `cos_learn_suggest` → `cos_details` if conf>0.7.
+{% endif %}3. **Repo Search** — Grep/Glob existing code. Diff against spec if found. [P1, P2]
+4. **Model Update** — new dimensions? Reframe trigger → back to Classify.
+
+### Plan (deep analysis — no new reads)
+
+1. **Invoke domain skill**: {{ substitutions.SKILL_ROUTES }}
+2. **Per dimension**: current state → target → gap → risk.
+3. **Action Plan** — ordered steps. For COMPLICATED+: write Problem Framing to Notes, record `bash $COS_STATE_DIR/hooks/write-state.sh $COS_STATE_DIR/.zoom-checkpoint "PROBLEM_FRAMED"`.
+
+For **CLEAR**: skip Plan.
+
+### Execute (implement only)
+
+1. Implement smallest correct change. [P1, P4]
+2. On-demand read ONLY if new question arises.
+3. Continuous monitoring — reframe trigger → back to Classify.
+
+### Verify & Close
+
+1. Run domain verification commands (see Verification Matrix below).{% if modules.tasks %} Fail 2x → `make task-block`.{% else %} Fail 2x → stop and surface to the user.{% endif %} [P6]
+{% if modules.tasks %}2. `make task-done TASK=<num> TYPE=<type> MSG="..." WHAT="..." FILES="..."`. Always WHAT+FILES. [P6]
+{% endif %}{% if modules.observability or modules.memory %}{% if modules.tasks %}3{% else %}2{% endif %}. {% if modules.observability %}`cos_metric_record` outcome (auto-recorded by session-end.sh — manual call optional). {% endif %}{% if modules.memory %}Every 10 tasks: `cos_learn_extract`.{% endif %}
+{% endif %}

templates/_base/fragments/engineering-routing.md.tmpl

@@ -0,0 +1,3 @@
+## Engineering Rule Routing
+
+{{ substitutions.ENGINEERING_RULE_ROUTING }}

templates/_base/fragments/header.md.tmpl

@@ -0,0 +1,6 @@
+# AGENTS — Routing & Execution Protocol
+
+Purpose: Root entry point for every agent session in this monorepo.
+Read when: Starting any task or re-grounding after context loss.
+Skip when: A linked playbook already covers the active task and no routing decision is needed.
+Read next: `docs/00-index.md`, then the matching playbook in `docs/playbooks/`

templates/_base/fragments/identity.md.tmpl

@@ -0,0 +1,3 @@
+## Identity
+
+{{ substitutions.PROJECT_NAME }}: {{ substitutions.PROJECT_DESCRIPTION }}. Stack: {{ substitutions.STACK }}.

templates/_base/fragments/principles.md.tmpl

@@ -0,0 +1,3 @@
+## Principles
+
+P1. SSOT-first — no parallel truths. P2. Source-grounded — trace to SSOT. P3. Minimal-context — 3-10 files max. P4. Diff-first — preserve unrelated content. P5. User-runs-production. P6. Log-everything. P7. No-guessing — log unknowns to questions.md.