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

MCP create_element can't produce <id>.md files for id-identified types (and writes packages as Name.md)

Chiusa
  • Qualcosa non va?
#185 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

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

Direzione di ricerca

Start with valid_qname in crates/syscribe-model/src/mutate/mv.rs, then trace the MCP create_element and apply_changes create operations; the issue's reproduction gives a concrete case to run. Check how move_element handles qnames and read the referenced spec sections (§8 and §11.3). Done means id-identified elements use the id as the file stem, packages use _index.md, and the documented MCP behavior matches.

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

Descrizione

Problem

For id-identified types (Requirement, TestCase, ADR, PlanningItem, …) the spec says the file is <id>.md and the id is the qualified-name stem (§8 / name scheme), e.g. model_auto/Requirements/Safety/REQ-ENG-SAFE-001.md → Requirements::Safety::REQ-ENG-SAFE-001.

The MCP create_element tool (and the create op in apply_changes) derives the file path directly from a caller-supplied qname, and valid_qname (crates/syscribe-model/src/mutate/mv.rs) only accepts [A-Za-z0-9_] segments. So a hyphenated id can never be the file name:

  • create_element {qname: "Requirements::Safety::REQ-ENG-SAFE-006", type: Requirement} → refused, reason: "not a valid basic qualified name".
  • The workaround is a different qname, e.g. Requirements::Safety::FaultLogging (or REQ_RL_005), which writes FaultLogging.md with id: REQ-ENG-SAFE-006 inside. The id is auto-allocated / explicit, but the file name and qname are unrelated to it.

Observed

  • In a real agent session (examples/chat-to-code/, PR #184) the agent hit this and named everything REQ_RL_005.md, ADR_RL_001.md, TC_RL_001.md, PI_RL_001.md (qname Requirements::REQ_RL_005, id REQ-RL-005). validate is clean and show REQ-RL-005 resolves, so nothing warns about it.
  • Related: create_element with type: Package writes Design.md next to a Design/ directory rather than Design/_index.md (spec §11.3: _index.md represents the containing directory's package). Validation is clean; not checked whether every consumer treats the two layouts alike.

Impact

  • Agent-authored models look different from hand-authored ones (REQ_RL_005.md vs REQ-RL-005.md), and the qname no longer matches the id.
  • The "permalink to <id>.md" convention (README, spec §1 rationale) doesn't hold for MCP-created elements; people can't find a requirement by its id in the file tree.
  • No diagnostic tells the author/agent that the file name deviates from the spec.

Suggested direction

  1. For id-identified types, let create_element take the parent package plus the id (explicit or auto-allocated) and write <parent>/<id>.md, bypassing the basic-name check for the stem (the id is already validated by is_stable_id). Keep the current qname form working for name-identified types.
  2. For type: Package, create <dir>/_index.md instead of <dir>.md.
  3. Optionally: a warning when an id-identified element's file stem differs from its id (opt-in / draft-suppressed, gateable with --deny), so existing models can be checked.
  4. Update move_element accordingly (its qname rewriting also uses valid_qname), and the help mcp / MCP tool docs.

Reproduce

cp -r model_auto /tmp/m
# drive `syscribe -m /tmp/m mcp` over stdio, then:
#   create_element {"qname":"Requirements::Safety::REQ-ENG-SAFE-006","type":"Requirement","dry_run":true}
#   → written:false, reason:"not a valid basic qualified name"
Lingua principale
JavaScript
Stelle
8
Fork
1
Merge medio
1h
PR unite (30g)
83

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

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 sjames/syscribe

Tutte le issue di sjames/syscribe

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.