Skip to content

Commit 6fcc7dd

Browse files
committed
docs(staleness): surface the pin-freshness feature + park the cross-repo half
Make the workflow-pin staleness work discoverable from the human and machine front doors, and capture the deferred cross-repo automation in-repo so it is not lost at session close: - README.adoc (human) + 0-AI-MANIFEST.a2ml (machine): extend the drift/staleness row to point at ADR-003, check-workflow-staleness.sh, and propagate-workflow-pins.sh. - docs/FUTURE-WORK.adoc: park item #16 — the cross-repo half (activate hypatia sha_bump_propagation; wire gitbot-fleet to open draft bump PRs; optional standards-side scheduled audit). Out of scope for a standards PR (lives in other repos) and gated on a dispatch PAT + owner sign-off. Registry + topology stay in sync (edited files are root/docs, not spec homes). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BKyi8Bht8xdXyajpkaTdYP
1 parent f01ace5 commit 6fcc7dd

3 files changed

Lines changed: 30 additions & 2 deletions

File tree

0-AI-MANIFEST.a2ml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ content-addressed `source_hash`. Prose explanation: `REGISTRY.adoc`.
2626
| Protocols | `*-protocol/` (registry stream `protocol`) |
2727
| Readiness grades | `adoption-readiness-grades/`, `foundations-readiness-grades/`, `component-readiness-grades/`, `toolchain-readiness-grades/` |
2828
| Enforcement / CI | `.github/workflows/`, `hooks/` |
29-
| Drift / staleness automation | `REGISTRY.adoc`, `hypatia-rules/` (HYP-S006) |
29+
| Drift / staleness automation | `REGISTRY.adoc`, `hypatia-rules/` (HYP-S006); reusable-pin freshness: `docs/decisions/ADR-003-workflow-pin-staleness-window.adoc`, `scripts/check-workflow-staleness.sh`, `scripts/propagate-workflow-pins.sh` |
3030
| Derived architecture map | `TOPOLOGY.md` (generated — do not edit) |
3131
| Current project state | `.machine_readable/6a2/STATE.a2ml` |
3232

README.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Every other "what is this repo" doc is now a thin pointer back to these two
5454
| link:.github/workflows/[.github/workflows/] + link:hooks/[hooks/] + <<Enforcement>>
5555

5656
| The **drift / staleness automation** — how this repo keeps itself honest
57-
| link:REGISTRY.adoc[REGISTRY.adoc] + link:hypatia-rules/[hypatia-rules/] (HYP-S006)
57+
| link:REGISTRY.adoc[REGISTRY.adoc] + link:hypatia-rules/[hypatia-rules/] (HYP-S006); reusable-workflow pin freshness: link:docs/decisions/ADR-003-workflow-pin-staleness-window.adoc[ADR-003] (`scripts/check-workflow-staleness.sh` gate + `scripts/propagate-workflow-pins.sh` deliberate-bump)
5858

5959
| The **architecture map** (derived, never frozen)
6060
| link:TOPOLOGY.md[TOPOLOGY.md] (generated from STATE + registry)

docs/FUTURE-WORK.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,34 @@ grades ingested. Five upstream dependencies.
4848
**When to revive:** Once the full 5-layer innervation stack is running
4949
end-to-end on at least 10 pilot repos.
5050

51+
=== 16. Cross-repo reusable-workflow pin propagation (auto-bump)
52+
53+
**What:** The cross-repo half of the workflow-pin staleness story. The
54+
standards-side is done (ADR-003: the gate tolerates a recency window, and
55+
`scripts/propagate-workflow-pins.sh` performs an audit-first bump). What
56+
remains is the *fleet* wiring so a deliberate bump fans out automatically:
57+
58+
* Activate the Hypatia rule `lib/rules/sha_bump_propagation.ex`
59+
(hyperpolymath/hypatia) so a "consumer pin is behind standards HEAD"
60+
finding is routed (`:review`) rather than inert.
61+
* Wire gitbot-fleet to run `propagate-workflow-pins.sh --fix` in the flagged
62+
consumer and open a DRAFT bump PR (mirrors the `.git-private-farm`
63+
dispatch pattern in `instant-sync.yml`; gated on a PAT, graceful-skip
64+
without it).
65+
* Optional standards-side scheduled workflow (`propagate-workflow-pins.yml`)
66+
that, on a cadence, audits the fleet and dispatches the above — sketch
67+
only; do not ship the cross-repo dispatch without the PAT + owner sign-off
68+
(estate "no unattended mutations" guardrail).
69+
70+
**Why parked:** The actionable pieces live in *other* repos (hypatia,
71+
gitbot-fleet) — out of scope for a standards PR. No technical precursor; it
72+
needs cross-repo PRs + a dispatch PAT, not a VeriSimDB-style dependency.
73+
74+
**When to revive:** Whenever the deliberate-bump cadence is wanted. The gate
75+
no longer forces it (consumers are green within the window), so this is a
76+
convenience/freshness improvement, not a treadmill fix. Track via issues in
77+
hypatia + gitbot-fleet referencing ADR-003.
78+
5179
== Out-of-scope (not parked — closed)
5280

5381
- Per-repo dashboards (PanLL handles this organically via manifests)

0 commit comments

Comments
 (0)