Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン
  • 何か問題がありますか？
#185 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
52/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
活発
技術スタック
rust
領域
cli, tooling

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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"
主要言語
Rust
スター
7
フォーク
1
平均マージ
1時間 25分
マージ済み PR（30日）
27

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

sjames/syscribe のほかの issue

sjames/syscribe の issue をすべて見る

似ている issue

Rust の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。