From fecdf8cc231bc7f75a9b0b3d5f5342e5f2f3d104 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Mon, 20 Jul 2026 15:24:06 -0500 Subject: docs(todo): close the polyglot and subprojects scouting with decisions Polyglot: case-by-case, no new machinery. The bundle files that auto-install already compose. The only real collision is the hand-pasted coverage-makefile.txt, and clock-panel (the one polyglot project) proves it's benign. Keep the install-lang guard and document the coverage-target namespacing as a manual step (filed as a follow-up). Subprojects: don't promote. N=1 (only home), and a 282-line always-on rule for one project fails the thin-always-on principle. Keep it home-local. Revisit as a thin pointer if a second case appears. --- todo.org | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/todo.org b/todo.org index 808d92b..5200406 100644 --- a/todo.org +++ b/todo.org @@ -95,8 +95,10 @@ Implemented (Shape A) during the morning sentry review, 2026-07-20: Finding confirmed at implementation: the canonical machinery already never ignored working/ (tooling set is only =.ai/ .claude/ CLAUDE.md AGENTS.md=), so .emacs.d's =/working/= ignore was a purely local deviation. The staging proposal dir was removed after shipping; its content lives in the feat commit and this body. -** TODO [#C] Polyglot projects — supported, or refused? :spec: -SCHEDULED: <2026-07-20 Mon> +** DONE [#C] Polyglot projects — supported, or refused? :spec: +CLOSED: [2026-07-20 Mon] +DECISION (2026-07-20, scouting with Craig): *case-by-case, and it already composes — no option-2 machinery.* The evidence: bundle contents split into namespaced/additive files (rules =.md=, =validate-.sh= hooks, =coverage-summary.= scripts, appended =gitignore-add.txt=) that compose cleanly, and exactly three colliding files — =claude/settings.json= and =githooks/pre-commit= (full bundles only: bash/elisp/go) and =coverage-makefile.txt= (elisp/go/python/typescript). Of the three, only =coverage-makefile.txt= occurs in the fleet, and clock-panel (the one real polyglot, python+typescript) proves it's benign: both bundles installed, no breakage, because that fragment is a hand-pasted Makefile block nobody pasted twice. So: keep the install-lang collision guard (it blocks the destructive full+full settings/githooks clobber, which no project actually hits), and document the =coverage-:= + =coverage:= aggregate namespacing as the one manual step when going polyglot (filed below). No two-full-co-equal-bundle project exists, so the settings.json/githooks merge is unwarranted. Follow-up doc: [[file:todo.org::*Document polyglot coverage-makefile namespacing][Document polyglot coverage-makefile namespacing]]. + Do we support more than one language bundle per project? The honest answer today is "partly, by accident." The collision guard added 2026-07-16 refuses a *colliding* second bundle rather than silently replacing the first's config, but @@ -136,8 +138,10 @@ What the decision needs to know: =CLAUDE.md=, which is destructive on a customized project. If polyglot becomes supported, the override wants to be its own flag. -** TODO [#C] Subproject pattern — promote to claude-rules? :spec: -SCHEDULED: <2026-07-20 Mon> +** DONE [#C] Subproject pattern — promote to claude-rules? :spec: +CLOSED: [2026-07-20 Mon] +DECISION (2026-07-20, scouting with Craig): *don't promote — keep it local at home.* The scouting confirmed N=1: across all 27 =.ai= scopes, home (9 subprojects, all from the single 2026-06-11 fold) is the only real user. The nearest neighbors aren't the pattern — rulesets folds claude-templates in as a git *subtree* (different mechanism, not shared-=.ai/=-scope), archsetup's dotfiles/ likewise; every other project is a focused single package with no subproject structure or need. Promoting a 282-line convention into the always-on claude-rules layer for one project fails the thin-always-on principle (the precedent is patterns.md at 29 lines + docs-lifecycle.md's depth-in-a-spec). Keep the convention as home's local instance. Revisit only if a genuine second case appears, and then as a thin pointer + a spec, never 282 lines always-on. + home proposes promoting its subproject pattern (a former standalone project folded into a parent, living as a self-contained subdir sharing the parent's =.ai/= scope) into the rules layer: vocabulary, the read-first @@ -175,6 +179,9 @@ so it's effective. Don't shape the rule before the scouting. - *Instance vs rule:* the metrics, self-improvement log, kill criteria, rollout dates, and adoption table are home's instance, not rule content. +** TODO [#D] Document polyglot coverage-makefile namespacing :chore: +The one manual step the polyglot decision (2026-07-20) left: when a project installs two bundles that both ship =coverage-makefile.txt= (elisp/go/python/typescript), their =coverage:= / =coverage-summary:= Makefile targets duplicate. Document the fix — rename to per-language =coverage-:= targets and add a =coverage:= aggregate that depends on them — where a polyglot user would meet it (install-lang docs, or a short note in the bundle README / languages/ overview). Low urgency: clock-panel is polyglot today and unaffected because it has no assembled Makefile. Do it when the coverage-makefile fragments are next actually pasted, or opportunistically. + ** TODO [#D] Cross-host agent coordination — a lock across ratio and velox :feature: Foundational primitive several deferred features wait on. =agent-lock= serializes agents on ONE host (its locks live on tmpfs, =$XDG_RUNTIME_DIR/agent-locks/=), so nothing coordinates the two daily drivers. When ratio and velox both act on shared state at once, there's no lock to stop them — the roam-write lock and sentry's single-runner lock are all host-local. Design a cross-machine lock (a lock node committed to a shared repo, a tailnet lock service, or a designated-primary election) that the host-local locks escalate to when the operation touches cross-machine-shared state (roam, a sibling-freshness push). Take up when cross-host contention proves real in practice, not speculatively. -- cgit v1.2.3