ns-living-spec

Living Spec Consolidator

Maintain docs/specs/ as current functional truth of product.

Session boot

See ../../ns-harness/references/session-boot.md and ../../ns-harness/references/artifact-layout.md.

Modes

Mode	When	Source of truth	Code + delivery gates
Version (default)	Version closure after delivery	docs/versions/{version_san}/sdd/ artifacts	Required (Code Review: Approved and Delivery Review: Approved, each score 10)
Ad-hoc	Invoked by ns-coder (or human) after both Approved	{task_description} + approved git diff	Required (both Approved)
Appearance	Invoked by ns-proto-creator or ns-proto-visual-guide	Guide/prototype path + short behavioral delta	None

Appearance if invoker pass mode appearance (or equivalent: guide/prototype path + behavioral delta, no review verdict). Ad-hoc if mode ad-hoc (or equivalent: no {version_san}, task description + approved diff). Else Version.

Write target

Orthogonal to Modes (which decide what to document and which gates apply). Decide where to write:

Target	When	Writes
Direct	Integration branch, or branch role unknown, or docs/specs/_pending/ absent (legacy repo)	docs/specs/{domain}.md + INDEX.md per Workflow. If _pending/ holds fragments, run Consolidate first
Fragment	Feature branch (../../ns-harness/references/artifact-layout.md → Branch role) and docs/specs/_pending/ exists	Exactly one new file per domain: docs/specs/_pending/{label}-{slug}.md from references/pending-fragment.template.md. Nothing else under docs/specs/
Consolidate	Integration branch: asked explicitly, or before a Direct write	Applies every fragment, then deletes it (see Consolidate)

Why: parallel MRs editing the same domain file conflict; distinct new files never do. Layout: ../../ns-harness/references/artifact-layout.md → Living spec fragments.

Fragment keeps every gate, skip rule, and domain-mapping step of the active mode. Only step 2 changes (write the delta to the fragment instead of editing the domain file) and step 3 is skipped (INDEX.md is touched only on consolidate). {slug} = short kebab-case of task or issue; {label} = changelog label of the mode. Report with Living specs staged (domains + fragment paths).

Consolidate

Gates were already enforced when each fragment was written — do not re-ask for review verdicts.

1. List docs/specs/_pending/*.md; process in filename order (deterministic).
2. Per fragment: read the target {domain}.md entirely; apply requirement/data-model/endpoint deltas; append the fragment's changelog entry with its label; create the domain file from references/domain-spec.template.md if missing.
3. Update INDEX.md once at the end (date + versions per domain touched).
4. Delete each fragment only after it applied cleanly.
5. Conflict (fragment updates or removes a requirement that no longer exists or was renamed by an earlier fragment): do not guess. Leave that fragment in place and list it in the report with the reason.
6. Report: ## Living specs consolidated — fragments consumed, fragments left (with reason), domains updated.

Run only on the integration branch (or role unknown). Never on a feature branch.

When invoked

• Version closure post Code Review: Approved and Delivery Review: Approved — Version
• Ad-hoc coding, both reviews Approved, docs/specs/ exists — Ad-hoc
• Prototype create/evolve or normative visual guides documenting behavioral UX — Appearance
• Not Version/Ad-hoc before both Approved

Prerequisites

Version mode

• Resolved requirements.md — sdd/ first, else legacy version root (artifact-layout.md Legacy path resolution)
• Invoker reports Code Review: Approved and Delivery Review: Approved — no code-review-report.md required
• Resolved execution-handoff.md — sdd/ first, else legacy version root (tasks completed)

Ad-hoc mode

• docs/specs/ already exists (not create tree from scratch)
• Invoker reports Code Review: Approved and Delivery Review: Approved
• {task_description} + approved working-tree diff (behavioral change)
• Skip (no writes) if diff non-behavioral: cosmetic, rename-only, pure refactor with no API/schema/UX/domain behavior change — report skipped

Appearance mode

• Input: path to appearance guide and/or prototype/ surface + short behavioral delta (what users can do / see changed or captured)
• May create docs/specs/ + INDEX.md if missing
• SHALL only for product-visible behavior (flows, fields, states, permissions cues)
• Never paste Element | How it should appear tables into domain specs — link guide instead
• Skip pure chrome polish (spacing, color tweak, font swap, no behavior change) — report reason
• No Code Review / Approved requirement

Workflow

Shared steps 1–4 all modes. Changelog label differs by mode.

1. Identify affected domains

Map features to canonical domains (examples):

Feature area	Domain file
Auth, login, RBAC	auth.md
Users, profiles	users.md
Billing	billing.md
Notifications	notifications.md
Reports	reports.md
Integrations	integrations.md
Agent / graph	agent.md

docs/specs/agent-architecture.md is the living ADR (ns-agent-architecture). Not a domain spec. Do not treat as {domain}.md.

Naming: English, kebab-case, singular (user-profile.md). Multi-domain features update multiple specs.

Ad-hoc: map from {task_description} + diff only — no invent unrelated domains.

Appearance: map from behavioral delta + guide/prototype scope only; add domain links to appearance docs under Related / references when useful.

2. Per domain

If docs/specs/{domain}.md missing: create from references/domain-spec.template.md

If exists: read entirely; append or update — never blind overwrite

Per relevant feature:

• Add or update ### Requirement: blocks (SHALL + scenarios)
• Update ## Data model + ## Endpoints when schema/API changed (Version/Ad-hoc)
• Appearance: prefer UX/behavior requirements; no invent APIs/schemas not evidenced
• Append ## Changelog entry:
  • Version: **{version_san}** — {ISO date}: {summary}
  • Ad-hoc: **adhoc-YYYY-MM-DD** — {ISO date}: {summary} (summary from task + diff)
  • Appearance: **appearance-YYYY-MM-DD** — {ISO date}: {summary}

3. Update INDEX.md

Create or update docs/specs/INDEX.md:

# Domain specs — {product_name}

| Domain | File                 | Last updated | Versions      |
| ------ | -------------------- | ------------ | ------------- |
| auth   | `docs/specs/auth.md` | {date}       | {version_san or adhoc-YYYY-MM-DD or appearance-YYYY-MM-DD} |

4. Consolidation report

Emit short report for handoff:

## Living specs updated
| Domain | Action | File |
...
Mode: {version|ad-hoc|appearance}
Requirements added: N
Requirements updated: N
New specs: N

Fragment target: replace the heading with ## Living specs staged and list docs/specs/_pending/ paths instead of domain files.

If skipped (non-behavioral, polish-only, or Ad-hoc missing docs/specs/):

## Living specs skipped
Reason: {missing docs/specs/|non-behavioral diff|chrome polish only}

Critical rules

• English for spec content
• Requirements use verifiable SHALL language
• Read before write on existing specs
• Planning orchestrator read INDEX.md before new version requirements
• Ad-hoc must not create version artifacts under docs/versions/
• Ad-hoc must not invent {version_san}
• Appearance must not paste normative Element|How tables into specs
• Appearance must not require Code Review Approved
• Fragment target must not edit docs/specs/{domain}.md or INDEX.md; Consolidate must not delete a fragment it did not fully apply
• Do not overwrite docs/specs/agent-architecture.md (ns-agent-architecture living ADR). agent.md is behavior only

Related skills

• ns-spec-driven — reads living specs when planning (references/requirements-generator.md)
• ns-reviewer — prerequisite Code Review: Approved for Version/Ad-hoc
• ns-judge — prerequisite Delivery Review: Approved for Version/Ad-hoc
• ns-coder — may invoke ad-hoc after both Approved
• ns-proto-creator / ns-proto-visual-guide — may invoke appearance mode