Merge feature/gitflow-aiguillage-standalone into develop

This commit is contained in:
Bastien Chanot 2026-07-01 14:28:10 +02:00
commit 0a2e832a66
12 changed files with 107 additions and 28 deletions

View File

@ -66,6 +66,7 @@ rules:
| BDR-042 | 2026-06-30 | /release-candidate = thin orchestrator over gitflow release; the tag lives in the skill, not the lib | accepted |
| BDR-043 | 2026-06-30 | BDR-015 trigger cleared — 5 ex-broken gstack symlinks repaired → darwin re-baseline back in scope (unblocked, NOT run) | accepted |
| BDR-044 | 2026-06-30 | auto-skill-dispatch won't-build — under-routing fear inverted to over-routing by cartography, then measured: model discriminates (clear→route, ambiguous→ask, trivial→abstain) | accepted · won't-build |
| BDR-045 | 2026-07-01 | Standalone memory/doc skills branch to chore/* via aiguillage (hook exemption kept) | accepted |
---
@ -680,3 +681,15 @@ rules:
- Add an over-routing bound (clear→route / ambiguous→ask / trivial→abstain) at L2 → measurement shows the model ALREADY does this; codifying it risks perturbing it, zero upside.
- Keyword hook on intent verbs → too noisy — the design-hook mis-fired on "design" in "auto-skill-dispatch" 3× this session; intent verbs (corrige/crée) are everywhere.
- **Reference**: cartography L0L4 + discernment-RED (user-run, fresh sessions). Subagent under-routing RED RETIRED as non-discriminating ([[LRN-083]]). [[LRN-080]] (measure-first), [[LRN-049]] (bound noise). TODO "auto-skill-dispatch" → won't-build.
## BDR-045 — Standalone memory/doc skills branch to `chore/*` via the aiguillage (hook exemption kept)
- **Date**: 2026-07-01
- **Status**: accepted
- **Decision**: Standalone memory/doc skills (`/capitalize` `/close` `/prune-memory` `/reconcile`) run the gitflow aiguillage BEFORE writing: on a protected base they `gitflow start chore <name>` off develop → commit lands on `chore/*`, not direct on main/develop. New `chore` type in `lib/gitflow.sh` (`base_for`→develop, `branch_type`, `finish`→develop like feature/bugfix); hook UNCHANGED (`chore/*` non-protected; the `.claude/**`-on-main exemption KEPT — T3 still green). `gitflow-aiguillage.md` broadened (caller→type map); 3 skills wired (`capitalize` covers `/close` via alias, `prune-memory`, `reconcile`); tests +T1 chore predicates +T6b finish chore→develop +T10 coherence chore/m → 64/64. Reused the EXISTING aiguillage include, not a new mechanism. Commit `e8807a7`.
- **Why**: the `.claude/**` exemption is scoped to the SIDE-CAR ([[BDR-034]]: memory following a code branch). When memory IS the work (standalone reconcile/prune/capitalize) there is no branch to follow → it fell back to `main`. A multi-repo raccord committed 5 `chore(memory)` direct on `main` and nothing flagged it — the exemption worked as designed, masking the divergence with the "all via branch" rule ([[LRN-084]]). The aiguillage closes the SKILL path without taxing the side-car. The hook can NEVER enforce "from develop" (only "not on a protected base") → that half lives ONLY in `gitflow_start`.
- **Alternatives rejected**:
- (A) remove the `.claude/**` exemption — breaks standalone `/capitalize`+`/close` on main/develop (commit in place, no branch of their own — `memory-commit.sh` has no protected-base guard) AND every side-car commit; over-reaches the leak.
- (C) codify exemption + human habit — enforces NOTHING mechanically; goal was automatic.
- (D) narrow the exemption by size/scope in the hook — fuzzy, false positives.
- **Honest residual**: a MANUAL `git commit` of `.claude/**` on `main` still passes — B covers the skill path only. Non-blocking hook WARN on manual `.claude/**`-on-main = DEFERRED. See [[BDR-034]], [[BDR-039]], [[LRN-084]].

View File

@ -287,3 +287,6 @@ rules:
- Subagent RED (6 reps, toy tasks) → 0/6 routed → RETIRED as non-discriminating (SUBAGENT-STOP + delegated framing = floor artifact, not signal); did NOT report as a number → [[LRN-083]].
- Discernment-RED in REAL fresh sessions (user-run, 8 prompts / 3 classes): CLEAR→route ✓, AMBIGUOUS→ask (refuses to guess, investigates for a useful Q) ✓, TRIVIAL→abstain ✓. Over-routing risk does NOT materialize — model balances L1 vs Workflow rules.
- Verdict: WON'T-BUILD ([[BDR-044]]) — 3rd measured moot of the session (--help, darwin re-baseline, auto-skill-dispatch). LRN-083 capitalized; [[LRN-080]] corroborated (3-in-a-row → measure-first sweep heuristic). TODO auto-skill-dispatch → won't-build. ALL actionables soldés.
## 2026-07-01
- gitflow aiguillage-standalone (BDR-045): chore type + 4 standalone memory/doc skills branch off develop before writing; hook exemption kept. 64/64 green (e8807a7). Then repaired 5 direct-on-main `chore(memory)` → chore/reconcile-memory branches (LRN-084, LRN-034 corrob).

View File

@ -103,6 +103,7 @@ rules:
| LRN-081 | 2026-06-30 | Claude commit trailers (Co-Authored-By + Claude-Session) only on Claude-COMPOSED content; a commit merely STAGING user-authored text gets none — staging ≠ authorship | committing on the user's behalf; memory-commit.sh appends trailers by default |
| LRN-082 | 2026-06-30 | Trigger-cleared on a multi-motif exclusion lifts only the named motif — re-check the others before acting | any "exclusion lifted / precondition cleared" — verify ALL grounds, not just the named one |
| LRN-083 | 2026-06-30 | subagents are an INVALID instrument for measuring main-loop spontaneous routing — SUBAGENT-STOP + delegated framing pin them to the no-route floor | any RED of whether the MAIN loop self-invokes; use fresh main-loop sessions, observe via the human |
| LRN-084 | 2026-07-01 | protection hook enforces PROD not the full branch-flow; exemption masked the rule-vs-guard divergence | a guard exempts a class / checks one predicate — verify it encodes full intent |
---
@ -544,6 +545,7 @@ rules:
- **Pattern**: narrated/remembered state from ANY source (user OR assistant) is not ground truth. Approval of a diff ≠ its application.
- **Future application**: anyone asserts "X is done" → verify (git log, file content, grep) before building on it; ESPECIALLY when it contradicts your own earlier statement, or after a context/window break. Internal contradiction → stop, re-check git, never reconcile by accepting the newer claim silently.
- **Reference**: P3 reprise, commit 493b6b9. Linked to [[LRN-032]] (verify before applying a rule), [[LRN-035]] (check the artifact, not the claim/count).
- **corroboration 2026-07-01**: multi-repo raccord (6 repos) — mapped each repo's REAL git/fs state (read-only cartography) before EVERY write/destructive op, gated per-gap, re-verified each subagent oracle in the main loop. Declared TODO/registry/checkbox drift confirmed repeatedly; the discipline KILLED false simplifications: a blind `master→main` CHANGELOG swap (reflog showed master renamed AWAY, not a live branch), "just remove the `.claude/**` exemption" (would have broken standalone `/capitalize`, [[LRN-084]]), a config supersession grep that failed on a line-wrap (supersession was real). Narrated/declared state ≠ ground truth, at multi-repo scale.
---
@ -906,3 +908,10 @@ rules:
- **why it matters**: a 0/N subagent RED reads as "under-triggers → build the chantier" but is the [[LRN-028]] trap — the instrument can't tell strong prose from weak. Concluding from it = a pass/fail for the WRONG reason ([[LRN-074]]/[[LRN-077]]).
- **context**: 2026-06-30 auto-skill-dispatch RED. 6 subagents on toy implicit-intent tasks → 0/6 routed → RETIRED as non-discriminating, NOT reported as a number. Reframed; measured instead in REAL fresh main-loop sessions.
- **future application**: measure main-loop spontaneous routing/discernment in FRESH main-loop sessions (full L0L4, no SUBAGENT-STOP, real user-turn). Observable instrument = the HUMAN typing the prompts + watching live — cron/schedule-spawned fresh sessions are the right CONDITION but UNOBSERVABLE to the orchestrator (they notify the owner, not the dispatcher), so they can't be the measurement vehicle. Never substitute a subagent for a fresh session in a routing RED. See [[LRN-028]], [[LRN-075]], [[LRN-080]].
## LRN-084 — A protection hook enforces PROD safety, not the full branch-flow — the exemption masked the rule-vs-guard divergence
- **Date**: 2026-07-01
- **pattern**: the gitflow pre-commit hook is a PROTECTION guard (block code on main/develop), NOT a flow enforcer. It exempts `.claude/**` and can only test "on a protected base" — it can NEVER verify "branched FROM develop" (no base knowledge). So "every change via a branch from develop" is only HALF-encoded by the hook; the base half lives solely upstream in `gitflow_start`. The exemption is scoped to the SIDE-CAR ([[BDR-034]]); it has no branch to follow when memory IS the work → standalone memory fell back to `main`.
- **why it matters**: a multi-repo raccord committed 5 `chore(memory)` direct on `main` and NOTHING flagged it — nothing was violated, the exemption worked as designed. The divergence was guard (declares PROD protection) vs intended rule (all via branch); the exemption MASKED it, the raccord revealed it by violating the unencoded half. A guard encoding only PART of the intent reads as full enforcement — a false-green.
- **future application**: when a guard exempts a class or checks one predicate, ask what it does NOT encode and whether a human leans on it for MORE than it enforces. Enforce the unencoded half where it actually lives (the aiguillage at skill start, [[BDR-045]]), do not push it into a guard that structurally can't hold it. Verify the guard's real scope against the rule's full scope before trusting "it would have caught it." See [[BDR-034]], [[BDR-045]], [[LRN-034]].

View File

@ -168,23 +168,27 @@ Every git action follows gitflow — inside a skill AND for ad-hoc commits made
outside one on direct request. The model is universal across all projects.
### Branch model
`main` (prod) · `develop` (integration, off main) · `feature/*` + `bugfix/*`
(off develop → develop) · `release/*` (off develop → main + back-merge develop)
· `hotfix/*` (off main → main + develop [+ any open release/*]). `master`→`main`
everywhere.
`main` (prod) · `develop` (integration, off main) · `feature/*` + `bugfix/*` +
`chore/*` (off develop → develop; `chore/*` = memory/doc maintenance, e.g.
standalone `/capitalize` `/prune-memory` `/reconcile`) · `release/*` (off develop →
main + back-merge develop) · `hotfix/*` (off main → main + develop [+ any open
release/*]). `master`→`main` everywhere.
### Rules for every git action
- **Never commit code directly on `main` or `develop`.** Branch first from the
correct base, named `<type>/<name>`. (`.claude/**` memory/config commits are
exempt — they follow the work, not the code's gitflow.)
hook-exempt — they follow the work; but *standalone* memory/doc skills branch to
`chore/*` via the aiguillage rather than lean on that exemption.)
- **Branch + merge via the lib, never by hand** — the directed-merge + hotfix
fan-out logic lives there once:
`bash ~/.claude/lib/gitflow.sh start <type> <name>` · `… finish`.
- **`gitflow finish` (merge) only on an explicit human signal** ("merge it",
"feature OK") — never because tests pass, a plan step says "merge", or a verb
("ship") implied it.
- **Assistance flows** (`/feat` `/bugfix` `/hotfix`) auto-branch on a protected
base (the aiguillage); on a working branch they commit in place, never finish.
- **Assistance flows** (`/feat` `/bugfix` `/hotfix`) AND **standalone memory/doc
skills** (`/capitalize` `/close` `/prune-memory` `/reconcile`, type `chore`)
auto-branch on a protected base (the aiguillage); on a working branch they commit
in place, never finish.
- **New/onboarded projects** get the model + the versioned pre-commit hook via
`gitflow init` (init-project STEP 5f, onboard STEP 2.6).

View File

@ -1,26 +1,41 @@
# Gitflow aiguillage — assistance flows branch on a protected base
# Gitflow aiguillage — branch on a protected base before writing
Assistance flows (`/feat`, `/bugfix`, `/hotfix`) commit IN PLACE on a working
branch — the frequent case, behavior unchanged. But they must NEVER commit code
on a protected base (`main`/`develop`). Run this check **before editing any
file**. The caller passes its TYPE: feat→`feature`, bugfix→`bugfix`,
hotfix→`hotfix`.
Flows that WRITE — code, OR standalone memory/doc work — must NEVER commit on a
protected base (`main`/`develop`). Run this check **before editing any file**.
```bash
bash "$HOME/.claude/lib/gitflow.sh" protected-base && echo PROTECTED || echo WORKING
```
- **WORKING** (`feature/*`, `bugfix/*`, `hotfix/*`, or any non-protected branch)
→ proceed; you commit in place on this branch. Nothing changes.
- **WORKING** (`feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`, or any non-protected
branch) → proceed; you commit in place on this branch. Nothing changes.
- **PROTECTED** (`main`/`develop`) → branch first, do NOT commit here:
```bash
bash "$HOME/.claude/lib/gitflow.sh" start <YOUR-TYPE> <short-kebab-name>
```
`<short-kebab-name>` derived from the request. Then do the work on the new branch.
**Never run `gitflow finish`** — assistance flows commit, they do not merge.
Integration is a separate, human-gated step (the `gitflow` skill).
The caller passes its TYPE:
Note: `hotfix` branches off **main** (prod) even when invoked from `develop`
that is the gitflow definition of a hotfix. For a dev-scoped small fix, use
`/bugfix` (branches off develop).
| Caller | TYPE | Base |
|--------|------|------|
| `/feat` | `feature` | develop |
| `/bugfix` | `bugfix` | develop |
| `/hotfix` | `hotfix` | main |
| `/capitalize` · `/close` · `/prune-memory` · `/reconcile` | `chore` | develop |
The `chore` row = **standalone memory/doc work**: the registry / TODO / doc
reconciliation & curation skills, run OUTSIDE an assistance flow. Inside `/feat`
`/bugfix` `/hotfix` `/ship-feature` a working branch already exists (this check
returns WORKING) and the memory commit rides it. The aiguillage only fires when
such a skill is invoked directly on `main`/`develop` — i.e. memory IS the work,
with no code branch to follow. That is the leak it closes: the `.claude/**` hook
exemption still lets a *manual* memory commit through on a protected base, but a
skill-driven one now branches to `chore/*` first.
**Never run `gitflow finish`** — these flows commit, they do not merge. Integration
is a separate, human-gated step (the `gitflow` skill).
Note: `hotfix` branches off **main** (prod) even when invoked from `develop` — that
is the gitflow definition of a hotfix. For a dev-scoped small fix, use `/bugfix`
(branches off develop).

View File

@ -32,6 +32,9 @@ chk "protected develop" 'gitflow_protected_base develop'
chk "not protected feat" '! gitflow_protected_base feature/x'
chk "base feature=develop" '[ "$(gitflow_base_for feature)" = develop ]'
chk "base hotfix=main" '[ "$(gitflow_base_for hotfix)" = main ]'
chk "type chore" '[ "$(gitflow_branch_type chore/x)" = chore ]'
chk "base chore=develop" '[ "$(gitflow_base_for chore)" = develop ]'
chk "not protected chore" '! gitflow_protected_base chore/x'
echo "T2 — init fresh (BLK-010 root commit)"
newrepo fresh; echo scaffold > README.md; hookon
@ -92,6 +95,16 @@ chk "merged into develop" 'git log develop --oneline | grep -q "Merge feature/f1
chk "main untouched" "[ \"\$(git rev-parse main)\" = \"$main_before\" ]"
chk "branch deleted" '! git rev-parse --verify -q refs/heads/feature/f1 >/dev/null'
echo "T6b — finish chore → develop only (standalone memory/doc maintenance)"
newrepo finchore; echo a>a; hookon; gitflow_init >/dev/null 2>&1
gitflow_start chore c1 >/dev/null 2>&1
mkdir -p .claude/memory; echo m>.claude/memory/x.md; git add -A; git commit -q -m "chore(memory)"
main_before="$(git rev-parse main)"
gitflow_finish >/dev/null 2>&1
chk "chore merged into develop" 'git log develop --oneline | grep -q "Merge chore/c1 into develop"'
chk "chore main untouched" "[ \"\$(git rev-parse main)\" = \"$main_before\" ]"
chk "chore branch deleted" '! git rev-parse --verify -q refs/heads/chore/c1 >/dev/null'
echo "T7 — finish hotfix → main + develop fan-out"
newrepo finhot; echo a>a; hookon; gitflow_init >/dev/null 2>&1
gitflow_start hotfix h1 >/dev/null 2>&1; echo p>patch.txt; git add patch.txt; git commit -q -m patch
@ -119,7 +132,7 @@ chk "idempotent 2nd run" "[ \"$before\" = \"\$(md5sum .gitignore)\" ]"
echo "T10 — COHERENCE: hook verdict == lib predicate (drift detector, #4)"
newrepo coh; echo a>a; hookon; gitflow_init >/dev/null 2>&1
for br in main develop feature/x bugfix/y release/z hotfix/w master mainline qa; do
for br in main develop feature/x bugfix/y release/z hotfix/w chore/m master mainline qa; do
if gitflow_protected_base "$br"; then lib=protected; else lib=open; fi
git checkout -q -B "$br" 2>/dev/null
printf 'x\n' >> a; git add a

View File

@ -21,7 +21,7 @@ GITFLOW_GITIGNORE_TEMPLATE="${GITFLOW_GITIGNORE_TEMPLATE:-$_GITFLOW_LIB_DIR/../t
# ── predicates / pure helpers ────────────────────────────────────────────────
# echo the gitflow type of a branch: feature|bugfix|release|hotfix|main|develop|other
# echo the gitflow type of a branch: feature|bugfix|release|hotfix|chore|main|develop|other
gitflow_branch_type() {
local br="${1:-$(git symbolic-ref --short -q HEAD 2>/dev/null)}"
case "$br" in
@ -31,6 +31,7 @@ gitflow_branch_type() {
bugfix/*) echo bugfix ;;
release/*) echo release ;;
hotfix/*) echo hotfix ;;
chore/*) echo chore ;;
*) echo other ;;
esac
}
@ -46,7 +47,7 @@ gitflow_protected_base() {
# echo the base a given type must fork from.
gitflow_base_for() {
case "$1" in
feature|bugfix|release) echo "$GITFLOW_DEVELOP" ;;
feature|bugfix|release|chore) echo "$GITFLOW_DEVELOP" ;;
hotfix) echo "$GITFLOW_MAIN" ;;
*) echo "gitflow: unknown type '$1'" >&2; return 2 ;;
esac
@ -103,7 +104,7 @@ gitflow_finish() {
br="$(git symbolic-ref --short -q HEAD)" || { echo "gitflow_finish: detached HEAD" >&2; return 3; }
type="$(gitflow_branch_type "$br")"
case "$type" in
feature|bugfix)
feature|bugfix|chore)
_gitflow_merge_into "$GITFLOW_DEVELOP" "$br" && _gitflow_delete "$br" ;;
release)
_gitflow_merge_into "$GITFLOW_MAIN" "$br" \

View File

@ -50,6 +50,13 @@ Running `/capitalize` right after a ritual should propose (near) nothing.
This skill is NOT `/prune-memory` (registry curation — merge, compress,
mark-superseded). It only appends.
## Gitflow aiguillage (before any write)
Before STEP 4 writes anything, follow `$HOME/.claude/lib/gitflow-aiguillage.md`
— this skill's TYPE = `chore`. On `main`/`develop` it branches to `chore/<name>`
off develop, so the memory commit lands on a branch, never direct on a protected
base; on a working branch it proceeds in place. Never `gitflow finish` (human-gated).
## STEP 0 — PRECHECK
```bash

View File

@ -34,4 +34,7 @@ Ritual answers are deduped like any other candidate — a dup is dropped and its
existing ID shown, not re-logged. This is the upgrade over the legacy `/close`,
which wrote ritual answers fresh with no dedup.
The gitflow aiguillage (branch to `chore/*` on a protected base before writing)
runs inside `capitalize` — not duplicated here.
→ Use the Skill tool to launch `capitalize` with argument `--ritual`.

View File

@ -68,11 +68,13 @@ gives a **real-time, explicit go for THIS merge** — "merge it", "feature OK",
All of these mean: present the merge as a question, then wait for the explicit go.
## Aiguillage (assistance skills)
## Aiguillage (assistance + standalone memory/doc skills)
On a protected base, assistance skills (`feat`/`bugfix`/`hotfix`) call
`start <type>` to branch first; on a working branch they commit in place. Same
`protected-base` predicate the out-of-skill hook uses.
On a protected base, assistance skills (`feat`/`bugfix`/`hotfix`) AND the standalone
memory/doc skills (`capitalize`/`close`/`prune-memory`/`reconcile`, TYPE `chore`)
call `start <type>` to branch first; on a working branch they commit in place. Same
`protected-base` predicate the out-of-skill hook uses. Caller→type map + rationale:
`lib/gitflow-aiguillage.md`.
## Common Mistakes

View File

@ -62,6 +62,13 @@ If working tree is dirty on any registry file → STOP with: "Commit or
stash pending changes in `.claude/memory/` first. Skill writes in-place.
Git is the only backup."
## STEP 0b — Gitflow aiguillage (after PRECHECK, before any write)
PRECHECK first (clean tree = the backup). Then follow
`$HOME/.claude/lib/gitflow-aiguillage.md` — this skill's TYPE = `chore`. On
`main`/`develop` it branches to `chore/<name>` off develop so the curation lands
on a branch; on a working branch it proceeds in place. Never `gitflow finish`.
## STEP 1 — AUDIT (per registry)
For each target registry (filter by `$ARGUMENTS` or all 5):

View File

@ -34,6 +34,8 @@ Not for: curating/compressing registries → `/prune-memory`. The skill never ed
Plus **contradiction candidates**`reconcile_contradiction_candidates`: accepted-BDR ⇄ open-chantier overlap, surfaced for human review.
## The gate (mandatory)
**Before applying (A/B):** follow `$HOME/.claude/lib/gitflow-aiguillage.md` — TYPE `chore`. On `main`/`develop` the write-back branches to `chore/<name>` off develop first, so a reconciled TODO never lands direct on a protected base; on a working branch it applies in place. Never `gitflow finish` (human-gated).
Reconciling the TODO edits a tracked file → never silent. Show the proposed diff, then ask: **A** apply all · **B** select a subset · **C** touch nothing. Registries stay READ-ONLY (append-only; curation is `/prune-memory`).
## Honest limits (do not over-read the guarantee)