Skip to content

Harden /init scaffolding: absorb unmarked section, lazy domains - #14

Merged
gering merged 6 commits into
mainfrom
task/harden-init-scaffolding
Jun 22, 2026
Merged

Harden /init scaffolding: absorb unmarked section, lazy domains#14
gering merged 6 commits into
mainfrom
task/harden-init-scaffolding

Conversation

@gering

@gering gering commented Jun 21, 2026

Copy link
Copy Markdown
Owner

Summary

  • Close two /init UX gaps surfaced while dogfooding the knowledge-system on this repo
  • No more duplicate ## Project Knowledge System heading when a repo already had a hand-written, unmarked one
  • Empty starter domain dirs no longer silently vanish on the first commit

Changes

  • Unmarked-section absorption (init/SKILL.md step 4): three-case resolution — markers present → replace in place; else unmarked ## Project Knowledge System heading → absorb the whole section into the marker-wrapped block; else append. Idempotent on re-run (next run hits the markers branch).
  • Lazy starter domains (step 2 + "what this creates" + report): stop scaffolding empty architecture//features//deployment/ dirs (Git drops empty dirs); they materialize on first /curate//migrate write and stay visible as headings in _index.md.
  • README /init command row tightened.
  • Curated the reusable pattern as architecture/idempotent-scaffolding.md (dogfooding).
  • Bumped knowledge-system 1.8.0 → 1.8.1 (plugin.json + marketplace.json in sync).

Readiness

  • ✅ README updated
  • ✅ Version bumped 1.8.0 → 1.8.1 (in sync)
  • ➖ Changelog N/A (no changelog in repo)
  • ✅ Knowledge curated (architecture/idempotent-scaffolding.md)
  • ✅ check-structure.py: 0 errors

Test plan

  • /init on a repo with a hand-written unmarked ## Project Knowledge System section → absorbed, no duplicate heading
  • /init twice → second run replaces in place, no second absorption
  • Fresh /init → no empty domain dirs; /curate into architecture/ creates the dir on demand

🤖 Generated with Claude Code

gering and others added 6 commits June 19, 2026 12:38
@gering @claude
Harden /init scaffolding: absorb unmarked section, lazy domains
e50e0ab 
- Detect a pre-existing unmarked "## Project Knowledge System" section and
  absorb it into the marker-wrapped block instead of appending a duplicate
  heading; idempotent on re-run (next run replaces in place)
- Stop scaffolding empty architecture/features/deployment dirs (Git drops
  empty dirs anyway); they materialize lazily on first /curate or /migrate
  write, and stay visible as headings in _index.md
- Tighten README /init row; bump knowledge-system to 1.8.1

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering @claude
Curate idempotent-scaffolding knowledge entry
49467ad 
Capture the two /init footguns as a reusable design convention: absorb
pre-existing unmarked sections when injecting a marker-wrapped block, and
create starter dirs lazily instead of scaffolding empty/.gitkeep dirs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering @claude
Fix code-review findings in /init SKILL.md
165ce5d 
- Reconcile re-init: step 2 now overwrites _index.md when the user chose
  'Re-initialize everything' (previously skipped if it existed, so re-init
  never actually reset it); clarify the 'created once' heading accordingly
- Drop stale 'directory structure' wording in the intro and re-init option
  (only _index.md is scaffolded now that domains are lazy)
- Tell the report step to annotate the real action ((new)/(reset)/absorbed)
  instead of hardcoding (new), which was wrong on re-runs

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering @claude
Make /init never overwrite _index.md; delegate index rebuild to /reindex
e699525 
The previous round made 'Re-initialize everything' actually reset _index.md
to the bare template, which discards the user's curated index entries. But
non-destructive index reconciliation already exists as /reindex (rebuilds
_index.md from the files on disk: adds missing entries, drops deleted ones).

So drop the special case instead of duplicating a reconciler in /init:
- /init on an initialized repo refreshes only the plugin-managed parts and
  never touches _index.md or knowledge files; stale index -> point to /reindex
- restore the accurate 'created once, never overwritten' wording
- step 2 skip rule no longer carries a re-init exception
- simplify the step-6 report annotation guidance and cover all three step-4
  CLAUDE.md outcomes (block added / updated / absorbed)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering @claude
Extend idempotent-scaffolding: never overwrite user content
690dd57 
Add the third principle that emerged from the /init redesign: scaffolders
must not clobber user-authored files, and reconciliation belongs in the
dedicated maintenance tool (/reindex), not as a destructive reset or a
duplicate reconciler in the scaffolder.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering @claude
Trim idempotent-scaffolding index line for context economy
d6685e2 
Always-loaded index entry was ~34% longer than its siblings; drop the
/reindex parenthetical (detail lives in the file body).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gering
gering merged commit a6d8845 into main Jun 22, 2026
1 check passed
@gering
gering deleted the task/harden-init-scaffolding branch June 22, 2026 12:39
gering added a commit that referenced this pull request Jul 16, 2026
@gering @claude
Address --max swarm self-review findings
005246f 
Second dogfooding round at the deepest profile (/swarm:review --max --fix:
per-lens split live — gate pruned style, 10 xhigh finders + codex
gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus).
Fixes the agreed findings:

- Never auto-accept an all-untagged consensus cluster: no tagged lens
  backs it, so it is verified like a solo. Verify/auto-accept now derive
  from ONE needsVerify predicate (structural exactly-once partition);
  kind vote in clearer every-form (#1, consensus critical; #21, #22)
- Design verifier sees the finding's recommendation — the proposal the
  applicability rubric actually tests — and carries an escape hatch:
  a genuine defect mis-filed under a design lens is not refuted away
  (#12, #3); "solo" dropped from verifier prompts (#4)
- Untagged findings from multi-lens cluster finders fall back to
  'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent
  free-text lens validated, majority-member fallback (#9)
- Improvement invitation scoped to design finder units — defect-lens
  finders stay defect-only (#8); merge prompt clusters by issue, not
  only defect (#13); schema descriptions generalized for design
  findings (#14)
- LENS_BRIEF startup assertion (#6); gate prompt interpolates
  LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens
  mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5)
- Workflow assigns stable finding num (defects first, shared sequence);
  presenter/pr-post render it verbatim (#20)
- pr-post.py: design lens is the backup kind signal when the handoff
  drops kind (explicit defect still wins); single-pass partition (#17, #24)
- Balance: REFUTED is its own segment (refuted ⊄ solo since design
  consensus can be refuted) (#2); LOCKED design-table column precedence
  in --loop rounds clarified (#11); "verifies solos" doc sweep across
  manifests/README/knowledge (#4); cluster failure-isolation trade-off
  documented (#10); knowledge index line trimmed (#15)

Declined: #16 (JS test harness for sandbox code; lens-sync test covers
the drift class), #18 (gate-fail under --max runs all lenses — the
documented never-silently-narrower degrade), #23 (micro-opt vs readability).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 17, 2026
@gering @claude
Address --max swarm self-review findings
9ff85f3 
Second dogfooding round at the deepest profile (/swarm:review --max --fix:
per-lens split live — gate pruned style, 10 xhigh finders + codex
gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus).
Fixes the agreed findings:

- Never auto-accept an all-untagged consensus cluster: no tagged lens
  backs it, so it is verified like a solo. Verify/auto-accept now derive
  from ONE needsVerify predicate (structural exactly-once partition);
  kind vote in clearer every-form (#1, consensus critical; #21, #22)
- Design verifier sees the finding's recommendation — the proposal the
  applicability rubric actually tests — and carries an escape hatch:
  a genuine defect mis-filed under a design lens is not refuted away
  (#12, #3); "solo" dropped from verifier prompts (#4)
- Untagged findings from multi-lens cluster finders fall back to
  'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent
  free-text lens validated, majority-member fallback (#9)
- Improvement invitation scoped to design finder units — defect-lens
  finders stay defect-only (#8); merge prompt clusters by issue, not
  only defect (#13); schema descriptions generalized for design
  findings (#14)
- LENS_BRIEF startup assertion (#6); gate prompt interpolates
  LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens
  mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5)
- Workflow assigns stable finding num (defects first, shared sequence);
  presenter/pr-post render it verbatim (#20)
- pr-post.py: design lens is the backup kind signal when the handoff
  drops kind (explicit defect still wins); single-pass partition (#17, #24)
- Balance: REFUTED is its own segment (refuted ⊄ solo since design
  consensus can be refuted) (#2); LOCKED design-table column precedence
  in --loop rounds clarified (#11); "verifies solos" doc sweep across
  manifests/README/knowledge (#4); cluster failure-isolation trade-off
  documented (#10); knowledge index line trimmed (#15)

Declined: #16 (JS test harness for sandbox code; lens-sync test covers
the drift class), #18 (gate-fail under --max runs all lenses — the
documented never-silently-narrower degrade), #23 (micro-opt vs readability).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 17, 2026
@gering @claude
Address --max swarm self-review findings
2be83aa 
Second dogfooding round at the deepest profile (/swarm:review --max --fix:
per-lens split live — gate pruned style, 10 xhigh finders + codex
gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus).
Fixes the agreed findings:

- Never auto-accept an all-untagged consensus cluster: no tagged lens
  backs it, so it is verified like a solo. Verify/auto-accept now derive
  from ONE needsVerify predicate (structural exactly-once partition);
  kind vote in clearer every-form (#1, consensus critical; #21, #22)
- Design verifier sees the finding's recommendation — the proposal the
  applicability rubric actually tests — and carries an escape hatch:
  a genuine defect mis-filed under a design lens is not refuted away
  (#12, #3); "solo" dropped from verifier prompts (#4)
- Untagged findings from multi-lens cluster finders fall back to
  'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent
  free-text lens validated, majority-member fallback (#9)
- Improvement invitation scoped to design finder units — defect-lens
  finders stay defect-only (#8); merge prompt clusters by issue, not
  only defect (#13); schema descriptions generalized for design
  findings (#14)
- LENS_BRIEF startup assertion (#6); gate prompt interpolates
  LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens
  mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5)
- Workflow assigns stable finding num (defects first, shared sequence);
  presenter/pr-post render it verbatim (#20)
- pr-post.py: design lens is the backup kind signal when the handoff
  drops kind (explicit defect still wins); single-pass partition (#17, #24)
- Balance: REFUTED is its own segment (refuted ⊄ solo since design
  consensus can be refuted) (#2); LOCKED design-table column precedence
  in --loop rounds clarified (#11); "verifies solos" doc sweep across
  manifests/README/knowledge (#4); cluster failure-isolation trade-off
  documented (#10); knowledge index line trimmed (#15)

Declined: #16 (JS test harness for sandbox code; lens-sync test covers
the drift class), #18 (gate-fail under --max runs all lenses — the
documented never-silently-narrower degrade), #23 (micro-opt vs readability).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk
gering added a commit that referenced this pull request Jul 25, 2026
@gering @claude
Address swarm review findings on the lane registry
4f29afb 
Apply the agreed findings from a local swarm review (11 ✅ + 1 🟨; the 3 ❌ —
a feature version bump, a README inventory line, and a per-subcommand python3
guard — were deliberately left, see the PR discussion).

herdr-agent.sh:
- Bound herdr list/get/read with a wall-clock timeout (_ha_bounded: timeout →
  gtimeout → perl alarm), honouring the header's "never a hang" promise. wait
  stays governed by its own --timeout. (#6)
- ha_wait now detects the --timeout=MS form too, so a caller's explicit bound in
  either spelling is honoured and no duplicate flag is appended. (#7)
- A missing <target> returns usage code 2, not 4 (server-unreachable), so a
  programmer error is not mistaken for a transient outage. (#12)
- set -u is enabled only on the executed-CLI path, never at source time, so
  sourcing for the prelude/helpers no longer mutates the caller's shell. (#13)
- classify_cwd returns the resolved path as a third tuple element, so a caller
  keying by full path reuses it instead of a second realpath. (#14)

lanes.sh:
- Scrub tab/CR/LF from every TSV cell: agent-derived fields are untrusted, and an
  embedded tab/newline would forge columns/rows. Mirrors herdr-tab-glyph. (#1)
- Guard the agent loop against non-dict (null) elements → never crash, always
  exit 0. (#2)
- flush() now calls the shared classify_cwd instead of re-open-coding the task
  rule, so the classification can't drift between the two consumers. (#15)
- Resolve SCRIPT_DIR via BASH_SOURCE (robust to bare-name invocation). (#5)
- Header wording: exit-0 scope clarified; --json emits [] when no lanes. (#3, #8)

herdr-tab-glyph.sh: consume classify_cwd's new 3-tuple; same BASH_SOURCE fix (#5).
herdr-tab-glyphs.md: point at $HERDR_MATCH_PRELUDE as the shared match SoT. (#10)
Tests extended: null-element + TSV-injection (lanes); --timeout= + missing-target
exit 2 (herdr-agent). Regression: herdr-tab-glyph output byte-identical vs a live
snapshot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8crYp6tzRKMiwW63Zt3GG
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@gering