Skip to content

Commit 5cd164e

Browse files
committed
refactor: flagbind batch helpers and convention sweep
Add parallel-slice batch functions to flagbind (BindStringFlagsP, BindStringFlags, BindBoolFlags, BindBoolFlagsP, BindStringFlagShorts, BindStringFlagsPDefault) replacing repetitive one-at-a-time flag registrations across 8 CLI command files. Convention sweep: - hub: rename files (entry_validate→validate_entry, errcheck→err_check), remove const aliases, move magic numbers to config/hub and config/entry, fix predicate naming (isEOF→eof, isAuthErr→authErr) - initialize: rename claudecheck→claude_check, details→detail - steering/types: align docstrings with conventions - compliance: fix TestNoSecretsInTemplates false positive on YAML keys - golangci: extend G101 exclusion to all embed/text/ DescKey files - sysinfo: add missing nolint:gosec for G204 on vm_stat Spec: specs/flagbind-batch-and-convention-sweep.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
1 parent 6ba64f0 commit 5cd164e

505 files changed

Lines changed: 19525 additions & 7584 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.context/DECISIONS.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
<!-- INDEX:START -->
44
| Date | Decision |
55
|----|--------|
6+
| 2026-04-11 | Journal stays local; LEARNINGS.md is the shareable layer |
67
| 2026-04-09 | Architecture skill pipeline is a triad not a quartet |
78
| 2026-04-08 | Remove #done tag convention, simplify task archival |
89
| 2026-04-06 | Use hook relay for session provenance instead of JSONL parsing or env vars |
@@ -119,6 +120,90 @@ For significant decisions:
119120
120121
-->
121122

123+
## [2026-04-11-200000] Journal stays local; LEARNINGS.md is the shareable layer
124+
125+
**Status**: Accepted
126+
127+
**Context**: With the hub now carrying shared project context between machines
128+
and eventually between teammates, the question came up whether enriched
129+
journal entries should ride along — either the raw `.context/journal/` files
130+
or an "export enriched entries as shareable learning items" pipeline layered
131+
on top of `/ctx-journal-enrich`. The journal is already gitignored per the
132+
2026-03-05 `.context/memory/` decision and for the same reason: it's a
133+
first-person log of raw prompts, half-formed thoughts, dead ends, personal
134+
names, and things the user talks through with themselves. It sits in the
135+
same trust tier as shell history or a private notebook.
136+
137+
The trade-off is real: shared journals would make it trivial for teammates
138+
(or future-me on another machine) to see the full reasoning trail behind a
139+
decision. But "full reasoning trail" is precisely the thing that makes a
140+
journal journal and not a changelog — it includes the parts the author
141+
hasn't decided to stand behind yet, plus incidental private content.
142+
143+
**Decision**: The journal is **Tier-0 personal** and never leaves the
144+
originating machine. No hub sync, no export-by-default, no
145+
enriched-entries-as-shareable-items pipeline. The enrichment pipeline
146+
(`/ctx-journal-enrich`) stays as-is: journal → human-in-the-loop review →
147+
explicit promotion to LEARNINGS.md / DECISIONS.md / CONVENTIONS.md via the
148+
existing `/ctx-learning-add`, `/ctx-decision-add`, `/ctx-convention-add`
149+
commands. Those distilled artifacts are **Tier-1 shareable** and are what
150+
the hub syncs when a team opts into shared context.
151+
152+
The promotion boundary is therefore the enrichment step, not a new export
153+
pipeline. The user is the gate.
154+
155+
**Rationale**: Any "shareable enriched journal entry" pipeline would have to
156+
re-implement the trust boundary that `/ctx-learning-add` already enforces:
157+
the human decides what's worth sharing, strips incidental private content,
158+
and rewrites it as a standalone artifact. A second pipeline that tries to
159+
do this automatically would either (a) leak private content by accident, or
160+
(b) require the same human review and thus collapse back into
161+
`/ctx-learning-add`. The principled answer is that there is no second
162+
pipeline — LEARNINGS.md *is* the shareable form of the journal.
163+
164+
This also preserves the psychological safety of the journal: the author
165+
can write freely because they know nothing they write is one sync away
166+
from a teammate's screen. Lose that property and the journal stops being a
167+
journal and starts being a changelog draft.
168+
169+
**Consequence**:
170+
171+
- Journal files stay gitignored and stay out of `ctx hub` sync paths. Any
172+
future code that walks context files for replication must exclude
173+
`.context/journal/` explicitly and be covered by a test.
174+
- `/ctx-journal-enrich` remains the promotion boundary. Its output targets
175+
are LEARNINGS.md / DECISIONS.md / CONVENTIONS.md, never a separate
176+
"shareable journal" bucket.
177+
- Hub docs (`docs/home/hub.md`, `docs/recipes/hub-personal.md`,
178+
`docs/recipes/hub-team.md`, `docs/security/hub.md`) should state the
179+
Tier-0 / Tier-1 split explicitly so users building team workflows don't
180+
assume "shared context" means "shared everything."
181+
- The sync code path in `internal/hub/sync_helper.go` and any future
182+
replication of context files must enforce this exclusion at the
183+
code level — a gitignore entry is a user-convenience signal, not a
184+
hub-trust boundary.
185+
- A potential future "personal multi-machine journal sync" (same human,
186+
different laptops) is explicitly **out of scope** of this decision. If
187+
it ever ships, it rides a different transport (encrypted-at-rest,
188+
single-user, not the team hub) and needs its own decision record.
189+
190+
**Alternatives considered**:
191+
192+
- **Sync raw journal files via hub**: rejected. Inverts the gitignore
193+
decision, leaks private content by construction, destroys the
194+
journal's "safe to write freely" property.
195+
- **Auto-export enriched entries as a new shareable artifact type**:
196+
rejected. Duplicates `/ctx-learning-add` without the human gate, or
197+
collapses back into it. No real difference from the status quo except
198+
the opportunity for accidental leakage.
199+
- **Opt-in per-entry "publish to hub" flag in the journal**: rejected as
200+
premature. If the user wants an entry on the hub, the existing flow is
201+
one command away — write it as a learning or decision. A second path
202+
adds surface area without adding capability.
203+
204+
**Related**: Reinforces the 2026-03-05 `.context/memory/` gitignore
205+
decision (same trust-tier reasoning for a different private artifact).
206+
122207
## [2026-04-11-180000] `Entry.Author` is server-authoritative, not client-authoritative
123208

124209
**Status**: Accepted

.context/TASKS.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,30 @@ TASK STATUS LABELS:
2727

2828
### Misc
2929

30+
- [ ] Move `ctx bootstrap` back to `ctx system bootstrap` (hidden). Bootstrap is agent-only plumbing — no human types it interactively. It was incorrectly promoted to top-level in the namespace cleanup. Move the package back to `internal/cli/system/cmd/bootstrap/`, restore `UseSystemBootstrap`/`DescKeySystemBootstrap` constants, re-add `Hidden: true`, update CLAUDE.md templates and skills back to `ctx system bootstrap`, remove from `docs/cli/bootstrap.md` and `docs/cli/index.md` Diagnostics group, remove from `zensical.toml` nav. Spec: specs/cli-namespace-cleanup.md #priority:high #added:2026-04-11
31+
32+
- [ ] Rename `ctx stats` to `ctx usage`. "Stats for what?" — the current name lost its anchor when promoted from `ctx system stats`. `ctx usage` communicates intent: "show me my token usage." `ctx session stats` was considered but rejected as premature — a parent with one child is worse than a flat command. Revisit when `ctx session` has 2+ children. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11
33+
34+
- [ ] Rename `ctx resource` to `ctx sysinfo`. Without the `system` prefix, "resource" sounds like it manages project resources (files, assets, infrastructure). It's actually a system-health snapshot: memory, swap, disk, CPU load. `sysinfo` matches the internal package name (`internal/sysinfo`) and is unambiguous. `health` was considered but rejected — too similar to `ctx doctor` and `ctx doctor health` reads wrong. Same rename pattern. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11
35+
36+
- [ ] Deprecate or remove `ctx dep`. Utility is marginal: agents rarely need a flat dependency inventory to make decisions, and `go list -m all` / `npm ls` already cover the use case. Doesn't clear the "would I miss it if it vanished?" bar. Removal is a one-command delete + doc cleanup. #priority:low #added:2026-04-11
37+
38+
- [ ] Introduce `ctx hook` parent command — consolidate hook-related user-facing commands under a single namespace: `ctx hook message list/show/edit/reset` (currently `ctx message`), `ctx hook notify` (currently `ctx notify`), `ctx hook pause` / `ctx hook resume` (currently top-level `ctx pause` / `ctx resume`). "What are we pausing?" — hooks. The current top-level `pause` loses that context. Clarifies the `ctx trigger` vs `ctx hook` distinction: `trigger` = user-authored scripts, `hook` = plugin-shipped machinery + its user-facing controls. Future children: `ctx hook status` (which hooks fired recently), `ctx hook test` (dry-run), `ctx hook event` (currently `ctx event`). Same rename pattern as previous namespace cleanups. Spec: specs/cli-namespace-cleanup.md #priority:medium #added:2026-04-11
39+
40+
### Runbooks
41+
42+
- [ ] Create `hack/runbooks/release-checklist.md` — canonical pre-release sequence: run codebase-audit, docs-semantic-audit, sanitize-permissions, `make test`, bump version, generate release notes, tag, push. Today this lives in the operator's head + scattered across docs/operations/. Cross-link with `_ctx-release` skill. #priority:high #added:2026-04-11
43+
44+
- [ ] Create `hack/runbooks/breaking-migration.md` — template for users upgrading across breaking CLI renames. What commands changed, how to regenerate CLAUDE.md (`ctx init --force`), how to update personal scripts and hook configs. One instance per breaking release, or a generic template with a per-release appendix. #priority:medium #added:2026-04-11
45+
46+
- [ ] Create `hack/runbooks/hub-deployment.md` — linear runbook for setting up a ctx Hub for a team: generate admin token, distribute, register clients, verify sync, configure TLS (when H-01/H-02 land). Consolidates pieces currently scattered across hub recipes. #priority:medium #added:2026-04-11
47+
48+
- [ ] Create `hack/runbooks/new-contributor.md` — onboarding sequence: clone → `ctx init``make build && sudo make install` → verify hooks (`claude mcp list`) → run first session → verify context persistence. Currently scattered across README, contributing.md, and setup docs. #priority:medium #added:2026-04-11
49+
50+
- [ ] Create `hack/runbooks/plugin-release.md` — plugin-specific release procedure: update hooks.json, bump version, test against fresh Claude Code install, publish to marketplace, verify `claude mcp list` shows updated version. Not covered by the general release checklist. #priority:low #added:2026-04-11
51+
52+
### Misc
53+
3054
- [ ] Human: Do a documentation audit for AI-generated artifacts. #important #not-urgent
3155

3256
- [ ] Human: test `ctx init` on a fresh ubuntu install.

0 commit comments

Comments
 (0)