# Reported issues for SpecMgr Pod holds 13 of 13 GitHub reports that passed its relevance review. This can include external user reports, maintainer-confirmed bugs, and concrete feature gaps. Treat them as evidence to inspect, not a count of distinct defects. Back to [SpecMgr](/mcp/specmgr). ## Most discussed ### MCP server silently resolves per-domain base directories relative to CWD, with no way for a client to self-diagnose a misconfiguration ## Problem The README's own "Add to OpenCode" example (and this repo's active `opencode.jsonc` `specmgr` entry, in the environment I was working in) configures the MCP server as: ```json "specmgr": { "type": "local", "enabled": true, "command": ["uvx", "--from", "biz-dfch-specmgr[mcp]", "specmgr", "mcp"] } ``` No `--directory`, and none of `SPECMGR_DOCS_DIR` / `SPECMGR_ADR_DIR` / `SPECMGR_FEAT_DIR` are set. Every per-domain base directory that resolves relative to the *server process's… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/51) · 2026-09-01 · closed · 3 comments ### Validation failures surface as opaque tool errors instead of structured results (and list_* silently reports 0 documents when all fail to parse) ## Summary When a document fails frontmatter/body validation, the affected MCP tools (`validate_`, `parse_`, `get_`) raise an uncaught exception that surfaces to the MCP client only as a bare `Error executing tool `, with no indication of which field failed or why. Separately, `list_` appears to silently skip documents that fail to parse, reporting `total: 0` for a directory that actually contains many (invalid) documents, rather than surfacing the failure… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/83) · 2026-09-03 · open · 2 comments ### validate_feat/create_feat (and likely other validate_/create_/update tools) surface bare HTML-like tokens as an unhelpful generic error, not the actionable detail feat-27-validation promised ## Finding While drafting a FEAT document body (`feat-69-update-context`) through `validate_feat`/`create_feat`, a structural validation failure surfaced only as a bare, completely generic `Error executing tool` -- no exception type, no message, no document-relative field path, no line number, no cause/fix hint. Root cause (found by manual bisection): a bare `` placeholder token used outside of backticks, e.g. in a heading: #### Phase 3: Per-domain create_ tools is parsed by the… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/70) · 2026-09-02 · closed · 2 comments ### TSK: bare -style tokens fail validation; MCP tools report only 'Error executing tool' (no detail) ## Problem Two related issues, found while authoring a TSK through the specmgr MCP server (v0.13.0): 1. **A bare ``-style token in a TSK body fails validation/creation.** `` is a well-formed HTML tag name, so the markdown parse treats it as raw HTML and the TSK document model cannot represent it. Such tokens are common in technical prose — this repo's own ADR `ec9f5262-9912-49d0-903f-fcfb54f28c13` is titled "Expose _list as paged MCP tools (list_), not… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/27) · 2026-08-27 · closed · 2 comments ### Generic update tool: frontmatter-length assumptions + no feedback let an off-by-N line offset silently corrupt a document ## Summary The generic `update` tool's line-range mode (`offset`/`limit`) addresses 1-based lines of the **frontmatter-stripped body**, sourced correctly only via `get_(id, raw=True)`. Two independent gaps make it easy to silently corrupt a document with a wrong offset: 1. Nothing warns that the on-disk file's YAML frontmatter block is **variable-length** (depends on which optional fields serialize -- e.g. a `null` field may or may not be emitted), so computing a body-line offset as… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/153) · 2026-09-23 · open · 1 comment ### create_feat silently fails on date-only Updates/Decisions Made timestamps (inconsistent with create_tsk) ## Summary `create_feat` requires a **full timestamp** (date + time) in every `Progress > Updates` and `Progress > Decisions Made` entry heading. A bare date — which is accepted without issue by `create_tsk` for its equivalent "Recent Updates" section — causes `create_feat` to fail with no explanation. ## Current scope (updated 2026-09-23) This issue is tracked as **feat-146-date-time** (`.specmgr/feat/feat-146-date-time/README.md`) under ADR **8c889262-152b-4b8e-ae2c-75371f7a9edf** ("Use… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/146) · 2026-09-22 · closed · 1 comment ### set_status error message doesn't list allowed status values for the artifact type Calling `set_status` with an invalid `status` value for a given `type` currently fails with only a generic, non-descriptive error (no exception detail, no enum listing) instead of surfacing the domain's closed vocabulary. Example: `set_status(id=, type="qa", status="closed")` returned only: ``` Error executing tool set_status ``` No indication of which values are actually valid for `qa` (turned out to be e.g. `draft`/`done`/... — had to be discovered by trial and error).… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/103) · 2026-09-07 · closed · 1 comment ### Soft-wrapped list items break create_feat/validate_feat (and likely other models/md domains) with an opaque error ## Summary Soft-wrapped list/checklist items (a bullet's text continued onto an indented second physical line) cause the `models/md`-based parser/renderer to fail with an opaque, unhelpful error when going through MCP tools such as `create_feat`/`validate_feat` — the underlying exception/validation message is swallowed and only `"Error executing tool create_feat"` (no further detail) is surfaced to the MCP client. This was discovered while drafting a `feat` document (`feat-46-remove-adr`)… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/99) · 2026-09-04 · closed · 1 comment ## Most recent ### set_status shall return without updating anything when target status equals source status When the `set_status` tool is called with a target status that is identical to the document's current status, it should be a no-op: return successfully without bumping `updated` or writing anything to disk, instead of performing (or attempting) a redundant update. [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/109) · 2026-09-07 · closed · 0 comments ### DEC Updates heading accepts yyyy-MM-dd as well as a full timestamp (undocumented) The \`## Updates\` section of a DEC document validates each entry heading against: \`\`\` ^\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2}:\d{2}\.\d{3}(?:Z|[+-]\d{2}:\d{2}))?(?: - | : ).+$ \`\`\` This accepts two forms, neither of which is documented anywhere (template/example only show the date-only form): 1. Date only: \`### 2026-09-07 - Created\` 2. Date + full timestamp (space-separated, ms precision, \`Z\` or \`±HH:MM\` offset): \`### 2026-09-07 14:23:00.123Z - Created\` Note the timestamp form does… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/104) · 2026-09-07 · closed · 0 comments ### set_feat_id should return frontmatter only, like the other write tools ## Summary `set_feat_id(id, new_id)` currently returns the **full document** (frontmatter + body) on a successful rename, unlike the generic write tools that were converted to frontmatter-only returns in feat-69-update-context. ## Background Per feat-69-update-context (see AGENTS.md), on a successful write the following tools now return the domain's frontmatter object only (no body): - the generic `update` tool - the generic `set_status` tool (its twelve non-`adr` adapters) - the generic… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/80) · 2026-09-03 · closed · 0 comments ### MCP write tools return the full document on every call, filling up context quickly -- want OpenCode edit-tool-like minimal responses ## Finding While running a design/elicitation session against `feat-63-refine` (updating both a `qa` document and the feature's own README via the generic `update` tool), we noticed that **every mutating MCP tool call returns the complete, freshly re-parsed document** -- not a diff, not just the changed section, and not a lightweight success acknowledgement. Confirmed for `update` (`general/tools/`): both the **whole-body replace** mode (no `offset`) and the **line-range splice** mode… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/69) · 2026-09-02 · closed · 0 comments ### Template placeholder timestamps use round 00:00:00.000Z values, inviting agents to copy them verbatim instead of substituting the real time ## Summary Every whole-body document template's `#### {timestamp} - {title}` placeholder entries (and several templates' placeholder frontmatter `created`/`updated` values) use a suspiciously *round* timestamp -- specifically all-zero time-of-day, `00:00:00.000Z` -- as the stand-in value. A round, all-zero value doesn't visually signal "this is a placeholder, replace me with the real current time"; it reads just like any other plausible timestamp. In practice this causes an LLM agent (and… [Read the thread](https://github.com/dfch/biz.dfch.SpecMgr/issues/67) · 2026-09-02 · closed · 1 comment The remaining reports are on [the project's issue tracker](https://github.com/dfch/biz.dfch.SpecMgr/issues).