[aitrawog]

Summary

verb:git-submodules in mode: currency answers ONE question — is each recorded pin the ref its
intent names? — and it answers it correctly. What it could not answer is the question a repo
that owns the pin needs: how long has this repo itself neglected to advance it?

This PR adds that answer as an opt-in knob, stale_after, on the currency mode.

The defect it closes, measured. From opencharly/charly's own advance history against each
box/* upstream's commit dates, 2026-09-22 → 2026-10-23 (behind-time as the union of the
behind-intervals, not the sum of overlapping per-commit lags):

twin	behind-time	share of the window	continuous behind-windows	max continuous behind
box/arch	554 h	73.7 %	4	237 h
box/cachyos	589 h	78.4 %	5	230 h
box/debian	566 h	75.4 %	4	238 h
box/fedora	564 h	75.0 %	4	237 h
box/ubuntu	578 h	77.0 %	4	238 h
box/omarchy	371 h	49.4 %	4	196 h

Two regimes hide in that table and must not be confused:

• CHURN — a twin whose upstream moves daily is behind between every wave. That is the normal
  state of a healthy tree.
• NEGLECT — what actually recurred was the owner's advance cadence: gaps of 8 days
  (10-06 → 10-16) and 10 days (09-28 → 10-06) with no advance at all, against a healthy
  maximum gap of 5 days (10-16 → 10-21). Every twin's own bookkeeping age is ≤ 1 day today.

The criterion that was first proposed, and why it is not this one. The RCA filed as
opencharly/charly#1048 proposed: fail when a twin is behind the ref its own .gitmodules
declares. The table above falsifies it — that gate would be red roughly three days out of four on
a perfectly healthy tree, and the org's own pin rule forbids exactly that:

Only a pin the workflow cannot JUDGE, or two sides that DISAGREE, is a failure; behind and a
blocked-by that names a producer leg PASS and are REPORTED … a gate that failed there would be
permanently red — which trains every reader to ignore it, the mirror problem inverted.

So the criterion was re-derived against the measurement, not implemented as written.

What stale_after does.

• The bound is on the AGE of the owner's own last commit that touched the pin's path — never
  on the pin's distance from the served ref. The distance is churn; the age is neglect.
• A pin that is not current AND has not been advanced within the bound is STALE, and a
  stale pin FAILS.
• A cur pin is never stale, however old its last advance: a quiet upstream is not neglect,
  and no quiet repo may go red on its own silence.
• A blocked-by edge is not eligible: the producer's neglect is the producer's business, and
  failing here over another repo's PR is the permanently-red trap again.
• Unset ⇒ off. The verdict and the report are byte-unchanged, so no repo sees a behaviour
  change until it declares a bound.

Where it lives, and why. In the canonical judgement — this verb — with the schema as the single
source (candy/plugin-task/schema/task.cue → the regenerated candy/plugin-task/params/cue_types_gen.go).
The owner declares the bound in its own manifest; no repo re-derives "is the pin at the tip" for
itself, and no second implementation of the currency judgement appears anywhere.

The calibration. The healthy maximum gap between advances was 5 days and the neglect gaps were
8 and 10 days, so a 7-day (168 h) bound sits above the healthy maximum and below the neglect
minimum, with margin on both sides.

The consumer side — the owner declaring the bound and advancing its twin through
charly task sync — is opencharly/charly#1048 and lands separately, producer-first.

How tested

The change class is a plugin-library + schema change, so it runs this repo's FULL bed, on the
committed tree this PR pushes (01484d2ed659743b076eca3d17a9c5b5d2d79956).

### HEAD: 01484d2ed659743b076eca3d17a9c5b5d2d79956

$ cd candy/plugin-task && go build ./...
exit=0

$ go test -count=1 ./...
ok  	github.com/opencharly/plugin-task/candy/plugin-task	4.006s
?   	github.com/opencharly/plugin-task/candy/plugin-task/cmd/serve	[no test files]
?   	github.com/opencharly/plugin-task/candy/plugin-task/params	[no test files]
exit=0

$ go vet ./...
exit=0

$ gofmt -l .
exit=0

$ GOTOOLCHAIN=go1.26.4 golangci-lint run ./...   # the toolchain candy/plugin-task/go.mod declares
0 issues.
exit=0

$ charly box validate
charly box validate: OK — checked 1 candy, 7 distros, 7 builders; 0 warnings, 0 errors
exit=0

The live gate — the only live execution of these verbs (scripts/gate-task.sh, exit 0), with
the new arm driving the knob through a real charly binary with this plugin compiled in:

== verb:git-submodules currency (stale_after: a pin NEGLECTED past the bound must FAIL) ==
   | task currency-stale: 1 step(s), 1 failed
   |   [fail] check — no pin is neglected past the bound
   |       currency: 1 of 1 pin(s) NOT current [1 behind]; intents: 1 upstream leaf/leaves (1 implicit), 0 derived-from edge(s); NOT CURRENT: gap: behind; intent upstream:main (implicit: .gitmodules branch=); recorded ad4a1d5266; served db862d8e40 (branch); 1 STALE pin(s) (neglected for more than 168h): gap: behind, and this repo has not advanced it for 59709h (bound 168h) — advance it: mode=bump advances every pin to the ref its intent names; FAILED on the STALE pin(s) above; producer-first legs: gap (ad4a1d5266 -> db862d8e40)
   | charly: error: command "task": task "currency-stale" failed (1 step(s) failed)
== verb:git-submodules currency (stale_after: the SAME pin, advanced recently, must PASS) ==
   the same behind pin, advanced recently, passed the bound
...
gate-task: PASS — command:task + all five maintenance verbs executed live against charly main
GATE_EXIT=0

R7 — the coverage fails without the change. Reverting only candy/plugin-task/verbs.go to
HEAD and re-running the new test (the schema and the generated params kept, so the knob is
accepted and ignored — the worst possible shape, and the one this test exists to catch):

--- FAIL: TestGitSubmodules_CurrencyStalenessBoundsNeglect (0.05s)
    currency_test.go:462: a pin neglected for longer than the bound must fail; got pass: currency: 1 of 2 pin(s) NOT current [1 behind, 1 cur]; ... producer-first legs: src (83ccc6a6b0 -> 6fea073ee5)
FAIL
WITHOUT_CHANGE_RC=1

and with the change restored, the same test passes.

The one-variable differential, in the unit test (candy/plugin-task/currency_test.go,
TestGitSubmodules_CurrencyStalenessBoundsNeglect): the same fixture, the same behind pin and the
same 168h bound, with only the DATE of the commit that recorded the pin changed —

1. knob unset → PASS, and the report contains no STALE (the opt-in is real, and the default
   verdict is unchanged);
2. old date (240 h) → FAIL, 1 STALE pin(s) (neglected for more than 168h), naming the pin,
   its age and the bound;
3. recent date (1 min) → PASS with 1 of 2 pin(s) NOT current still reported — churn, not
   neglect;
4. a cur pin with a 240 h old advance → PASS — the idle-upstream trap;
5. a malformed bound (7d) → FAIL with not a duration — a broken control is never silent.

Rulebook compliance

• R0 — the skills this area selects (/charly-internals:plugin, /charly-image:layer,
  /charly-internals:git-workflow) were loaded before the first edit.
• R1 — the first criterion (fail on distance) was falsified by measurement and re-derived
  before it was implemented; the RCA is currency mode: nothing bounds NEGLECT — a pin that is not current is churn, and the owner can stop advancing it forever unnoticed #42. The one non-blocking finding
  raised while gating (the local linter's export-data skew) is filed below.
• R2 — one implementation: the bound lives in the canonical currency judgement, and no repo
  re-derives "is the pin at the tip" for itself. The schema is the single source for the params
  struct, and the regeneration is byte-reproducible from it.
• R3 — no workaround, no sleep, no retry, no fallback branch: a malformed bound fails loud.
• R4 — the product carries the behaviour and the prose follows it: the schema, the verb's own
  doc comment and the README describe the same knob, and the README's currency example names it.
• R5 — no legacy path survives: the knob is new, and no mode, state or field is renamed.
• R6 — the change is confined to this worktree (feat/pin-staleness off origin/main); no
  history is rewritten, no force, no bypass, and no other session's work is touched.
• R7 — the differential above; the coverage fails without the change.
• R8 — the live gate drives the verb against real git fixtures and a real charly binary, not
  a mock; the unit test's upstream is a local repository, exercised live.
• R9 — the binary the gate builds is the worktree-local build with this plugin compiled in.
• R10 — the change class (plugin library + schema) runs this repo's full bed on the committed
  tree, with zero warnings, and the live gate re-run on that same tree.

Change classification

Plugin library + schema (opt-in parameter, additive). The change class's gate is this repo's
full bed — go build, go test, go vet, gofmt, golangci-lint, charly box validate and
scripts/gate-task.sh — all run on the committed tree above, with zero warnings. The umbrella's
R10 rule that a plugin-library or schema change runs the full assembled bed is satisfied by the
repo's own assembled bed: the plugin is compiled into the binary the live gate builds and every
one of the five maintenance verbs is executed live in that same run.

Producer-first. This is the producer leg for opencharly/charly#1048: the verb ships here, and
the owner declares the bound and advances its twin in the consumer repo afterwards.

Filed issues

• dev-tools: the distro golangci-lint cannot decode the host Go's export data, so it can lint nothing — and the candy's own check (binary exists) cannot fail on it layer-dev-tools#3 — the local golangci-lint run fails on this host with
  export data version 5 is greater than maximum supported version 4, because the host's Go
  (1.27.3) is newer than the analysis side the pinned linter was built against. Measured to be
  pre-existing: the identical error reproduces on the pristine opencharly/plugin-task
  checkout with none of this change present, and the changed tree lints 0 issues under the
  toolchain candy/plugin-task/go.mod declares (go 1.26.4) — which is the toolchain CI selects
  via go-version-file. Evidence added to the existing issue rather than filed as a duplicate.

Closes #42

Agent: charly

Assisted-by: Claude Code minimax/minimax-m3.1-flash:cloud (fully tested and validated)

[github-actions]

Review — PASS

I reviewed all 6 changed files, the single commit, the PR body, and the (empty) comment thread. No maintainer sign-off is present (0 comments), so the change is evaluated on its own evidence.

Correctness vs. body claims

• File count / SHA / scope. The body says 6 changed files and head 01484d2e…; the provided diffs are exactly 6 files (README, currency_test.go, cue_types_gen.go, task.cue, verbs.go, gate-task.sh) and one commit. Scope is coherent: schema → generated params → verb logic → unit test → live gate → README.
• Schema is the single source. task.cue adds stale_after?: string @go(StaleAfter), and cue_types_gen.go adds the matching StaleAfter string \yaml:"stale_after,omitempty" json:"stale_after,omitempty"`` field with the same doc comment. Consistent and byte-plausible.
• Knob semantics match the prose.
  • Unset ⇒ off: the parse block only sets staleBoundSet when TrimSpace(in.StaleAfter) != ""; the render path only adds STALE text when len(stale) > 0. Default verdict is unchanged (Arm 1 asserts this).
  • Bound is on age of this repo's own last commit touching the path: lastAdvancedAt runs git log -1 --format=%ct -- <path>, not any distance calculation. Matches the body's central claim.
  • cur is never stale: staleEligible excludes it, and Arm 4 exercises the idle-upstream case.
  • blocked-by not eligible: excluded by staleEligible (and likely non-leaf). Matches body.
  • Malformed bound fails loud: time.ParseDuration error returns StatusFail with a message containing not a duration, and Arm 5 asserts exactly that.
• Message assertions line up with the implementation. Arm 2 requires 1 STALE pin(s) (neglected for more than 168h), src: behind, and this repo has not advanced it for 240h, (bound 168h), FAILED on the STALE pin(s) above — all four are produced by the exact format strings added in verbs.go (with durText(168h) == "168h", age.Round(time.Hour) == 240h, and state == "behind"). The 240h fixture stamp and the round-to-hour rendering are consistent.
• Differential is real. Arm 3 reuses the same fixture/pin/bound and only changes the advance date to ~1 minute, expecting PASS with 1 of 2 pin(s) NOT current still reported. This genuinely isolates churn from neglect, and the R7 claim (reverting verbs.go makes the bound accepted-and-ignored, so Arm 2 flips to PASS and the test fails) is logically sound.
• Live gate. scripts/gate-task.sh adds a stale_fixture and two runs (2020 stamp must FAIL, now stamp must PASS), checking the same substrings and the 1 of 1 pin(s) NOT current count. The fixture materializes the submodule checkout so the pin is judged behind rather than differs (no checkout), matching the body's stated reason.

Tests, security, cleanliness

• Coverage is meaningful and would fail without the feature (Arm 2 in the unit test; the old-stamp arm in the gate).
• Input handling: the pin path passed to git log is shellQuoted and preceded by --, so no option/path injection. No secrets or new dependencies.
• No dead code, no legacy path, no renamed modes/fields. The three new local closures (durText, staleEligible, lastAdvancedAt) are all referenced, so no unused-variable compile issue even when the bound is off.
• README documents the knob with an example consistent with the struct.

Comments

The comment thread is empty; nothing to disposition, and no sign-off to weigh.

Non-blocking observations (not gating)

• A negative/zero stale_after (e.g. "-1h", "0") parses successfully and would mark every non-current pin stale. Not validated, but it is an explicit operator error and not a correctness/security blocker.
• lastAdvancedAt treats any git log failure as "never advanced here" and flags the pin stale; a transient git error could produce a false stale. Acceptable given the fail-loud posture, but worth a future hardening note.

The change does what the body claims, ships coverage that fails without it, and introduces no security or scope problems.

Verdict: PASS

---

ollama-cloud/deepseek-v4.1-flash — action-review.

View action run

[aitrawog]

RESOLVED — both non-blocking observations in the review above are fixed in the successor PR, #44.

This PR is merged and tagged (v2026.296.2124), so its branch can no longer carry a fix. R1 is explicit that a finding raised on your own PR is fixed, or rebutted on the thread with evidence — never filed away. Neither is filed: both are fixed, in #44, with the differential proof pasted there.

Observation 1 — "A negative/zero stale_after (e.g. "-1h", "0") parses successfully and would mark every non-current pin stale."

Fixed in candy/plugin-task/verbs.go: the parse block now rejects a duration that is not POSITIVE, and the refusal names the reason. A bound of zero or less is not a bound — it is the permanently-red gate this knob exists to avoid, reached through the operator's own hand, so it is refused as the operator error it is. Covered by a unit arm over three values (0s, 0, -1h) and by a live arm in scripts/gate-task.sh that asserts both the refusal and the absence of any staleness judgement.

With the fix reverted, that arm goes red and shows what the knob did before:

FAIL: the refusal must name the reason; got: task currency-nonpositive: 1 step(s), 1 failed
      currency: 1 of 1 pin(s) NOT current [1 behind]; ... 1 STALE pin(s) (neglected for more than 0h): gap: behind, and this repo has not advanced it for 59710h (bound 0h) — advance it: mode=bump advances every pin to the ref its intent names

Observation 2 — "lastAdvancedAt treats any git log failure as 'never advanced here' and flags the pin stale; a transient git error could produce a false stale."

Fixed in the same file. The read now has three outcomes, and only one of them is a claim about the pin: a measured age; no-history (the path is in no commit of this repo's history, so it has never been advanced here — a FACT, and it IS neglected); and read-failed (the age could not be measured — the workflow being unable to JUDGE the pin, which is a structural-class failure naming the read error). The read-failure case is routed to the structural class precisely so that a transient git error can never manufacture a stale verdict.

The two are told apart by COUNTING the repo's commits, because git reports them identically: git log exits 128 on an unborn HEAD ("does not have any commits yet") and 128 on a broken object store ("fatal: bad object HEAD"), and git rev-parse --verify -q HEAD — the first discriminator reached for — exits 1 for BOTH an unborn HEAD and a broken HEAD ref, so it cannot separate them either. git rev-list --all --count can: zero commits means there is nothing here that could have been advanced (the fact), a count that cannot be produced means the history cannot be read (the failure).

With that split reverted, the arm goes red and shows the false stale:

--- FAIL: TestGitSubmodules_CurrencyStalenessBoundsNeglect (0.19s)
    currency_test.go:552: an unreadable history must never be reported as neglect; got:
        currency: 1 of 2 pin(s) NOT current [1 behind, 1 cur]; ... 1 STALE pin(s) (neglected for more than 168h): src: behind, and this repo's own history records no advance of it — it has never been advanced here

The full bodies, the differential runs and the live gate are in #44.

Issue #42 stays open until that successor lands, and is closed with its record then.

Agent: charly

Assisted-by: Claude Code minimax/minimax-m3.1-flash:cloud (fully tested and validated)