punkshell

802 Commits

1 Branch

1 Tag

191 MiB

Commit Graph

Author	SHA1	Message	Date
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	3 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	3 weeks ago
Julian Noble	9948810b9b	G-042, G-043 proposed: subshell help topics via punk::config; subshell definition plugins (punk.subshell capability) Both user-approved after a review of the intended plugin facility (punk::mix::init pluginmgr todos, the punk::pluginmgr 0.5.1 tcllib fork, punk::cap provider/handler system, punk::cap::handlers::templates pathtype resolution, punk::overlay commandset composition and its toml-CLI todo). - G-042: a named subshell declares help topics (name/aliases/summary/text) in punk::config stored configuration, registered into the ::punk::helptopic registry on entry and restored on exit, with an explicit shadowing policy. Text-content only - config is data; code-bearing topics belong to the plugin path where the trust story lives. Detail file records the registry seam (punk 0.2.0), dependencies (hard on G-014; beneficial G-040/G-008/G-009), and the plugin-facility relationship from the review. - G-043: the umbrella for that plugin path - a punk.subshell capability whose providers supply commandset bindings (punk::overlay import), help topics (G-042's registry API) and config defaults per named subshell, with a validating punk::cap handler, an equivalent data-only stored-config declaration path (absorbing punk::overlay's ".toml configuration files for defining CLI configurations" todo), and punk::pluginmgr as the discovery/ safe-interp trust layer for untrusted providers. Also absorbs punk::cap housekeeping found in the review: pkg_unregister api-object cleanup and unhandled-capability discoverability (the deliberate punk.isbogus silence). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	3 weeks ago

Author

SHA1

Message

Date

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

3 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

3 weeks ago

Julian Noble

9948810b9b

G-042, G-043 proposed: subshell help topics via punk::config; subshell definition plugins (punk.subshell capability)

Both user-approved after a review of the intended plugin facility (punk::mix::init
pluginmgr todos, the punk::pluginmgr 0.5.1 tcllib fork, punk::cap provider/handler
system, punk::cap::handlers::templates pathtype resolution, punk::overlay
commandset composition and its toml-CLI todo).

- G-042: a named subshell declares help topics (name/aliases/summary/text) in
  punk::config stored configuration, registered into the ::punk::helptopic
  registry on entry and restored on exit, with an explicit shadowing policy.
  Text-content only - config is data; code-bearing topics belong to the plugin
  path where the trust story lives. Detail file records the registry seam
  (punk 0.2.0), dependencies (hard on G-014; beneficial G-040/G-008/G-009),
  and the plugin-facility relationship from the review.
- G-043: the umbrella for that plugin path - a punk.subshell capability whose
  providers supply commandset bindings (punk::overlay import), help topics
  (G-042's registry API) and config defaults per named subshell, with a
  validating punk::cap handler, an equivalent data-only stored-config
  declaration path (absorbing punk::overlay's ".toml configuration files for
  defining CLI configurations" todo), and punk::pluginmgr as the discovery/
  safe-interp trust layer for untrusted providers. Also absorbs punk::cap
  housekeeping found in the review: pkg_unregister api-object cleanup and
  unhandled-capability discoverability (the deliberate punk.isbogus silence).

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

3 weeks ago

3 Commits (456fa80500f4af1a475317f2c472d2aff3f5b276)