…URLs (lychee)

Same MD025 issue PR #300 hit: YAML frontmatter `title:` field + body
H1 both register as top-level heading. Recent AgDRs (0034, 0035, 0037,
and now 0038 after the same revert) all skip frontmatter entirely.
Reverting the frontmatter on AgDR-0039 to match the convention.

The lychee timeouts on the two Martin Fowler URLs are the same pattern
the medium.com exclusion handles — Fowler's article server applies
aggressive per-IP rate limiting and lychee's burst trips it; the links
work in browsers. Adding `martinfowler.com/articles/exploring-gen-ai/.*`
to .lycheeignore with a comment naming AgDR-0037 and AgDR-0039 as the
citations.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…s (shape + 5 retrofits) (#301)

* feat(#295): standardise self-correction guidance — shape + 5 hook retrofits

ApexYard's blocking hooks were uneven in error-message shape — some
shipped a gold-standard "BLOCKED → context → numbered next-action
list" (e.g. require-active-ticket.sh, validate-commit-format.sh)
while others shipped a single-line "BLOCKED: <reason>" with no
recovery path (e.g. check-secrets.sh, block-git-add-all.sh). Per
Böckeler's harness-engineering framing, structured next-action
guidance in sensor errors is the highest-leverage move for agent
self-correction — "a good kind of prompt injection."

This PR ships the canonical shape (AgDR-0039) + retrofits 5
high-impact underweight hooks:

- check-secrets.sh: full To-unblock block with env-var migration
  steps + false-positive handling
- block-git-add-all.sh: explicit "stage by name" guidance with
  directory-form example
- block-main-push.sh: two cases (push, commit) each get a To-unblock
  block; commit case includes recovery from an accidental
  protected-branch commit
- validate-branch-name.sh: heredoc shape with rename command + fresh
  branch alternative + accepted-shape examples
- require-active-ticket.sh: phrasing tweak from "To proceed:" to
  "To unblock:" — canonical phrase from AgDR-0039

The canonical phrase is "To unblock:" (decision recorded in AgDR-0039).
Prior hooks variously used "To proceed:" / "To self-correct:" /
"To unblock:"; standardising on the third for grep-ability and
operator habit-formation.

The remaining ~6 underweight hooks (warn-stale-review-markers and a
handful of validate/check hooks with sparser messages) are scope for
a follow-up PR — landing this first to lock in the shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#295): address Rex's 5 findings on the canonical-example PR

Rex flagged three real bugs in the very PR meant to demonstrate the
new standard — exactly the right scrutiny. Fixing all in one commit:

1. check-secrets.sh: "intentional / ally" word-break across lines
   in the help text. Reflowed to keep "intentionally" intact.

2. block-main-push.sh push case: the "override" guidance pointed
   in the WRONG direction — `.git.protected_branches[]` REPLACES the
   default list. Adding a branch makes it MORE protected, not less.
   Rewrote as "Customise" with explicit direction for both REMOVE and
   ADD intents — get the direction right is now load-bearing.

3. validate-branch-name.sh: hardcoded `git checkout dev` as the
   integration-branch example. Per CLAUDE.md § "Branch model — framework
   only", managed projects are trunk-based on 'main'; only the apexyard
   framework itself uses 'dev'. Changed to `git checkout main` with a
   parenthetical noting the framework's own convention.

4. block-main-push.sh commit case: the accidental-commit-recovery
   section had a SECOND numbered list, diluting AgDR-0039's contract
   that reserves the numbered shape for the single `To unblock:` block.
   Reflowed as prose + a code block, no numbering.

5. AgDR-0039: replaced `#XXX` placeholder with `#301` so the AgDR is
   self-contained for archaeology.

The shape is now consistent across all 5 retrofits. Re-Rex on this
HEAD.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#295): CI green — drop AgDR-0039 frontmatter (MD025) + ignore MF URLs (lychee)

Same MD025 issue PR #300 hit: YAML frontmatter `title:` field + body
H1 both register as top-level heading. Recent AgDRs (0034, 0035, 0037,
and now 0038 after the same revert) all skip frontmatter entirely.
Reverting the frontmatter on AgDR-0039 to match the convention.

The lychee timeouts on the two Martin Fowler URLs are the same pattern
the medium.com exclusion handles — Fowler's article server applies
aggressive per-IP rate limiting and lychee's burst trips it; the links
work in browsers. Adding `martinfowler.com/articles/exploring-gen-ai/.*`
to .lycheeignore with a comment naming AgDR-0037 and AgDR-0039 as the
citations.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…s (shape + 5 retrofits) (#301)

* feat(#295): standardise self-correction guidance — shape + 5 hook retrofits

ApexYard's blocking hooks were uneven in error-message shape — some
shipped a gold-standard "BLOCKED → context → numbered next-action
list" (e.g. require-active-ticket.sh, validate-commit-format.sh)
while others shipped a single-line "BLOCKED: <reason>" with no
recovery path (e.g. check-secrets.sh, block-git-add-all.sh). Per industry-standard prior art on harness engineering for coding agents, structured next-action
guidance in sensor errors is the highest-leverage move for agent
self-correction — "a good kind of prompt injection."

This PR ships the canonical shape (AgDR-0039) + retrofits 5
high-impact underweight hooks:

- check-secrets.sh: full To-unblock block with env-var migration
 steps + false-positive handling
- block-git-add-all.sh: explicit "stage by name" guidance with
 directory-form example
- block-main-push.sh: two cases (push, commit) each get a To-unblock
 block; commit case includes recovery from an accidental
 protected-branch commit
- validate-branch-name.sh: heredoc shape with rename command + fresh
 branch alternative + accepted-shape examples
- require-active-ticket.sh: phrasing tweak from "To proceed:" to
 "To unblock:" — canonical phrase from AgDR-0039

The canonical phrase is "To unblock:" (decision recorded in AgDR-0039).
Prior hooks variously used "To proceed:" / "To self-correct:" /
"To unblock:"; standardising on the third for grep-ability and
operator habit-formation.

The remaining ~6 underweight hooks (warn-stale-review-markers and a
handful of validate/check hooks with sparser messages) are scope for
a follow-up PR — landing this first to lock in the shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#295): address Rex's 5 findings on the canonical-example PR

Rex flagged three real bugs in the very PR meant to demonstrate the
new standard — exactly the right scrutiny. Fixing all in one commit:

1. check-secrets.sh: "intentional / ally" word-break across lines
 in the help text. Reflowed to keep "intentionally" intact.

2. block-main-push.sh push case: the "override" guidance pointed
 in the WRONG direction — `.git.protected_branches[]` REPLACES the
 default list. Adding a branch makes it MORE protected, not less.
 Rewrote as "Customise" with explicit direction for both REMOVE and
 ADD intents — get the direction right is now load-bearing.

3. validate-branch-name.sh: hardcoded `git checkout dev` as the
 integration-branch example. Per CLAUDE.md § "Branch model — framework
 only", managed projects are trunk-based on 'main'; only the apexyard
 framework itself uses 'dev'. Changed to `git checkout main` with a
 parenthetical noting the framework's own convention.

4. block-main-push.sh commit case: the accidental-commit-recovery
 section had a SECOND numbered list, diluting AgDR-0039's contract
 that reserves the numbered shape for the single `To unblock:` block.
 Reflowed as prose + a code block, no numbering.

5. AgDR-0039: replaced `#XXX` placeholder with `#301` so the AgDR is
 self-contained for archaeology.

The shape is now consistent across all 5 retrofits. Re-Rex on this
HEAD.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#295): CI green — drop AgDR-0039 frontmatter (MD025) + ignore external URLs (lychee)

Same MD025 issue PR #300 hit: YAML frontmatter `title:` field + body
H1 both register as top-level heading. Recent AgDRs (0034, 0035, 0037,
and now 0038 after the same revert) all skip frontmatter entirely.
Reverting the frontmatter on AgDR-0039 to match the convention.

The lychee timeouts on the two URLs are the same pattern
the medium.com exclusion handles — 's article server applies
aggressive per-IP rate limiting and lychee's burst trips it; the links
work in browsers. Adding `[external-blog-pattern]`
to .lycheeignore with a comment naming AgDR-0037 and AgDR-0039 as the
citations.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(#280): SessionStart hook warns when jq is missing

Many framework hooks call jq to read .claude/project-config.json
overrides; without jq those reads silently degrade to defaults and
the adopter's .ui_paths / .tracker.* / etc. have zero effect. The
new check-jq-installed.sh hook surfaces the gap as a one-line
SessionStart banner whenever a project-config file is present but
jq is off PATH. Wired sibling to check-upstream-drift.sh.

Non-blocking advisory: exit 0 always, banner only when (jq missing
AND project-config present AND inside an ops fork). Silent when
any of those isn't true. Mirrors the established graceful-degrade
pattern (AgDR-0005, AgDR-0034).

Refs #280

* feat(#280): /setup refuses if jq is missing

Adds a Step −1 pre-flight check to the /setup skill that runs
before any state-mutating step. If jq is absent, the skill prints
clear install instructions and exits 1 — explicit refusal beats
the silently-degraded fallback that adopters were hitting on
fresh machines.

Cross-references the new check-jq-installed.sh SessionStart
advisory for the case where /setup never re-runs but jq later
disappears.

Refs #280

* docs(#280): list jq in getting-started prerequisites

Adds jq to the Prerequisites bullet list with install instructions
per platform and a pointer to AgDR-0038. Fresh adopters now see
the dependency declared at the same level as gh CLI, before they
hit the SessionStart banner or the /setup pre-flight refusal.

Refs #280

* docs(#280): AgDR-0038 — jq as a hard dependency

Records the Option A vs Option B decision from #280: declare jq
as a hard dep with explicit failure paths (/setup pre-flight,
SessionStart advisory, prerequisites doc) rather than build a
Python fallback inside _lib-read-config.sh. Captures the
justification (silent degradation beats clean failure was the
adopter complaint; A is simpler; B shifts the burden, not removes
it; jq is broadly available on target machines) and the negative
consequences (locked-down corporate environments without install
rights are blocked until they whitelist jq).

Sibling to AgDR-0005 (upstream drift) and AgDR-0034 (PDF
converter dispatch) — same loud-failure-at-use-time shape.

Refs #280

* test(#280): smoke tests for check-jq-installed.sh

Covers the five behavioural cases the hook needs to honour:
  1. jq present + project-config present → silent
  2. jq missing + project-config.json → warning
  3. jq missing + project-config.defaults.json → warning
  4. jq missing + no project-config → silent
  5. jq missing + outside any ops fork → silent

Uses a two-stage jq-absence simulator (PATH-only mask, falling
through to a `command` function override sourced into a child
bash) so the tests run cleanly on macOS (jq in /opt/homebrew/bin)
and Linux (jq in /usr/bin) alike.

Refs #280

* docs(#280): add YAML frontmatter to AgDR-0038 (Rex review nit)

Rex review on PR #300 flagged that AgDR-0038 lacked the YAML
frontmatter block every other AgDR has (per templates/agdr.md).
Without it, /agdr browse reads category as 'other' instead of
'architecture'. One-line prepend, no content changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* revert(#280): drop the frontmatter from AgDR-0038 (CI MD025)

Markdownlint MD025 fired because the YAML frontmatter `title:` AND the
body H1 (`# AgDR-0038 —`) both register as top-level headings. Recent
AgDRs (0034, 0035, 0037) skip frontmatter entirely and just use the
body H1 — so Rex's "missing frontmatter" nit on the prior re-review was
actually wrong about the convention.

Reverting the frontmatter addition. Single H1 = `# AgDR-0038 — jq as a
hard dependency`. MD025 passes.

The /agdr browse `category` indexing concern Rex flagged is real but
orthogonal — it should be fixed at the template / browse-resolver
layer, not by adopting an inconsistent per-AgDR override. Filing
separately if it bites.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…s (shape + 5 retrofits) (#301)

* feat(#295): standardise self-correction guidance — shape + 5 hook retrofits

ApexYard's blocking hooks were uneven in error-message shape — some
shipped a gold-standard "BLOCKED → context → numbered next-action
list" (e.g. require-active-ticket.sh, validate-commit-format.sh)
while others shipped a single-line "BLOCKED: <reason>" with no
recovery path (e.g. check-secrets.sh, block-git-add-all.sh). Per industry-standard prior art on harness engineering for coding agents, structured next-action
guidance in sensor errors is the highest-leverage move for agent
self-correction — "a good kind of prompt injection."

This PR ships the canonical shape (AgDR-0039) + retrofits 5
high-impact underweight hooks:

- check-secrets.sh: full To-unblock block with env-var migration
 steps + false-positive handling
- block-git-add-all.sh: explicit "stage by name" guidance with
 directory-form example
- block-main-push.sh: two cases (push, commit) each get a To-unblock
 block; commit case includes recovery from an accidental
 protected-branch commit
- validate-branch-name.sh: heredoc shape with rename command + fresh
 branch alternative + accepted-shape examples
- require-active-ticket.sh: phrasing tweak from "To proceed:" to
 "To unblock:" — canonical phrase from AgDR-0039

The canonical phrase is "To unblock:" (decision recorded in AgDR-0039).
Prior hooks variously used "To proceed:" / "To self-correct:" /
"To unblock:"; standardising on the third for grep-ability and
operator habit-formation.

The remaining ~6 underweight hooks (warn-stale-review-markers and a
handful of validate/check hooks with sparser messages) are scope for
a follow-up PR — landing this first to lock in the shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#295): address Rex's 5 findings on the canonical-example PR

Rex flagged three real bugs in the very PR meant to demonstrate the
new standard — exactly the right scrutiny. Fixing all in one commit:

1. check-secrets.sh: "intentional / ally" word-break across lines
 in the help text. Reflowed to keep "intentionally" intact.

2. block-main-push.sh push case: the "override" guidance pointed
 in the WRONG direction — `.git.protected_branches[]` REPLACES the
 default list. Adding a branch makes it MORE protected, not less.
 Rewrote as "Customise" with explicit direction for both REMOVE and
 ADD intents — get the direction right is now load-bearing.

3. validate-branch-name.sh: hardcoded `git checkout dev` as the
 integration-branch example. Per CLAUDE.md § "Branch model — framework
 only", managed projects are trunk-based on 'main'; only the apexyard
 framework itself uses 'dev'. Changed to `git checkout main` with a
 parenthetical noting the framework's own convention.

4. block-main-push.sh commit case: the accidental-commit-recovery
 section had a SECOND numbered list, diluting AgDR-0039's contract
 that reserves the numbered shape for the single `To unblock:` block.
 Reflowed as prose + a code block, no numbering.

5. AgDR-0039: replaced `#XXX` placeholder with `#301` so the AgDR is
 self-contained for archaeology.

The shape is now consistent across all 5 retrofits. Re-Rex on this
HEAD.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#295): CI green — drop AgDR-0039 frontmatter (MD025) + ignore external URLs (lychee)

Same MD025 issue PR #300 hit: YAML frontmatter `title:` field + body
H1 both register as top-level heading. Recent AgDRs (0034, 0035, 0037,
and now 0038 after the same revert) all skip frontmatter entirely.
Reverting the frontmatter on AgDR-0039 to match the convention.

The lychee timeouts on the two URLs are the same pattern
the medium.com exclusion handles — 's article server applies
aggressive per-IP rate limiting and lychee's burst trips it; the links
work in browsers. Adding `[external-blog-pattern]`
to .lycheeignore with a comment naming AgDR-0037 and AgDR-0039 as the
citations.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>