> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SPEC-039 v0.2: NYI Runtime Contract — Stub/Placeholder Signaling for Prism Verbs

> NYI Runtime Contract — Stub/Placeholder Signaling for Prism Verbs

<Info>**Status:** `draft` · **Version** `0.2` · Filed 2026-04-25</Info>

# 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:

```json theme={null}
{
  "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:

| Language                     | Marker                                        |
| ---------------------------- | --------------------------------------------- |
| 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):

```python theme={null}
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):

```python theme={null}
# 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):

```python theme={null}
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:

```json theme={null}
{
  "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.