Skip to main content
Status: draft · Version 0.2 · Filed 2026-04-25

​
SPEC-039: NYI Runtime Contract — Stub/Placeholder Signaling for Prism Verbs

​
Version

0.2

​
Status

draft

​
Origin

The constitution (PRISM.md, CLAUDE.md, AGENTS.md) references hd_exec as the session-pickup verb. Six markdown files describe its contract. Zero source files implement it. Two-year-old hanging chad. The methodology layer made a promise the runtime never kept; agents and vibe-coding callers had no signal this was vapor until they tried to call it. This spec establishes a dual-layer signal: (1) every stub/placeholder verb returns a canonical “not yet implemented” runtime response that any caller recognizes; (2) every stub carries a grep-able source-level marker; (3) prism_audit surfaces both. Methodology promises are now backed by runtime teeth — or they explicitly self-declare as vapor.

​
§1 — Canonical Response Shape

A verb that is declared but not yet implemented MUST return: 
{
  "status": "not_yet_implemented",
  "code": "NYI",
  "verb": "<verb_name>",
  "tracking_spec": "SPEC-XXX",
  "tracking_issue": "<url-or-id>",
  "message": "<one-line human description>",
  "since_constitution_version": "<bios_version-when-declared>"
}
status and code are required. verb is required. tracking_spec is required if a spec exists for the eventual implementation; otherwise tracking_issue must point to a tracker entry. message is required and must answer: what would a caller have expected this verb to do? Wire-level mappings:
  • MCP / JSON-RPC: structured response with status: "not_yet_implemented", result is the payload above. NOT an exception — callers should be able to introspect without try/except.
  • HTTP / REST: status 501 Not Implemented, body is the canonical payload above. Standard HTTP semantics — meets caller expectations.
  • gRPC: status code UNIMPLEMENTED (12), trailer carries serialized canonical payload.

​
§2 — Source-Level Marker Convention

Every stub function MUST carry a marker comment on the line above its declaration:
LanguageMarker
Python# PRISM-NYI: <reason> [tracking: SPEC-XXX]
TypeScript / JavaScript// PRISM-NYI: <reason> [tracking: SPEC-XXX]
Shell (bash/zsh)# PRISM-NYI: <reason> [tracking: SPEC-XXX]
PowerShell# PRISM-NYI: <reason> [tracking: SPEC-XXX]
Markdown (constitution refs)inline *(PRISM-NYI — tracking: SPEC-XXX)*
The marker is grep-able by a single regex (PRISM-NYI) across all source types. tracking is mandatory; <reason> is one-line.

​
§3 — Helper API

Python (added to mcp/server.py or a new mcp/nyi.py module): 
def prism_nyi_response(
    verb: str,
    tracking_spec: str = "",
    tracking_issue: str = "",
    message: str = "",
    since: str = "",
) -> dict:
    """Return the canonical NYI payload."""

def prism_nyi(verb: str, tracking_spec: str = "", message: str = ""):
    """Decorator: replace the wrapped function's body with the NYI payload."""
Usage pattern A — decorator (preferred for whole-verb stubs): 
# PRISM-NYI: hd_exec is constitutional vaporware [tracking: SPEC-040]
@prism_nyi(verb="hd_exec", tracking_spec="SPEC-040",
           message="Symmetric pickup to prism_wrap; see SPEC-040.")
async def hd_exec(pid: str) -> dict:
    ...  # body never runs
Usage pattern B — inline (for partial stubs / branches): 
async def some_verb(pid, mode):
    if mode == "experimental":
        # PRISM-NYI: experimental mode pending [tracking: SPEC-XXX]
        return prism_nyi_response(
            verb="some_verb",
            tracking_spec="SPEC-XXX",
            message="experimental mode not yet implemented",
        )
    ...  # real path
TypeScript: equivalent prismNyiResponse() helper. Shell: helpers not provided (stubs in shell should be vanishingly rare); use the comment marker + exit 78 (advisory exit code, not standard errno but distinguishable from 0/1/2). Decision Q1 (input validation in stub verbs): stubs do NOT validate their inputs. The decorator returns the canonical payload immediately without running any validation logic. Validation belongs to the real implementation when it ships.

​
§4 — prism_audit Integration

prism_audit is currently a dispatch verb that returns an instruction string to the calling agent (mcp/server.py:2939-2951). Extend it to actually audit the source tree: 
{
  "stubs_in_source": [
    {
      "verb": "hd_exec",
      "file": "mcp/server.py",
      "line": 2310,
      "tracking_spec": "SPEC-040",
      "reason": "constitutional vaporware",
      "marker_kind": "decorator"
    }
  ],
  "constitution_refs": [
    {
      "file": "PRISM.md",
      "line": 88,
      "verb": "hd_exec",
      "marker_present": false,
      "tracking_spec": null
    }
  ],
  "summary": {
    "total_stubs": 1,
    "tracked": 1,
    "untracked": 0,
    "constitution_refs_unmarked": 4
  },
  "exit_status": "fail"
}
Decision Q2 (audit failure mode — HYBRID): prism_audit returns exit_status: "ok" when every stub has a tracking_spec AND every constitution reference to an unimplemented verb carries the *(PRISM-NYI — SPEC-XXX)* annotation. Returns exit_status: "fail" (and a non-zero exit code when invoked via CLI) when ANY stub is untracked OR ANY constitution ref is unmarked. Tracked stubs are advisory; untracked stubs and unmarked constitution refs are blocking. A constitution reference to an unimplemented verb that LACKS the *(PRISM-NYI — tracking: SPEC-XXX)* annotation is also surfaced as a rules_reminders entry of severity warn on subsequent prism_start.

​
§5 — Verification

  1. Calling a verb decorated with @prism_nyi(...) returns the canonical payload with all required fields.
  2. Calling a stub verb with deliberately malformed inputs (e.g., hd_exec(pid=42)) returns the SAME canonical NYI payload — no validation interception (per Q1 decision).
  3. prism_audit lists every PRISM-NYI marker in mcp/, backend/, cli/, bin/.
  4. prism_audit returns exit_status: "fail" when an untracked stub exists or a constitution ref lacks the annotation.
  5. After SPEC-040 ships and removes hd_exec’s NYI marker, prism_audit no longer lists it under stubs_in_source and exit_status flips back to ok (assuming no other untracked stubs).
  6. HTTP wire test: a REST call to an NYI endpoint returns 501 with the canonical body.
  7. gRPC wire test: an UNIMPLEMENTED status carries the canonical payload in trailer metadata.

​
§6 — Decisions

  • Q1 (input validation in stubs): SKIPPED / settled — orthogonal to the dual-signal architecture (return code + source marker) which already addresses the “don’t forget” goal. Stubs do not validate inputs; validation logic belongs to the real implementation.
  • Q2 (audit failure mode): HYBRID. Tracked stubs (with tracking_spec) are advisory. Untracked stubs AND constitution refs missing the marker cause prism_audit to return exit_status: "fail" and non-zero CLI exit. Forces every stub to be either implemented or explicitly declared.
  • Q3 (marker token): PRISM-NYI. Namespaced (won’t false-positive on grep), brand-consistent with PRISM_AGENT_IDENTITY / prism_*, self-documenting. Applied across all source types per §2.
Last modified on April 27, 2026