sdd: decision tactical Plans the implementation of sdd view — a new CLI command ...

Author: hlubek

.sdd/graph/2026/05/06-151345-d-tac-uww.md

@@ -0,0 +1,73 @@
+---
+type: decision
+layer: tactical
+kind: plan
+refs:
+    - 20260505-153647-d-tac-kv5
+    - 20260505-153654-d-tac-qom
+    - 20260413-142536-d-cpt-ah1
+closes:
+    - 20260505-215340-s-cpt-rwd
+    - 20260505-215333-s-cpt-jq7
+participants:
+    - Christopher
+    - Claude
+confidence: medium
+summary: Plans implementation of `sdd view`, a new CLI command with a composable pipeline of query primitives (source, filter, transform, aggregate, rank, page, render) and named macros to enable lightweight catch-up output at graph scale beyond 400 entries without modifying `sdd status`. The plan references the quick catch-up mode directive (d-tac-kv5) and topic-drill mode decision (d-tac-qom) for operational context, and adopts the CQRS decomposition mandate from the framework contract (d-cpt-ah1). It closes the ranking mechanism signal (s-cpt-rwd) by implementing composite in-degree and heat-decay ranking, and resolves the catch-up synthesis bottleneck (s-cpt-jq7) by replacing synthesis-heavy playbook rewriting with mechanical selection and ranking.
+summary_hash: 91701e07911924ee99781330ed34deb5
+---
+
+Plans the implementation of `sdd view` — a new CLI command exposing a composable pipeline of query primitives (source, filter, transform, aggregate, rank, page, render) with named macros as sugar — to enable lightweight, mechanical catch-up output at graph scale beyond 400 entries while leaving `sdd status` unchanged.
+
+**Architecture: pipeline of primitives.** Every layout entry is a chain of function calls (`section:modifier:modifier:...`) where each modifier is itself a function. The grammar is uniform, parsable left-to-right with paren-depth tracking, and extensible without further CLI changes. Filters intersect cumulatively; non-filter modifiers apply last-write-wins per modifier kind.
+
+**Primitives.** Sources: `source(graph)` (default), `source(wip)`. Filters: `active`, `closed`, `superseded`, `kind(K[, ...])`, `layer(L)`, `since(date|duration)`, `topic(L)`. Transforms: `expand(field)`. Aggregates: `group(by:field)` (`count`, `agg(...)` reserved). Rank: `rank(<algorithm>)`. Page: `n(N)` (`offset(O)` reserved). Output: `name(string)`. Render: `as-list`, `as-grouped`, `as-focus-block`, `as-participants-block`, `as-wip-list`.
+
+**Algorithm and decay vocabulary.** Algorithms: `heat(decay)`, `in-degree`, `mult(decay)`, `add(decay)`, `log(decay)`, `by(date)`. Decay names: `exp-{7,14,30}d`, `linear-{7,14,30}d`, `none`. `in-degree` ignores decay silently. `since(Nm)` and `since(Ny)` use Go's `time.AddDate` for calendar-correct subtraction; `Nd` and `Nw` use exact 24h offsets.
+
+**Macros (canonical pipelines, modifier-overridable):**
+
+- `top(N)` → `active:n(N):rank(heat(exp-14d)):as-list`
+- `focus` → `kind(focus):active:expand(involvement):as-focus-block`
+- `topic(L)` → `topic(L):rank(heat(exp-14d)):as-list`
+- `decisions` → `active:kind(plan,directive,activity,contract,aspiration):group(by:kind):as-grouped`
+- `signals` → `active:kind(gap,question):group(by:kind):as-grouped`
+- `insights`, `done`, `aspirations`, `contracts`, `participants`, `wip` — each a named pipeline with appropriate filter+rank+render
+
+**Focus-block state derivation.** For each involvement target in an active focus, resolve actors (per-involvement first, else focus-level default, else empty) and heat (via the configured rank). State: `pull-available` if actors empty; `stalled` if actors present and heat below stalled threshold; otherwise `driving`. Closed/superseded targets are omitted from the focus block. Stalled threshold is configurable via `stalled(value)` modifier; default observed during plan implementation.
+
+**CLI surface.** New command `sdd view` parses `--layout=<spec>`, executes the pipeline, renders. Bare `sdd view` (no `--layout`) prints help — grammar overview, vocabulary reference, and sample invocations — consistent with the no-presets-in-CLI decision (a hidden default would be a preset by another name). For ad-hoc browsing without composition, `sdd list` remains the simpler tool. The existing `sdd status` is **not modified** — its kind-grouped narrative stays as is, deprecation deferred to a future directive once `sdd view` is well-adopted. Pipeline primitives live in shared `internal/` packages so `sdd list` (Plan 1) can consume filter primitives like `topic(L)` without re-implementation.
+
+**Defaults and evaluation methodology.** Initial defaults: `rank=heat`, `decay=exp-14d`, top-N count=25. Stalled threshold default chosen during implementation by qualitative comparison on this graph. Closing done signal carries a findings attachment comparing at least three rank/decay combinations across `top` outputs on the current graph, with usefulness narrative and chosen-default rationale; defaults revisable post-shipping via a separate directive based on observed behavior.
+
+**CQRS decomposition** (per `d-cpt-ah1`): layout parsing in `internal/query/`, pipeline execution and ranking/decay/aggregation in `internal/finders/`, layout/result types in `internal/model/`, render functions in `internal/presenters/`, thin CLI shell in `cmd/sdd/`.
+
+**Out of scope** (deferred): `offset(O)` paging, `count` aggregation, `as-table` and other render shapes, `agg(...)` envelope, `source(topics)` and `as-tree`, `sdd list` rank flags (filter via `topic(L)` is in Plan 1's scope), `sdd status` deprecation, persistent ranking index/cache (v1 is pure read-time).
+
+See [design](./06-151345-d-tac-uww/design.md) for full grammar, vocabulary reference, macro pipelines, render contracts, CQRS package scaffolding, and sample invocations per catch-up move.
+
+## Acceptance criteria
+
+- [ ] New command `sdd view` accepts `--layout=<spec>` per the pipeline grammar
+- [ ] Bare `sdd view` (no `--layout`) prints help — grammar overview, vocabulary reference, and sample invocations — rather than executing any default layout
+- [ ] Empty `--layout=` value produces a grammar error (no implicit fallback)
+- [ ] `sdd status` is not modified by this plan; existing kind-grouped output preserved
+- [ ] Layout grammar implemented (functional, colon-chained, parens for args, nested function calls); parser tracks paren depth
+- [ ] Filters intersect cumulatively; non-filter modifiers apply last-write-wins per modifier kind
+- [ ] Source, filter, transform, aggregate, rank, page, output, and render primitives implemented per the vocabularies in the description
+- [ ] Algorithm vocabulary {heat, in-degree, mult, add, log, by(date)} implemented; in-degree ignores decay silently
+- [ ] Decay vocabulary {exp-{7,14,30}d, linear-{7,14,30}d, none} implemented
+- [ ] `since()` accepts ISO date `YYYY-MM-DD` and duration `Nd|Nw|Nm|Ny`; m/y via `time.AddDate` calendar arithmetic; d/w exact 24h offsets
+- [ ] Macros implemented: top(N), focus, topic(L), decisions, signals, insights, done, aspirations, contracts, participants, wip — each a named pipeline overridable by user modifiers
+- [ ] Focus-block state derivation per the algorithm: pull-available / stalled / driving; closed/superseded targets omitted; stalled threshold configurable via `stalled(value)`; default observed during evaluation
+- [ ] `as-list` deduplicates entries already shown in any focus block in the same layout
+- [ ] `name(string)` modifier sets section header verbatim; otherwise auto-derived from rank+decay
+- [ ] Unknown function/algorithm/decay/render name → clear error listing the valid set
+- [ ] Render-shape mismatch → clear error (e.g., `as-grouped` on flat result)
+- [ ] Invalid layout grammar → clear error pointing to position
+- [ ] CQRS decomposition per `d-cpt-ah1`: layout parsing in `internal/query/`, pipeline execution in `internal/finders/`, types in `internal/model/`, render in `internal/presenters/`
+- [ ] Pipeline primitives in shared internal packages, callable from other CLI commands (`sdd list --topic` consumes `topic(L)` filter)
+- [ ] Unit tests cover layout parser edge cases, ranking algorithms, decay functions, render-shape validation, since() parsing
+- [ ] Smoke test demonstrates `sdd view` against the local graph with light, full, and drill compositions
+- [ ] Skill `cli-reference.md` updated with `sdd view` overview, grammar summary, and section/algorithm/decay reference tables
+- [ ] Closing done signal includes findings attachment: at least three rank/decay combinations compared qualitatively on the current graph, chosen defaults documented with rationale