punkshell

1 Tag

182 MiB

Author	SHA1	Message	Date
Julian Noble	e2fc7332fe	G-087 stages 4+5: overlay merge primitive, marker/matrix retirement, version seeding Stage 4 - documented overlay semantics implemented (commandset::layout 0.2.0): layout_materialize resolves a layout to its overlay chain (vendor tier then custom tier per store+vendor, <name>@<base> derived-layout folders expanding their base chain first, cycle-guarded) and composes multi-folder chains into a disposable staging dir applying <item>.anti deletion markers (zero-byte marker files recommended - committable, unlike the originally documented empty marker folders, which are also accepted). Single-folder chains with no markers are used in place, so punk.project (store and zipfs modpod) behaviour is unchanged. project.new (commandset::project 0.4.0) copies from the materialized path and the layout listing/scanning commands show the effective merged view. Fixtures: punk.othersample is now a live derived layout (new custom-deck fauxlink ref + .gitignore.anti demo marker); extra.txt/store README rewritten to the implemented semantics. New tcltest suite src/tests/modules/punk/mix/testsuites/layout/materialize.test (20 tests). Anti markers deliberately stay a plain filename convention rather than tag-bearing fauxlinks: a fauxlink is a reference tooling may follow (fcat auto-follows), a marker is a tombstone with no target. Stage 5 - retirements and generated-project version seeding: - The empty unimplemented child-side src/PROJECT_LAYOUTS_CREATE_FROM_... marker folder is deleted along with its project.new and make.tcl sync exclusions. - The vendor/custom x _project matrix collapses for layouts: custom/<vendor> is the one override level; _project folders join no overlay chain (the pseudo-vendor remains for decktemplates module/utility templates only). - project.new seeds generated projects post-materialization (only-if-missing, never from payload): punkproject.toml ([project] name + 0.1.0), a matching CHANGELOG.md ## [0.1.0] header, and punkorigin.toml - an interim generation provenance baseline (utc, layout name + resolved store target, punk::mix::templates version, punkshell version when derivable, origin path) for the G-027 pull design to adopt (noted in G-027). Also: script-mode/programmatic project.new robustness (explicit shellrun require; punk::mix::util askuser/do_in_path/foreach-file fully qualified - the util:: shorthand exists only after cli commandset import). Includes the concurrently-landed (other session, previously uncommitted) 0.3.1 early module-name validation fix in project.new, shipped within the 0.4.0 bump. G-087 flipped achieved 2026-07-19 (verification in the detail file; archive move follows in the next commit). punkshell 0.16.0 -> 0.17.0. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	6 days ago
Julian Noble	eba0fe0098	goals: propose G-094/G-095 (punkcheck lifecycle unification + concurrent-writer safety); G-027 baseline reframe Outcomes of the 2026-07-19 punkcheck module review: - G-094 [proposed]: single OO record lifecycle - installtrack/installevent becomes the sole implementation with an eager\|deferred persistence policy, punkcheck::install rebuilt as an OO consumer in deferred mode, the zero-caller installfile_begin/finished/skipped trio retired to shims, and the o_record_list staleness fixed. The single save chokepoint is G-095's attachment point. - G-095 [proposed]: concurrent-writer safety - atomic temp+rename saves, advisory EXCL lockfile serializing whole installer events per punkcheck root, merge-on-flush for deferred mode, non-interactive-safe duplicate-INSTALLER recovery. SQLite recorded as rejected for now (TDL human readability/debugability overriding; three-part reconsideration bar). - G-027: acceptance reframed - .punkcheck records demoted from sole provenance basis to acceleration layer; safe-overwrite classification survives record loss via a committed baseline record (origin identity + pulled version, pristine content re-derivable from the origin's VCS), degrading conservatively (report/confirm - never silent overwrite, never a wedged pull). Approach classification bullet extended to match. - G-095 notes carry the tiered expendability taxonomy (build trees: recopies only; synced-targets bin/ deploy: non-self-healing skip wedge; derived projects: G-027 baseline) and the cross-tier invariant: absent records degrade to skip/confirm, never to overwrite. - (The G-087 cross-pointer to G-094/G-095 already landed with the stage-3 sources commit.) goals_lint clean (73 active-index goals, 22 archived). Claude-Session: https://claude.ai/code/session_01L7MfuYBfYpUFpVafo5JowC Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	6 days ago
Julian Noble	99af43c8be	goals: G-062 achieved archival + archive-loss prevention (sweep rules, backlink markers, goals_lint) Finalises the G-062 achieved flip staged by the prior session (punkshell 0.12.1): LICENSE.txt (BSD-2-Clause, Julian Marcel Noble 2023-2026) at the repo root, README/punkproject.toml/AGENTS.md license declarations, index record to GOALS-archive.md and detail file to goals/archive/. Archive-loss prevention, from the G-015 incident (its achieved-status verification parenthetical was silently dropped by the 2026-07-11 two-tier restructure's Status-line normalisation; the text is restored to the G-015 archive file's Notes with provenance): - root AGENTS.md 'Doc Restructures': deleted-line conservation check before committing bulk doc migrations, structured-field-normalisation hazard (relocate prose to body sections first), moves separated from edits - goals/AGENTS.md: lintable header field grammar (one line per field, bare Status values), flip-time verification evidence recorded in the body, the archive move content-identical, and a new archive-time reference sweep: pending-tense mentions of the archived goal updated in the live tier, and actionable archived notes pointed to from the affected live goal's Notes - GOALS.md maintenance rules: achieved-flip clause extended to require the evidence write-up and the reference sweep Retroactive reference sweep over all 12 archived goals (25 live detail files): pending-tense fixes (G-002 G-008 G-013 G-016 G-017 G-021 G-022 G-031 G-042 G-044 G-050 - G-017's Goal/Acceptance annotated as gate-satisfied, contract meaning unchanged), forward pointers pushed from archived notes (G-062 license-seeding follow-on -> G-012/G-027, G-037 vendorlib/vfs drift semantics -> G-024, G-058 static-baseline mechanism -> G-005), and one 'Archived-goal references' Notes bullet per remaining referencing file so every live mention of an archived goal is resolvable without consulting the archive index. scriptlib/developer/goals_lint.tcl (new, plain tclsh): validates detail-file header grammar, strict status values in both tiers, orphan rules in both directions, Status/Scope mirror consistency, plus an informational (never fatal) warning for live files referencing an archived goal with no achieved/archive marker - baseline now zero warnings. Root AGENTS.md scriptlib/developer ownership note widened to cover developer utilities. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 weeks ago
Julian Noble	ae04b3f8c9	GOALS: two-tier index restructure - summary-only GOALS.md, canonical Goal/Acceptance in detail files, archive-on-flip - GOALS.md collapsed to summary entries (ID/status/title/Scope/detail pointer): 104.6KB -> 23KB so a full read stays cheap; Scope lines kept verbatim so path-grep goal discovery still works - canonicality split: index canonical for ID/status/title/Scope, detail file canonical for Goal:/Acceptance:; all 61 detail-file headers reconciled from the index (fixes stale copies, e.g. G-036 detail acceptance predated the achieved rework), bodies preserved untouched - detail files created for the three index-only goals G-017, G-034, G-054; every goal now has one - 10 achieved goals (G-007 G-015 G-036 G-037 G-040 G-046 G-049 G-054 G-058 G-059) archived: summary records appended to GOALS-archive.md, detail files moved to goals/archive/; archive-on-flip replaces the ~30-achieved-entries trigger - GOALS.md preamble/rules reworked: read workflow (read index in full, then detail files of scope-intersecting goals before editing), contract spans both tiers with proposal-first unchanged, next-free-ID counts the archive, achieved flip judged against the detail-file Acceptance and includes archiving - progress convention codified from G-001 increment-1 practice: index entries carry status only, never progress; incremental progress lives in the detail file's ## Progress section (landed/remaining); achieved flip requires the remaining-work list resolved - a partial increment never flips a goal - goals/AGENTS.md rewritten for the split (required 4-field header, one detail file per goal, orphan rules covering archive/); root AGENTS.md Child DOX Index + Repo-wide Notes updated; GOALS-archive.md preamble updated - stale detail-file paths updated to goals/archive/ in src/lib/app-punkscript/punkscript.tcl (comment), runtimebash_wsl.test, wslprobe.tcl and the G-042 detail file; propagated copies (root lib/, src/vfs/_vfscommon.vfs, src/_build) left to refresh via normal build steps - no project version bump: governance docs and source comments only, no user-visible shell behaviour Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 weeks ago
Julian Noble	7d1d1aa386	commit conventions VCS-neutral; template DOX/goals ownership design input Root AGENTS.md "Git Commit Conventions" renamed "Commit Conventions (any VCS)": the Co-Authored-By/AI-attribution ban and the Assisted-by trailer apply to git commits and fossil checkins alike (git parses trailers structurally, fossil comments are free text - either way the trailer is the last line of the message). Generated projects start fossil-only but may adopt git; punkshell itself is git-primary today and could flip. CLAUDE.md mirror section updated to match. G-027 detail: documentation/goals ownership design input - layout-owned child AGENTS.md docs ride the pull channel under the unmodified-since-install classification; project-owned skeletons (thin root AGENTS.md, GOALS.md, goals/AGENTS.md, empty GOALS-archive.md) are seeded once and never pulled; commit conventions are part of the seed (developer-changeable, VCS-neutral); layout-owned marker convention; transitive chains inherit the parent''s modified docs as their baseline. G-012 detail: AGENTS.md template payloads recorded as the same hazard class as live .gitignore payloads - a template AGENTS.md under src/project_layouts/ is binding DOX for agents walking the punkshell tree though written for generated projects; needs the same inert storage + materialize-at-generation treatment. First field test: the tomlish project was seeded today with the thin root AGENTS.md + CLAUDE.md + GOALS framework this design describes. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	3 weeks ago
Julian Noble	92f6c30442	add goal G-027: pull-based infrastructure updates for derived projects Projects generated by dev project.new receive a layout snapshot that drifts; the current remedy is a push from punkshell (project.new -force 1 -update 1). G-027: one command run inside the derived project pulls make.tcl/build.tcl, bootsupport modules/libs and template payloads from the originating punkshell project - .punkcheck records remain the provenance basis, origin identity becomes durable to workdir moves (not relative paths alone; projects.work discovery as re-locator), VCS awareness on both ends (G-026 clean-checkout policy on the source, uncommitted-local-modification detection on the target), and the remote-pull question gets a recorded decision. Detail file records the motivating incident (tomlish 2026-07-06: a stale make.tcl whose bootsupport updater was disabled by the very drift it needed to fix - broken bundled fileutil::traverse under Tcl 9) and the constraint that the pull entrypoint must not depend on the freshness of what it updates. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	3 weeks ago

6 Commits (9f4ff1db626e49c7f6f802e4bb50c48edee1b906)