Browse Source
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.commaster
45 changed files with 357 additions and 32 deletions
@ -0,0 +1,24 @@
|
||||
BSD 2-Clause License |
||||
|
||||
Copyright (c) 2023-2026 Julian Marcel Noble |
||||
|
||||
Redistribution and use in source and binary forms, with or without modification, |
||||
are permitted provided that the following conditions are met: |
||||
|
||||
1. Redistributions of source code must retain the above copyright notice, this |
||||
list of conditions and the following disclaimer. |
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright notice, this |
||||
list of conditions and the following disclaimer in the documentation and/or |
||||
other materials provided with the distribution. |
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR |
||||
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
||||
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT |
||||
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, |
||||
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
||||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
||||
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
||||
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE |
||||
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF |
||||
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||||
@ -1,3 +1,4 @@
|
||||
[project] |
||||
name = "punkshell" |
||||
version = "0.12.0" |
||||
version = "0.12.1" |
||||
license = "BSD-2-Clause" |
||||
|
||||
@ -0,0 +1,218 @@
|
||||
#!/usr/bin/env tclsh |
||||
# goals_lint.tcl - lint the two-tier goals documentation |
||||
# (root GOALS.md / GOALS-archive.md indexes + goals/ / goals/archive/ detail files) |
||||
# |
||||
# Validates the contracts declared in goals/AGENTS.md and root AGENTS.md: |
||||
# - detail-file header grammar: '# G-<id> <title>' then a blank line, then |
||||
# Status:/Scope:/Goal:/Acceptance: exactly once each, in order, one line each, |
||||
# before any '## section'; no prose riding a header field |
||||
# - Status: values are exactly one of proposed|active|abandoned|superseded or |
||||
# 'achieved YYYY-MM-DD' |
||||
# - active-tree detail files are not 'achieved'; archive detail files are |
||||
# - no orphans: every goals/*.md detail file has a GOALS.md index entry and vice |
||||
# versa; every goals/archive/*.md file has a GOALS-archive.md record and vice versa |
||||
# - Status:/Scope: mirror lines in detail files match the owning index entry |
||||
# |
||||
# Plain tclsh (8.6+ or 9), no package dependencies - runnable from any checkout: |
||||
# tclsh scriptlib/developer/goals_lint.tcl [repo-root] |
||||
# Exit 0 when clean; exit 1 with one 'path: problem' line per finding. |
||||
|
||||
set root [expr {$argc >= 1 ? [lindex $argv 0] : [file dirname [file dirname [file dirname [file normalize [info script]]]]]}] |
||||
if {![file isfile [file join $root GOALS.md]] || ![file isdir [file join $root goals]]} { |
||||
puts stderr "goals_lint: '$root' does not look like the punkshell repo root (need GOALS.md and goals/)" |
||||
exit 2 |
||||
} |
||||
|
||||
set findings {} |
||||
proc flag {path msg} { |
||||
global findings |
||||
lappend findings "$path: $msg" |
||||
} |
||||
|
||||
set status_re {^(proposed|active|abandoned|superseded|achieved \d{4}-\d{2}-\d{2})$} |
||||
|
||||
proc read_lines {path} { |
||||
set f [open $path r] |
||||
fconfigure $f -encoding utf-8 |
||||
set lines [split [read $f] \n] |
||||
close $f |
||||
return $lines |
||||
} |
||||
|
||||
# --- parse an index file (GOALS.md or GOALS-archive.md) --------------------- |
||||
# returns dict: id -> {status <s> title <t> scope <scope-or-empty>} |
||||
proc parse_index {path} { |
||||
global status_re |
||||
set entries [dict create] |
||||
set relpath [file tail $path] |
||||
set curid "" |
||||
foreach line [read_lines $path] { |
||||
if {[regexp {^### G-(\d+) \[([^\]]*)\] (.*)$} $line -> id status title]} { |
||||
set curid $id |
||||
if {[dict exists $entries $id]} { |
||||
flag $relpath "duplicate index entry G-$id" |
||||
} |
||||
if {![regexp $status_re $status]} { |
||||
flag $relpath "G-$id: bad status '\[$status\]' (want proposed|active|abandoned|superseded|achieved YYYY-MM-DD)" |
||||
} |
||||
dict set entries $id [dict create status $status title $title scope ""] |
||||
} elseif {[regexp {^### } $line]} { |
||||
set curid "" |
||||
} elseif {$curid ne "" && [regexp {^Scope: (.*)$} $line -> scope]} { |
||||
dict set entries $curid scope $scope |
||||
} |
||||
} |
||||
return $entries |
||||
} |
||||
|
||||
# --- lint one detail file ---------------------------------------------------- |
||||
# returns dict {id <id> status <s> scope <s>} (empty strings when unparseable) |
||||
proc lint_detail {path relpath} { |
||||
global status_re |
||||
set lines [read_lines $path] |
||||
set fname [file tail $path] |
||||
set result [dict create id "" status "" scope ""] |
||||
|
||||
if {![regexp {^G-(\d+)-[a-z0-9-]+\.md$} $fname -> fid]} { |
||||
flag $relpath "filename does not match G-<id>-<slug>.md" |
||||
set fid "" |
||||
} |
||||
dict set result id $fid |
||||
|
||||
if {![regexp {^# G-(\d+) .+$} [lindex $lines 0] -> hid]} { |
||||
flag $relpath "line 1 is not '# G-<id> <title>'" |
||||
set hid "" |
||||
} |
||||
if {$fid ne "" && $hid ne "" && $hid ne $fid} { |
||||
flag $relpath "title-line id G-$hid does not match filename id G-$fid" |
||||
} |
||||
if {[lindex $lines 1] ne ""} { |
||||
flag $relpath "line 2 is not blank" |
||||
} |
||||
|
||||
# header fields: Status/Scope/Goal/Acceptance exactly once each, in order, |
||||
# before the first '## ' section |
||||
set want {Status Scope Goal Acceptance} |
||||
set found [dict create] |
||||
set order {} |
||||
set i 2 |
||||
foreach line [lrange $lines 2 end] { |
||||
incr i |
||||
if {[regexp {^## } $line]} break |
||||
if {[regexp {^(Status|Scope|Goal|Acceptance): ?(.*)$} $line -> field value]} { |
||||
if {[dict exists $found $field]} { |
||||
flag $relpath "duplicate header field '$field:' (line $i)" |
||||
} else { |
||||
dict set found $field $value |
||||
lappend order $field |
||||
} |
||||
if {$value eq ""} { |
||||
flag $relpath "empty header field '$field:' (line $i)" |
||||
} |
||||
} |
||||
} |
||||
foreach field $want { |
||||
if {![dict exists $found $field]} { |
||||
flag $relpath "missing header field '$field:'" |
||||
} |
||||
} |
||||
if {[llength $order] == 4 && $order ne $want} { |
||||
flag $relpath "header fields out of order ([join $order /] - want [join $want /])" |
||||
} |
||||
|
||||
if {[dict exists $found Status]} { |
||||
set status [dict get $found Status] |
||||
dict set result status $status |
||||
if {![regexp $status_re $status]} { |
||||
flag $relpath "bad Status line 'Status: $status' - must be exactly proposed|active|abandoned|superseded or 'achieved YYYY-MM-DD' with no additional prose (verification evidence belongs in ## Progress / ## Notes)" |
||||
} |
||||
} |
||||
if {[dict exists $found Scope]} { |
||||
dict set result scope [dict get $found Scope] |
||||
} |
||||
return $result |
||||
} |
||||
|
||||
# --- run ---------------------------------------------------------------------- |
||||
set active_index [parse_index [file join $root GOALS.md]] |
||||
set archive_index [parse_index [file join $root GOALS-archive.md]] |
||||
|
||||
foreach {dir index indexname achieved_expected} [list \ |
||||
goals $active_index GOALS.md 0 \ |
||||
[file join goals archive] $archive_index GOALS-archive.md 1] { |
||||
set seen [dict create] |
||||
foreach path [lsort [glob -nocomplain -directory [file join $root $dir] G-*.md]] { |
||||
set relpath [string map {\\ /} [file join $dir [file tail $path]]] |
||||
set info [lint_detail $path $relpath] |
||||
set id [dict get $info id] |
||||
if {$id eq ""} continue |
||||
dict set seen $id 1 |
||||
set achieved [string match "achieved *" [dict get $info status]] |
||||
if {$achieved_expected && !$achieved && [dict get $info status] ne ""} { |
||||
flag $relpath "archived detail file Status is '[dict get $info status]' - archive/ holds achieved goals only" |
||||
} elseif {!$achieved_expected && $achieved} { |
||||
flag $relpath "achieved goal still in goals/ - the achieved flip includes archiving (move to goals/archive/, record in GOALS-archive.md)" |
||||
} |
||||
if {![dict exists $index $id]} { |
||||
flag $relpath "orphan detail file - no G-$id entry in $indexname" |
||||
continue |
||||
} |
||||
set entry [dict get $index $id] |
||||
if {[dict get $info status] ne "" && [dict get $info status] ne [dict get $entry status]} { |
||||
flag $relpath "Status mirror '[dict get $info status]' disagrees with $indexname '\[[dict get $entry status]\]' (index wins)" |
||||
} |
||||
if {[dict get $info scope] ne "" && [dict get $entry scope] ne "" \ |
||||
&& [dict get $info scope] ne [dict get $entry scope]} { |
||||
flag $relpath "Scope mirror disagrees with $indexname (index wins)" |
||||
} |
||||
} |
||||
foreach id [dict keys $index] { |
||||
if {![dict exists $seen $id]} { |
||||
flag $indexname "G-$id has no detail file in $dir/" |
||||
} |
||||
} |
||||
} |
||||
|
||||
# --- informational: candidate stale references to archived goals --------------- |
||||
# An active detail file mentioning an archived goal with no achieved/archive/landed |
||||
# marker on ANY of the mentioning lines has likely missed the archive-time reference |
||||
# sweep (goals/AGENTS.md Archive rules) - a reader cannot tell the referenced goal is |
||||
# done. One marked mention per file suffices; pure-history mentions on other lines |
||||
# are fine. Heuristic - reported as warnings, never fatal. |
||||
set warnings {} |
||||
foreach path [lsort [glob -nocomplain -directory [file join $root goals] G-*.md]] { |
||||
set relpath goals/[file tail $path] |
||||
set mentioned [dict create] ;# id -> 1 when any mentioning line carries a marker |
||||
set lines [read_lines $path] |
||||
set n [llength $lines] |
||||
for {set i 0} {$i < $n} {incr i} { |
||||
set line [lindex $lines $i] |
||||
# marker may sit on the mention line or a wrapped neighbour |
||||
set window "$line [lindex $lines [expr {$i-1}]] [lindex $lines [expr {$i+1}]]" |
||||
set marked [regexp -nocase {achieved|archive|landed} $window] |
||||
foreach id [regexp -all -inline {G-\d+} $line] { |
||||
set num [string range $id 2 end] |
||||
if {![dict exists $archive_index $num]} continue |
||||
if {$marked || ![dict exists $mentioned $num]} { |
||||
dict set mentioned $num $marked |
||||
} |
||||
} |
||||
} |
||||
dict for {num marked} $mentioned { |
||||
if {!$marked} { |
||||
lappend warnings "$relpath: references archived goal G-$num with no achieved/archive marker anywhere - reference sweep candidate (goals/AGENTS.md Archive rules)" |
||||
} |
||||
} |
||||
} |
||||
|
||||
if {[llength $warnings]} { |
||||
puts stderr "goals_lint: [llength $warnings] informational warning(s):" |
||||
puts stderr [join $warnings \n] |
||||
} |
||||
if {[llength $findings]} { |
||||
puts [join $findings \n] |
||||
puts stderr "goals_lint: [llength $findings] finding(s)" |
||||
exit 1 |
||||
} |
||||
puts "goals_lint: clean ([dict size $active_index] active-index goals, [dict size $archive_index] archived)" |
||||
exit 0 |
||||
Loading…
Reference in new issue