Add living-spec workflow for solo product documentation

[Go7hic]

What changed

• add a new living-spec skill with three operations:
  • inspect decides whether a change needs durable documentation and finds the repository's existing source of truth;
  • draft creates one lightweight change brief for multi-session or multi-PR work;
  • converge updates current product truth only after real-surface verification;
• add portable templates for current product docs, temporary change briefs, and ADRs;
• integrate the documentation persistence check and convergence gate into the Feature playbook;
• expose living-spec from the pstack entry skill and document the solo-project workflow in README and COVERAGE;
• protect the portable-only skill from upstream imports through UPSTREAM_MANIFEST.json.

Why

Solo developers often use pstack directly and still need a maintained description of what the product currently promises. Previously, pstack recorded design and execution evidence but did not explicitly converge verified product behavior into a durable current-truth document.

This change adds that missing layer without requiring OpenSpec or forcing documentation onto trivial edits and internal refactors.

Behavioral rules

• reuse OpenSpec, an existing spec framework, ADR convention, or product-doc hierarchy when the repository already has one;
• create documentation only for durable user-visible, operator-visible, API, security, billing, permission, retention, or business behavior;
• keep current truth, temporary change context, ADR rationale, and execution evidence in separate artifacts;
• update current truth from the final verified implementation, not from the initial plan;
• report a convergence gap instead of rewriting intent to match broken code.

Validation

The repository's pull-request workflow will run:

• mirror consistency checks;
• full strict portability audit;
• Markdown relative-link validation;
• model override fixtures;
• import idempotency checks.

Review focus

• whether the persistence decision is light enough for solo projects;
• whether Feature should invoke living-spec only for durable behavior changes;
• whether the three templates capture enough context without recreating a full spec framework.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b206901995

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve non-user-facing persistence triggers

For features that change operator-visible, API, security, billing, permission, or retention behavior without being directly user-visible, this instruction permits not required, even though the persistence decision in skills/living-spec/SKILL.md explicitly includes all of those categories. Since agents copy the Feature playbook into their todo list, this narrower shortcut can skip the product-document update that the new workflow is intended to require; use the same complete trigger set here.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Mark ADRs created during convergence as accepted

When an ADR is created through living-spec converge, the implementation has already been verified and the durable decision has already been selected, but this template leaves the resulting record in proposed state. Because the workflow contains no later step that promotes the ADR, completed changes will retain an apparently unresolved decision; default this convergence-only template to an accepted status or explicitly require the status transition.

Useful? React with 👍 / 👎.