coding-os 0.3.2__py3-none-any.whl

core/skills/typescript/references/type-system.md

@@ -0,0 +1,86 @@
+<!-- domain:FRONTEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# TypeScript Type System — Narrowing, Unions, Generics
+
+> P: The type-level moves that make illegal states unrepresentable and bugs compile errors.
+> R: Modeling a domain, narrowing a value, or writing a reusable generic.
+> S: tsconfig flags — see [strictness.md](strictness.md).
+> N: [SKILL.md](../SKILL.md), [typescript-checklist.md](../assets/typescript-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Narrowing — let control flow refine the type
+
+```typescript
+function len(x: string | string[]): number {
+  if (typeof x === "string") return x.length;   // x: string here
+  return x.length;                                // x: string[] here
+}
+```
+
+The compiler narrows by `typeof`, `instanceof`, `in`, truthiness, equality, and
+**user-defined type guards** (`function isUser(x: unknown): x is User`). A guard
+that returns `x is T` teaches the compiler to narrow at every call site — far
+safer than `as T`.
+
+## Discriminated unions + exhaustiveness
+
+```typescript
+type Shape =
+  | { kind: "circle"; r: number }
+  | { kind: "rect"; w: number; h: number };
+
+function area(s: Shape): number {
+  switch (s.kind) {
+    case "circle": return Math.PI * s.r ** 2;
+    case "rect":   return s.w * s.h;
+    default: { const _exhaustive: never = s; return _exhaustive; }
+  }
+}
+```
+
+The `never` default makes adding a new `kind` a **compile error** until you handle
+it — the type system enforces completeness. Model every "one of N states" this way.
+
+## Generics — link types, don't decorate
+
+```typescript
+function map<T, U>(arr: readonly T[], f: (x: T) => U): U[] { return arr.map(f); }
+function prop<T, K extends keyof T>(o: T, k: K): T[K] { return o[k]; }
+```
+
+A generic is earned when a type parameter appears in **two** positions and links
+them (input → output). `K extends keyof T` constrains the key to the object's
+real keys, so `prop(user, "naem")` is a compile error.
+
+## Utility & mapped types — reach for built-ins first
+
+| Need | Built-in |
+|---|---|
+| all optional | `Partial<T>` |
+| all required | `Required<T>` |
+| subset of keys | `Pick<T, "a" \| "b">` |
+| drop keys | `Omit<T, "id">` |
+| dict | `Record<K, V>` |
+| function's return | `ReturnType<typeof fn>` |
+| element of array | `T[number]` |
+
+```typescript
+// derive types from a single source instead of redeclaring
+const ROLES = ["admin", "user", "guest"] as const;
+type Role = typeof ROLES[number];                 // "admin" | "user" | "guest"
+```
+
+Deriving types from a `const` (or a zod schema via `z.infer`) keeps one source of
+truth — the type can't drift from the value. Mapped + conditional types
+(`{ [K in keyof T]: ... }`, `T extends U ? X : Y`) build on these; reach for them
+only when a built-in doesn't fit.
+
+## `satisfies` — check without widening
+
+```typescript
+const config = { port: 8080, host: "0.0.0.0" } satisfies Record<string, string | number>;
+config.port;   // still typed as number (not widened to string | number)
+```
+
+`satisfies` validates a literal against a type while keeping the narrow inferred
+type — better than `: Type` (which widens) or `as Type` (which doesn't check).

core/skills/typescript/scripts/check_tsconfig.py

@@ -0,0 +1,92 @@
+"""Audit a tsconfig.json for the strictness flags that catch real bugs.
+
+PURPOSE:      Flag a tsconfig that leaves the type checker blindfolded — one
+              summary instead of eyeballing nested compilerOptions.
+INPUT:        tsconfig path (default tsconfig.json) or --file. [--json]
+OUTPUT:       Findings on stderr; "clean"/"N finding(s)" on stdout. Exit 0
+              clean, 1 findings, 2 usage/parse error.
+DEPENDENCIES: stdlib only. Tolerates JSONC (comments, trailing commas).
+NOTES:        `extends` is NOT resolved — a flag may be inherited; the script
+              says so rather than guess. Pure audit() is unit-testable.
+              Spec: docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# flag -> (required_value, why)
+REQUIRED = {
+    "strict": (True, "the umbrella flag — without it null-safety + implicit-any are off"),
+}
+RECOMMENDED = {
+    "noUncheckedIndexedAccess": (True, "makes arr[i] honestly T | undefined"),
+    "noImplicitOverride": (True, "catches a method that no longer overrides its base"),
+    "exactOptionalPropertyTypes": (True, "distinguishes missing from undefined"),
+    "noFallthroughCasesInSwitch": (True, "catches a missing break/return in a switch"),
+}
+
+
+def strip_jsonc(text: str) -> str:
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.DOTALL)  # block comments
+    text = re.sub(r"(^|\s)//[^\n]*", r"\1", text)  # line comments
+    text = re.sub(r",(\s*[}\]])", r"\1", text)  # trailing commas
+    return text
+
+
+def load_tsconfig(text: str) -> dict:
+    data = json.loads(strip_jsonc(text))
+    if not isinstance(data, dict):
+        raise ValueError("tsconfig root must be an object")
+    return data
+
+
+def audit(config: dict) -> list[str]:
+    opts = config.get("compilerOptions", {})
+    findings: list[str] = []
+    for flag, (want, why) in REQUIRED.items():
+        if opts.get(flag) != want:
+            findings.append(f"{flag} != {json.dumps(want)} — {why}")
+    for flag, (want, why) in RECOMMENDED.items():
+        if opts.get(flag) != want:
+            findings.append(f"{flag} not set — {why}")
+    if "extends" in config and findings:
+        findings.append(
+            f"note: this config extends {config['extends']!r}; "
+            "a flag above may be inherited — verify the resolved config"
+        )
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("path", nargs="?", default="tsconfig.json")
+    parser.add_argument("--file", default=None)
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    target = args.file or args.path
+    try:
+        findings = audit(load_tsconfig(Path(target).read_text(encoding="utf-8")))
+    except FileNotFoundError:
+        print(f"error: {target} not found", file=sys.stderr)
+        return 2
+    except (json.JSONDecodeError, ValueError) as exc:
+        print(f"error: {target}: {exc}", file=sys.stderr)
+        return 2
+
+    for f in findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": findings, "count": len(findings)}))
+    else:
+        print("clean" if not findings else f"{len(findings)} finding(s)")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/typescript/versions.json

@@ -0,0 +1,9 @@
+{
+  "typescript": {
+    "ecosystem": "npm",
+    "package": "typescript",
+    "version": "6.0.3",
+    "source": "https://www.npmjs.com/package/typescript",
+    "checked": "2026-06-05"
+  }
+}

core/subsystems.yaml

@@ -0,0 +1,202 @@
+# Subsystem (module) registry — TASK-349. VSCode-style modularity: the kernel
+# is always on; optional modules toggle per project via the state API
+# (cli/subsystems.py → $COS_STATE_DIR/subsystems-state.json).
+#
+# Every hook id below MUST exist in src/core/hooks/registry.yaml
+# (tests/test_cli.py::TestSubsystems cross-validates). Safety-category hooks
+# are non-disableable regardless of module membership (TASK-256 layer);
+# `kernel: true` additionally pins the whole module.
+#
+# Schema: id, label, hint, kernel, hooks[], tools[], skills[], commands[], rules[], depends_on[], hidden.
+# `hint` = one-line "when to enable" surfaced in the Hub Config → Modules tab (discovery UX).
+# `tools` trailing '*' = MCP prefix family (tools/_shared.py gate).
+# `commands` = slash-command stems (core/commands/<name>.md) UNAMBIGUOUSLY owned
+# by this module; disabling it unlinks them from the adapter commands dir
+# (ref-counted) via module_commands.cascade_module_commands (TASK-481). Always-on
+# commands (classify/verify/review/diagnose/new-project) are never listed.
+# `skills` = domain-skill names UNAMBIGUOUSLY owned by this module; disabling it
+# unlinks them (ref-counted, override-aware) via skill_commands.cascade_module_skills
+# (TASK-475). Always-on skills (clean-code, thinking_os, search) are never listed.
+# `rules` = core rule filenames (src/core/rules/<name>.md) UNAMBIGUOUSLY owned by
+# this module; disabling it unlinks them from the adapter rules dir (ref-counted)
+# via module_commands.cascade_module_rules. Cross-cutting rules (git-workflow,
+# anti-overengineering, api-contract-discipline, thinking_os, transparency-banner,
+# test-discipline) and derived rules (dimension-registry, skill-enforcement) are
+# never listed. A disabled module's rule also self-guards as inert (defense-in-depth).
+# `hidden: true` keeps a reserved id stable but drops it from every toggle UI.
+version: 1
+
+# Profiles (TASK-509): named curated module sets for `cos init --profile <name>`.
+# Each profile lists the modules it DISABLES (everything else stays on); the
+# resolver feeds that union through the existing --disable-module path into
+# subsystems-state.json. Progressive disclosure / least-surface-by-default — a
+# fresh consumer gets a leaner MCP tool surface; `full` is the all-on escape
+# (byte-identical to a no-profile init). Disabled lists must stay dependency-safe
+# (never drop a module another profile-enabled module depends on).
+default_profile: standard
+profiles:
+  lite: { disabled: [docs, tasks, graph, memory, cognition, observability, hub-extras, cicd] }  # kernel-only: discipline + safety, ~zero MCP tools (MCP-averse adopters)
+  core: { disabled: [memory, cognition, observability, cicd] }   # kernel + docs + tasks + graph
+  standard: { disabled: [cognition, cicd] }                      # + memory + observability (default)
+  full: { disabled: [] }                                         # everything (today's behaviour)
+
+modules:
+  - id: kernel
+    label: "Kernel — state, env, session lifecycle + always-on safety/enforcement discipline"
+    hint: "Always on — lifecycle + the non-negotiable safety/enforcement discipline surface."
+    kernel: true
+    # Lifecycle + the non-negotiable discipline surface. Safety-category hooks
+    # are non-disableable regardless of module (project_overrides filters them);
+    # pinning enforcement + meta-governance here makes the registry↔module map
+    # total so every hook has an owner (audit F9), with none toggleable-away.
+    hooks:
+      - session-context
+      - session-end
+      - classify-task-mode
+      - agent-presence
+      - track-skill
+      - inject-mcp-caller-session
+      # safety (never disableable — category-gated in project_overrides)
+      - block-secrets
+      - block-dangerous-commands
+      - block-bad-patterns
+      - block-hardcoded-literals
+      - block-migration-conflict
+      - block-protected-files
+      - block-uv-heredoc
+      - check-mcp-extras
+      - enforce-task-transition
+      - enforce-wip-limit
+      - lint-task
+      - validate-task-frontmatter
+      # core enforcement discipline (always on)
+      - branch-guard
+      - block-shared-tree-edit
+      - pr-reap
+      - nudge-git-mode
+      - enforce-commit-message
+      - enforce-scaffold-boundary
+      - enforce-skill
+      - enforce-template
+      - enforce-verify
+      - enforce-zoom
+      - search-enforce-inventory
+      - search-verify-remaining
+      - test-governor
+      - thinking_os-gate
+      # meta-repo governance (coding-os-internal; no-ops in consumers)
+      - check-agents-md-refs
+      - check-agents-md-size
+      - remind-dogfood
+      - warn-destructive-edit
+      - warn-diff-size
+    # Always-on tools that match no module pattern, so the gate never removes them
+    # (auditable floor — the tool gate skips kernel by design). cos_classify_prompt
+    # (Record Gate) + cos_health (diagnostic) are kernel by design; cos_traceability
+    # is cross-cutting; cos_failure_pattern_query reads cognition-populated data and
+    # is a candidate to move to `cognition` later (rank-11 follow-up).
+    tools: [cos_classify_prompt, cos_health, cos_traceability, cos_failure_pattern_query]
+    depends_on: []
+
+  - id: docs
+    label: "Docs system — SSOT docs, doc search, doc hygiene"
+    hint: "Enable for SSOT doc search (cos_doc_*) + the doc-anchor / docs-first discipline."
+    kernel: false
+    hooks: [enforce-doc-anchor, enforce-doc-sync, nudge-docs-first, check-doc-size, auto-regen-doc-index, auto-reindex-docs]
+    tools: ["cos_doc_*"]
+    depends_on: []
+
+  - id: tasks
+    label: "Task system — Scrumban board, lifecycle, work logs"
+    hint: "Enable for the Scrumban board, task lifecycle gates, and work logs (cos_task_*)."
+    kernel: false
+    hooks: [enforce-task-start, enforce-task-body, nudge-task-discovery, warn-abandoned-task, nudge-reentry, remind-daily, auto-task-sync, sync-task-current, link-commit-to-task, reclaim-sweep, capture-work-log]
+    tools: ["cos_task_*", cos_work_log_append]
+    skills: [task-driver]
+    commands: [board, daily, retro, task]
+    # tasks→docs is NOT a code dependency (board_os imports nothing from docs); it
+    # is enforcement-locality — the docs-first code-write BLOCK gate (enforce-doc-anchor)
+    # lives in the docs module and consumes each task's Read First, so tasks-on/docs-off
+    # would silently strip that gate. Keep hard.
+    depends_on: [docs]
+    depends_on_reason: "Enforcement-locality: the docs-first code-write gate (enforce-doc-anchor) lives in the docs module and consumes each task's Read First — tasks-on/docs-off would silently strip that gate."
+
+  - id: graph
+    label: "Knowledge graph — code/doc graph, structural queries"
+    hint: "Enable for structural code/doc queries — callers, blast radius, rename (cos_graph_*)."
+    kernel: false
+    hooks: [enforce-graph-context, enforce-graph-first-read, enforce-rename-plan, nudge-graph-os, warn-graph-empty, verify-rename-callers, auto-graph-reconcile-shell]
+    tools: ["cos_graph_*"]
+    skills: [graph-explorer, graph-os-authoring]
+    depends_on: []
+
+  - id: memory
+    label: "Agent memory — observations, learning, recall"
+    hint: "Enable for cross-session recall + the learning loop (cos_search, cos_learn_*)."
+    kernel: false
+    hooks: [enforce-memory-check, capture-observation, jit-recall, nudge-learn-narrative, remind-learn-validate, auto-brain-decay, drain-embedding-outbox, check-capture-worked, ensure-agent-memory-link, sync-agent-memory]
+    tools: [cos_search, cos_observation_record, cos_timeline, cos_details, "cos_learn_*", "cos_retrieval_*", cos_promote, cos_digest_regenerate]
+    skills: [agent-memory]
+    commands: [memory-search]
+    rules: [memory.md]
+    depends_on: []
+
+  - id: cognition
+    label: "Cognition — role composition, reasoning primers + workflow nudges"
+    hint: "Enable for role-chain composition + reasoning primers (adds per-session token cost)."
+    kernel: false
+    # The optional reasoning-assist surface: session primers, role chain
+    # composition, and soft nudges. Toggle off to cut the per-session token
+    # cost of the cognitive scaffolding (hard gates stay in kernel).
+    hooks: [advance-role, auto-compose-roles, enforce-anti-ambiguity, nudge-model-routing, nudge-thinking-os, rules-primer, session-skill-primer, track-backtrack, track-discovery, nudge-reuse-first, regen-reminder, test-first-reminder]
+    # The reasoning-assist tool surface: role composition, formula dispatch,
+    # supervision, model/skill routing, situation detect. cos_classify_prompt
+    # (Record Gate, core loop) + cos_health (diagnostic) stay KERNEL by design.
+    tools: ["cos_dispatch_*", "cos_route_*", cos_compose_chain, cos_supervise, cos_supervise_record_output, cos_role_info, cos_situation_detect, cos_takeover, cos_analyze_task, cos_ambiguity_check, cos_backtrack_log, cos_discovery]
+    # /compose is the role-chain composition surface; /role-* commands map from
+    # thinking_os/agents/ (a separate source) and stay always-on (Rule 22 — not
+    # worth the agents/ source-mapping to gate a low-frequency advanced surface).
+    commands: [compose]
+    rules: [model-routing.md]
+    depends_on: []
+
+  - id: observability
+    label: "Observability — session tracing, transcript + tool-failure capture"
+    hint: "Enable for session tracing, metrics, and tool-failure / transcript capture (cos_metric_*)."
+    kernel: false
+    hooks: [auto-trace-rotate, capture-tool-failure, record-verify-auto, snapshot-transcript]
+    # Session metrics, log query, trajectory snapshots, presence. Internal
+    # callers (task-done outcome recording, hooks) use the impl functions, not
+    # these MCP tools, so gating is surface-only — it never breaks recording.
+    tools: ["cos_metric_*", "cos_trajectory_*", cos_log_query, cos_presence_query]
+    depends_on: []
+
+  - id: hub-extras
+    label: "Hub extras — web UI conveniences beyond the API core"
+    hint: "Enable for web-UI conveniences (ensure-hub-up, MCP-down banner) beyond the API core."
+    kernel: false
+    hooks: [ensure-hub-up, warn-mcp-down]
+    tools: []
+    depends_on: []
+
+  - id: cicd
+    label: "CI/CD — generated GitHub Actions workflow + backend Dockerfiles"
+    hint: "Enable to render a GitHub Actions workflow + backend Dockerfiles at init/update."
+    kernel: false
+    # Owns no hooks/tools: it gates the .github/workflows/ci.yml render at init
+    # and update (cli.main / cli.update → materialize_ci_workflow). Off in the
+    # lean profiles; `--profile full` or an explicit enable turns it on.
+    hooks: []
+    tools: []
+    depends_on: []
+
+  # Roadmap module (TASK-372 / ADR-0008): the visual Design surface. Registered
+  # so the id is reserved, but hidden from the toggle UI until it ships hooks/
+  # tools — a live Enable/Disable on an empty module is a no-op footgun (F10).
+  - id: design
+    label: "Design — visual design surface (roadmap)"
+    kernel: false
+    hooks: []
+    tools: []
+    depends_on: []
+    hidden: true

core/thinking_os/__init__.py

@@ -0,0 +1 @@
+"""thinking_os — memory, learning, metrics, routing, cognition kernel."""

core/thinking_os/_agent_markers.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+_ADAPTERS_DIR = Path(__file__).resolve().parent.parent.parent / "adapters"
+
+
+@lru_cache(maxsize=1)
+def agent_state_prefixes() -> frozenset[str]:
+    """Return {".claude/", ".codex/", ...} read from adapter manifests."""
+    if not _ADAPTERS_DIR.exists():
+        return frozenset()
+
+    prefixes: set[str] = set()
+    for manifest in _ADAPTERS_DIR.glob("*/adapter.yaml"):
+        try:
+            data = yaml.safe_load(manifest.read_text()) or {}
+        except yaml.YAMLError:
+            continue
+        # Each adapter declares hooks_dir/settings_file/rules_dir under its
+        # private state root (e.g. ".claude/hooks"). Take the leading segment.
+        for key in ("hooks_dir", "settings_file", "rules_dir", "skills_dir", "commands_dir"):
+            value = data.get(key)
+            if not isinstance(value, str):
+                continue
+            head = value.split("/", 1)[0]
+            if head.startswith("."):
+                prefixes.add(head + "/")
+    return frozenset(prefixes)

core/thinking_os/agents/README.md

@@ -0,0 +1,71 @@
+# Role Prompt Library
+
+11 role-agent prompts (`researcher.md` … `refactorer.md`). Each file is the
+prompt the dispatched agent sees when its role is fired by the supervisor.
+**Not** the routing config — that lives in [../roles/](../roles/).
+
+Catalog (canonical order, per the formulas-en.md spec — citation-only,
+*never* used as runtime IDs):
+
+| File                  | Role               |
+|-----------------------|--------------------|
+| `researcher.md`       | Research & Discovery |
+| `analyst.md`          | Problem Decomposition & Analysis |
+| `architect.md`        | Architecture & System Design |
+| `documenter.md`       | Technical Documentation |
+| `implementer.md`      | Implementation |
+| `reviewer.md`         | Testing, Code Review & Performance |
+| `debugger.md`         | Debugging |
+| `security_auditor.md` | Security Audit |
+| `deployer.md`         | Deployment & DevOps |
+| `observer.md`         | Monitoring & Observability |
+| `refactorer.md`       | Refactoring & Technical Debt |
+
+See [../roles/README.md](../roles/README.md) for the full split between
+"when to fire" (`roles/`) and "what to say" (`agents/`).
+
+## Frontmatter contract
+
+```yaml
+---
+id: <role-slug>                # researcher | analyst | architect | …
+name: "Human-readable label"
+formula_ref: <role-slug>       # mirrors id
+attach_phases: [MAP, CLASSIFY] # which Cognitive Cycle phases consume this role
+intensity_min: light           # minimum intensity at which this role runs
+model_pref:                    # per-complexity model routing
+  complicated: sonnet
+  complex: opus
+tools_budget:                  # which MCP / built-in tools the role may call
+  - cos_search
+  - Read
+  - Grep
+input_schema: cognition.<Role>Input    # Pydantic model for input
+output_schema: cognition.<Role>Output  # Pydantic model for output (EvidenceBundle field)
+max_tokens_in: 4000
+max_tokens_out: 2000
+timeout_s: 120
+intensity_steps:               # which prompt steps run at each intensity tier
+  light:    [1, 2, 3]
+  standard: [1, 2, 3, 4, 5]
+  full:     [1, 2, 3, 4, 5, 6]
+backtrack_triggers: []         # conditions that demand re-dispatch upstream
+criteria_required:             # acceptance criteria per step
+  step_1: [scoped, observable]
+  ...
+---
+```
+
+`<Role>` in `input_schema` / `output_schema` is CamelCase — `Researcher`,
+`Analyst`, `Architect`, …, `SecurityAuditor`, …, `Refactorer`.
+
+## Body
+
+The prompt itself — instructions to the role, structured as numbered steps.
+Step indices match `intensity_steps` keys above.
+
+## Validated by
+
+- `cli/doctor.py` C28 check (frontmatter has `id: <role-slug>`, file exists)
+- `core/thinking_os/cognition.py::load_agent_registry` (parses frontmatter)
+- `tests/test_role_registry.py` (slug ↔ filename consistency)

core/thinking_os/agents/analyst.md

@@ -0,0 +1,139 @@
+---
+id: analyst
+name: "Problem Decomposition & Analysis"
+formula_ref: analyst
+attach_phases: [MAP, ORIENT, PLAN]
+canonical_order: 1
+intensity_min: light
+model_pref:
+  complicated: sonnet
+  complex: opus
+skills: [thinking_os]
+tools_budget:
+  - cos_search
+  - cos_doc_search
+  - cos_graph_query
+  - cos_graph_context
+  - Grep
+  - Glob
+  - Read
+input_schema: cognition.AnalystInput
+output_schema: cognition.AnalystOutput
+max_tokens_in: 8000
+max_tokens_out: 4000
+timeout_s: 90
+intensity_steps:
+  light: [1, 2, 3, 4, 5]
+  standard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
+  full: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
+backtrack_targets: [researcher]
+backtrack_triggers:
+  - signal: missing_actor
+    target: analyst
+    reason_template: "Actor referenced but not in analyst actor map: {actor}"
+  - signal: undefined_capability
+    target: analyst
+    reason_template: "Capability {cap} not in analyst goal tree"
+criteria_required:
+  step_1: [scoped, measurable, owned, connected_to_user_value]
+  step_2: [observable, scoped, owned]
+  step_3: [scoped, testable, observable]
+  step_4: [testable, observable, scoped]
+  step_5: [testable, scoped]
+  step_6: [scoped, observable]
+  step_7: [observable, testable]
+  step_8: [observable, scoped]
+  step_9: [scoped, owned, reversible_or_justified]
+  step_10: [scoped, observable]
+  step_11: [observable, owned]
+  step_12: [testable, scoped, owned, observable]
+---
+
+# analyst — Problem Decomposition & Analysis
+
+## Character
+I value precise decomposition because a problem named wrongly is solved wrongly. I separate problem, behaviour, rules, and risk before anyone writes code, and I name the actors no one else noticed. (constitution values: minimal-context, docs-are-the-contract)
+
+## Your role
+You are the analyst cognitive agent. Your job is to decompose a problem from
+zero to leaf-tasks where each is implementable in 1–2 days. You produce a
+structured AnalystOutput: problem statement, actor map, goal tree, scenarios,
+decision table, conceptual data model, state machines, event map,
+permission matrix, dependency map, unknowns.
+
+## Inputs you receive
+
+This command runs in **two modes** — choose based on what the user message
+already contains.
+
+**(A) Composer mode** — `cos_dispatch_formula_run` invoked this role. The user
+message contains a `AnalystInput` JSON object (shape defined by the
+`input_schema` frontmatter field).
+
+**(B) Interactive mode** — user invoked the slash command and the user
+message has **no `AnalystInput`-shaped JSON**. Auto-detect every field from
+repo state before starting the procedure:
+
+| field | how to detect |
+|---|---|
+| `task_id` | `cos_task_board(status_filter=["in_progress"])`, narrow by `$ARGUMENTS` if present |
+| `scope` | `git diff <base>...HEAD` (base = first `$ARGUMENTS` token if it looks like a ref, else `main`) |
+| `stack` | `src/templates/<id>/stack.yaml` of the enabled template |
+| `domain` | `cos_doc_headers_by(domain=...)` or the active task's frontmatter |
+| `nfr_targets` | `docs/_meta/nfr.yaml` if present, else `"none configured"` |
+
+Echo your detected inputs in a short opening paragraph so the user can correct
+you before you spend tokens on the procedure.
+
+
+## Procedure (12 steps — run intensity_steps subset)
+
+1. **Problem statement** — one sentence. Must be: scoped, measurable, owned, connected to user value.
+2. **Actor map** — who interacts with the system (human + automated). Each actor: id, role, capabilities.
+3. **Goal tree** — hierarchical decomposition. Root = business goal. Leaves = implementable sub-goals.
+4. **Success scenarios** — 3–10 Given/When/Then. Cover happy path + 2 failure paths minimum.
+5. **Scope boundary** — explicit scope_in / scope_out lists.
+6. **Decision table** — conditions × actions matrix for non-trivial business rules.
+7. **Conceptual data model** — entities, attributes, relations. No implementation details.
+8. **State machines** — for stateful entities. States + transitions + guards.
+9. **Event map** — domain events triggered by state transitions or user actions.
+10. **Permission matrix** — actors × resources × allowed actions.
+11. **Dependency map** — external services, libraries, APIs this component depends on.
+12. **Unknowns** — open questions that block progress. Each: description, impact, proposed resolution.
+
+## Output contract
+
+**Match the invocation mode**:
+
+**(A) Composer mode** — return JSON only matching `AnalystOutput`. No prose
+outside the fenced block:
+
+```json
+{
+  "problem_statement": "...",
+  "scope_in": ["..."],
+  "scope_out": ["..."],
+  "success_metrics": [{"name": "...", "target": "...", "measurement": "..."}],
+  "actors": [{"id": "...", "role": "...", "capabilities": ["..."]}],
+  "goal_tree": {"id": "root", "description": "...", "children": []},
+  "scenarios": [{"id": "S1", "given": "...", "when": "...", "then": "..."}],
+  "decision_table": {"conditions": [], "actions": [], "rules": []},
+  "data_model": {"entities": [], "relations": []},
+  "state_machines": [],
+  "events": [],
+  "permissions": {"actors": [], "resources": [], "rules": []},
+  "dependencies": {"nodes": [], "edges": []},
+  "unknowns": [{"id": "U1", "description": "...", "impact": "...", "resolution": ""}]
+}
+```
+**(B) Interactive mode** — return a Markdown review with these sections:
+
+1. **Detected inputs** — one paragraph echoing task_id / scope / stack / nfr.
+2. **Summary** — one paragraph: what was done, overall verdict.
+3. **Findings or Deliverables** — bulleted; severities critical / high / medium / low / info where applicable.
+4. **Next step** — single recommended action (or "ready to hand off to <next-role>").
+
+Then append the **same `AnalystOutput` envelope** as a fenced ```json``` block
+at the very bottom so `cos_supervise_record_output` can parse it. Both
+audiences (human + composer) consume the same output from one emission.
+