Goals: draft G-147/G-148 (user-approved proposals)

G-147 libfetch revision check: read-only report of newer server revisions for declared artifacts (Tin check/upgrade translated to punkbin's deliberate-adopt discipline). G-148 vendor upstream discovery: read-only ref/tag listing + pin-drift report for G-065 declared packages (Tin autoadd translated to hand-authored-declaration discovery). Cross-linked as siblings; back-pointers added to G-141/G-142/G-065.

Assisted-by: harness=opencode; primary-model=huggingface/moonshotai/Kimi-K3; api-location=unknown

GOALS.md

@@ -406,3 +406,11 @@ Detail: goals/G-144-punkargs-synopsis-name-fallback.md
 Scope: src/project_layouts/ (.fossil-settings payloads); src/make.tcl (thin-layout sync, if derivation chosen); src/modules/punk/mix/commandset/project-999999.0a1.0.tm (generation-time fossil commit path)
 Detail: goals/G-146-fossil-binary-glob-seeding.md
 
+### G-147 [proposed] libfetch revision check: read-only report of newer server revisions for declared artifacts
+Scope: src/make.tcl (libfetch check/report surface); src/runtime/libpackages.toml (declared revisions as input); src/tests/shell/testsuites/punkexe/maketcllibfetch.test (characterization); bin/AGENTS.md + src/runtime/AGENTS.md (report documentation)
+Detail: goals/G-147-libfetch-revision-check.md
+
+### G-148 [proposed] Vendor upstream discovery: read-only ref/tag listing and pin-drift report for declared packages
+Scope: src/modules/punk/mix/ (vendor-sync command surface - discovery beside the G-065 sync); punkproject.toml or sibling vendor manifest (G-065 declaration schema as consumed); src/tests/modules/punk/mix/ (discovery testsuite with local fixture upstreams)
+Detail: goals/G-148-vendor-upstream-discovery.md
+

goals/G-065-declarative-vendoring.md

@@ -63,6 +63,9 @@ remains the punkshell format (G-024 direction).
   those declarations consume), G-047 (punkproject.toml [workflow] schema
   co-tenant - if the manifest lives in punkproject.toml, the two schemas must not
   collide).
+- Related: G-148 - read-only upstream ref/tag discovery adjunct for declared
+  packages (pin-drift reporting); lands after this goal's manifest schema
+  exists and consumes its declarations.
 - Proving case: tcl_oauth2_library. A hand-trimmed copy (keeping
   LICENSE/license.terms/README/examples) was placed in src/vendorlib and load-tested
   with the punk91 src shell on 2026-07-12, then deliberately removed before ever being

goals/G-141-libfetch-target-selection.md

@@ -117,6 +117,9 @@ has no equivalent of "materialize what this checkout needs".
   "declared artifact not in the server's current listing" warning coordinates
   with this goal's libfetch surface (whichever lands second adopts the
   other's vocabulary).
+- Related: G-147 - libfetch revision check (read-only newer-revision
+  report); joins this goal's and G-142's shared libfetch vocabulary
+  coordination as a third party.
 - Overlap survey 2026-07-31 (drafting): goals_xref paths over src/make.tcl,
   src/runtime/libpackages.toml, src/runtime/vendorlib_vfs.toml, bin/packages,
   src/tests/shell/testsuites/punkexe - strongest live intersections G-127 and

goals/G-142-punkbin-listing-manifests.md

@@ -34,6 +34,9 @@ User direction shaping the design (2026-07-31): grouping is a first-class need -
 - Related: G-123 (achieved 2026-07-31 - see goals/archive/G-123-thirdparty-runtime-tiers.md) - runtime-tier twin; this goal's manifest sits beside its retroactive sidecars and schema-v2 records.
 - Related: G-138/G-139/G-140 (archived) - the lib tier's emission/consumption; the manifest mechanism serves lib/<target>/ identically to runtime tiers, and libfetch is a consumer.
 - Related: G-141 - libfetch target selection; the libfetch-side "declared artifact not in the server's current listing" warning is a coordinated surface (whichever lands second adopts the other's vocabulary), not a dependency.
+- Related: G-147 - libfetch revision check; its absent-from-listing status
+  absorbs this goal's libfetch-side drift warning into the wider read-only
+  report, and its carved-out status reads this goal's group semantics.
 - Related: G-067 - the future .tm module artifact channel inherits this listing idiom (its artifact sets have the same growth shape); recorded here so the channel design adopts rather than reinvents.
 - Related: G-006 - absorbs fetch/consent mechanisms when it lands; the listing mechanism must survive that absorption.
 - Related: G-119 (archived) - the list -remote freshness/row vocabulary this goal extends.

goals/G-147-libfetch-revision-check.md

@@ -0,0 +1,43 @@
+# G-147 libfetch revision check: read-only report of newer server revisions for declared artifacts
+
+Status: proposed
+Scope: src/make.tcl (libfetch check/report surface); src/runtime/libpackages.toml (declared revisions as input); src/tests/shell/testsuites/punkexe/maketcllibfetch.test (characterization); bin/AGENTS.md + src/runtime/AGENTS.md (report documentation)
+Goal: 'make.tcl libfetch' answers "is there a newer revision of what I have declared?" as a first-class read-only report - comparing each declared artifact's pinned revision against the server's per-tier sha1sums.txt (and the current-group listing where a G-142 manifest exists) - so revision adoption stays a deliberate libpackages.toml edit informed by the report, never a client-side auto-upgrade.
+Acceptance: a libfetch check mode (flag or subcommand settled in the work) reports per declared artifact: declared revision, newest revision present on the server, and status vocabulary covering at least up-to-date / newer-available / absent-from-listing (the G-142 drift case) / carved-out (a newer revision exists but sits in a hidden G-142 group such as vulnerable or archive - reported distinctly, never silently recommended); the mode is read-only - it fetches only the server ledger/listing files, writes nothing to bin/packages, and edits no declaration; output has a machine-parsable form (the G-064 direction); behaviour is characterized in maketcllibfetch.test through the existing PUNK_LIBFETCH_CONFIG / fixture seams; vocabulary coordination with G-141 and G-142 is recorded (whichever of the three lands second adopts the landed one's terms).
+
+## Context
+
+Drafted 2026-08-01 from the Tin package-manager comparison (Tin's `tin check` /
+`tin upgrade` make "is there a newer one?" a first-class client question).
+The punkbin-shaped answer is report-only: punkbin artifacts are immutable
+-r<N> revisions and adoption is a deliberate declaration bump (the
+deliberate-publish/deliberate-adopt discipline of G-138, archived), so Tin's
+auto-upgrade flow has no punkbin analogue - the check informs the edit, the
+edit stays manual. Consent keying is inherited unchanged from the fetch path
+(canonical origin queries gate nothing; other origins need -trust-server).
+
+## Notes
+
+- Related: G-141 - libfetch target selection; the check consumes the same
+  declared set and derivation reporting (whichever lands second adopts the
+  other's vocabulary).
+- Related: G-142 - listing manifests; the current/vulnerable/archive group
+  semantics are what the check's carved-out status reads. Its libfetch-side
+  "declared artifact absent from the server's current listing" warning is
+  this report's absent-from-listing case, absorbed into the wider report.
+- Related: G-006 - absorbs the consent surface when it lands; the check must
+  survive that absorption.
+- Related: G-067 - the future .tm module artifact channel inherits this
+  check idiom for module artifacts.
+- Related: G-139 (archived - goals/archive/G-139-punkbin-library-consumption.md) -
+  created libfetch; this goal adds the revision-freshness dimension.
+- Related: G-148 - the vendor-upstream sibling drafted from the same Tin
+  comparison; both are read-only reports that inform a deliberate
+  declaration edit (libpackages.toml here, the G-065 vendor manifest there)
+  rather than acting on what they find.
+- Overlap survey 2026-08-01 (drafting): goals_xref paths over src/make.tcl,
+  src/runtime/libpackages.toml, bin/packages/,
+  src/tests/shell/testsuites/punkexe/maketcllibfetch.test - strongest live
+  intersections G-141 (direct sibling), G-005/G-006/G-023/G-101/G-131
+  (sibling-path adjacency only); G-142 relation from the libfetch
+  coordination clause in its contract; no contract-level conflicts found.

goals/G-148-vendor-upstream-discovery.md

@@ -0,0 +1,41 @@
+# G-148 Vendor upstream discovery: read-only ref/tag listing and pin-drift report for declared packages
+
+Status: proposed
+Scope: src/modules/punk/mix/ (vendor-sync command surface - discovery beside the G-065 sync); punkproject.toml or sibling vendor manifest (G-065 declaration schema as consumed); src/tests/modules/punk/mix/ (discovery testsuite with local fixture upstreams)
+Goal: for packages declared in the G-065 vendor manifest, a read-only discovery command answers "what refs/tags exist upstream?" and reports pin drift (declared pin vs newest matching upstream ref) - so pin selection at declaration time and pin-bump decisions later are informed by the upstream's actual version surface, without retrieving payloads or changing any state.
+Acceptance: the discovery command (home settled in the work, beside the G-065 sync surface) lists upstream tags/refs for a named declared package or all declared packages without materializing anything; a pin-drift report classifies each declared package as up-to-date / behind (naming the newest matching ref) / unpinned-resolves-to (what an unpinned declaration would resolve to today); git upstreams are supported via ls-remote, with fossil and http-archive upstream kinds supported or recorded as deferred with rationale; the command is strictly read-only - no materialization, no manifest edits, no provenance records written; tests run against local fixture repositories with no network access; the relationship to G-065 (adjunct surface landing after its manifest schema) is recorded.
+
+## Context
+
+Drafted 2026-08-01 from the Tin package-manager comparison: Tin's
+`tin autoadd` discovers versions by querying git tags (`git ls-remote
+--tags`) and auto-registers every match. The punkshell-shaped adoption keeps
+declarations hand-authored (the G-065 manifest is a deliberate declaration,
+not an auto-populated database) and uses discovery only to INFORM pins:
+what to pin at declaration time, and when a declared pin has drifted behind
+upstream. Discovery of a newer upstream ref never triggers a sync - the bump
+is a manifest edit followed by the G-065 sync, preserving the
+declaration-driven model.
+
+## Notes
+
+- Related: G-065 - the parent surface; this goal is its read-only adjunct
+  and lands after the manifest schema exists (dependency direction: this
+  goal consumes G-065's declarations).
+- Related: G-063 - a pin bump informed by this report is the natural
+  re-trigger point for license-verification provenance on the new version.
+- Related: G-047 - punkproject.toml schema co-tenant if the G-065 manifest
+  lives there (no new fields expected; recorded to keep the schemas
+  collision-free).
+- Related: G-026 - local-pull provenance sibling; discovery here covers
+  EXTERNAL upstreams, which G-026 deliberately does not.
+- Related: G-147 - the libfetch revision-check sibling drafted from the same
+  Tin comparison; both are read-only reports that inform a deliberate
+  declaration edit (the G-065 vendor manifest here, libpackages.toml there)
+  rather than acting on what they find.
+- Overlap survey 2026-08-01 (drafting): goals_xref paths over
+  punkproject.toml, src/modules/punk/mix/, src/vendorlib/,
+  src/vendormodules/ - surfaced G-065 (parent, carried as Related),
+  G-063/G-067/G-004 (vendor-area co-tenants, domain-distinct), G-047/G-137
+  (punkproject.toml co-tenants), G-026 (include_modules.config adjacency);
+  no contract-level conflicts found.