Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de 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

Abierto
  • ¿Algo no está bien?
#41 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
shell
Área
cli

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
Shell
Estrellas
16
Forks
6
Merge medio
6 h 24 min
PR fusionados (30 d)
5

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de DimitriGeelen/agentic-engineering-framework

Todos los issues de DimitriGeelen/agentic-engineering-framework

Issues similares

Más issues de Shell/Bash

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.