Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Task template points at CLAUDE.md §AC Classification Guidance, which the framework never creates — the AC routing rule is unreadable where it is applied

Aperta
  • Qualcosa non va?
#41 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
shell
Ambito
cli

Direzione di ricerca

Start with the shipped .tasks/templates/default.md and the framework-generated CLAUDE.md; the report says the template references a missing AC Classification Guidance section. Then inspect the fw reviewer heuristic and fw doctor checks mentioned in the issue. Done when the generated guidance is present and the shipped cross-reference is checked; the issue also proposes a work-completed gate, whose scope may need maintainer clarification.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Context

  • Framework version: 1.6.769
  • Project: 1409-sprind (shared-tooling mode)
  • Reported: 2026-09-21T14:20:53Z

Description

The task template points at a CLAUDE.md section the framework never creates, and the rule it delegates is therefore unreadable

Severity: the framework's own AC-routing rule is invisible at the moment an agent applies it.
Measured in 1409-sprind (shared-tooling, v1.6.769), but the cause is in shipped scaffolding, so
every project initialised by fw init has it.

What happens

.tasks/templates/default.md carries the routing rule inline, in the ### Human block's comment:

── Prefix routing (T-1811, T-1878): default to [REVIEWER] if Expected is grep-able ──
If your Expected clause is grep-able / file-exists / structural (a deterministic
shell check), prefer [REVIEWER] — that AC should be an Agent AC with the reviewer
command in `## Verification` instead of a Human AC here.
See CLAUDE.md §AC Classification Guidance for the conversion rule.

CLAUDE.md has no §AC Classification Guidance. grep -n 'AC Classification' CLAUDE.md
returns nothing — not in this project, and not in the CLAUDE.md the framework ships.

Why that is worse than a dangling link

The two locations have opposite lifetimes:

Location Lifetime Contains
template comment deleted in normal use — the agent replaces the placeholder block, comments included half the rule, plus a pointer
CLAUDE.md auto-loaded every session, permanent nothing

So the durable, always-present location holds no guidance, while the ephemeral one holds a partial
rule pointing at the empty one. An agent reads the routing hint exactly once, then writes ACs from
memory with no anchor to check against — and the artifact it produces carries no trace of the rule
it was supposed to follow.

Measured consequence

In one afternoon in this project, three tasks went partial-complete with Human ACs. One of them —
"the three stored files are byte-identical to what you dropped" — is a sha256sum comparison
the agent had already run and recorded in the task's own Decisions section before writing the
AC. A fourth, older task carried the same shape from the day before.

fw reviewer then agreed, unprompted: run against those tasks it returned Needs Human: no on
all three, and on one it emitted human-ac-mechanical-signal against the AC itself. The tool that
detects the defect already ships — it is simply not reached, because nothing routes to it at the
moment ACs are written and nothing checks the result afterwards.

The operator's reaction is the real report: reviews had become a queue of eight tasks, several of
them asking a person to confirm a hash.

The framework has already learned this exact lesson elsewhere

This project's learnings register carries PL-011 (T-1074): "A cross-reference from code into a
document rots silently unless a check spans both." It was surfaced to the agent by fw context focus on the same day. The lesson exists; it has not been applied to the framework's own
template-to-CLAUDE.md reference.

Suggested fix, in order of leverage
  1. Ship the section. Put §AC Classification Guidance in the CLAUDE.md the framework
    generates, containing the actual conversion rule rather than a pointer. The template's comment
    then becomes a reminder of something the agent can always re-read, instead of the only copy.
  2. Make the default structural, not advisory. At the work-completed transition, when a task
    would go partial-complete, run the human-ac-mechanical-signal heuristic fw reviewer already
    has. Emit a warning naming the AC, or refuse until the AC is reclassified or an override is
    recorded. Today the check exists but only runs when an agent thinks to invoke it — which is
    precisely the agent that just mis-classified the AC.
  3. Check the reference. A fw doctor line asserting that every See CLAUDE.md §X in the
    shipped templates resolves to a heading in the project's CLAUDE.md. This is PL-011 applied to
    the framework itself, and would have caught the defect the day the pointer was written.
Fixed locally

1409-sprind now carries its own ### AC Classification Guidance (T-1119) above ## Core Principle
(so fw upgrade cannot remove it), stating the default as [REVIEWER] + Agent AC, the test
("if a shell command can settle the Expected clause, it is not a Human AC"), that a check the agent
has already run may never be routed to a person, that reviews are never blocking, and that
sovereign decisions — Tier-0 approvals, fw inception decide, arc closes — are commands, not
checkboxes. Five tasks were reclassified and closed against it. That is a per-project patch; the
scaffolding defect is upstream.

Reported via fw upstream report from field installation

Lingua principale
Shell
Stelle
16
Fork
6
Merge medio
6h 24m
PR unite (30g)
5

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di DimitriGeelen/agentic-engineering-framework

Tutte le issue di DimitriGeelen/agentic-engineering-framework

Issue simili

Altre issue su Shell/Bash

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.