@osovv/vv-opencode 0.35.29 → 0.35.30

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## <small>0.35.30 (2026-06-24)</small>
+
+### Summary
+
+Spec packages created by the vv-spec skill now use date-prefixed directory names (YYYY-MM-DD-slug) so active packages sort by creation date and are easier to identify, with corresponding updates to the vv-spec, vv-plan, and vv-controller skill and agent templates. The project documentation has been fully migrated to the GRACE 4 artifact model, replacing legacy XML sources under docs/ with the current .grace/ directory structure, and all GRACE context artifacts—requirements, technology, principles, deployment, and UX guidelines—have been refined for clarity and accuracy. Legacy GRACE 3 XML documents and superseded workflow plan handoff notes have been removed, and stale migration references have been cleaned up from graph and verification indexes.
+
+* feat(vv-spec): date-prefix spec packages ([0dba659](https://github.com/osovv/vv-opencode/commit/0dba659))
+* docs: drop migration report artifact ([327812d](https://github.com/osovv/vv-opencode/commit/327812d))
+* docs: finalize GRACE migration cleanup ([496236f](https://github.com/osovv/vv-opencode/commit/496236f))
+* docs: migrate project to GRACE 4 ([ba3e162](https://github.com/osovv/vv-opencode/commit/ba3e162))
+* docs: refine GRACE context requirements ([73245b1](https://github.com/osovv/vv-opencode/commit/73245b1))
+* docs: refine GRACE deployment context ([cd2da0f](https://github.com/osovv/vv-opencode/commit/cd2da0f))
+* docs: refine GRACE principles context ([ad1b050](https://github.com/osovv/vv-opencode/commit/ad1b050))
+* docs: refine GRACE technology context ([eeff4d2](https://github.com/osovv/vv-opencode/commit/eeff4d2))
+* docs: refine GRACE UX guidelines ([09d075a](https://github.com/osovv/vv-opencode/commit/09d075a))
+* docs: remove legacy GRACE 3 artifacts ([c9b910d](https://github.com/osovv/vv-opencode/commit/c9b910d))
+* docs: remove stale GRACE migration references ([6ad640a](https://github.com/osovv/vv-opencode/commit/6ad640a))
+
 ## <small>0.35.29 (2026-06-22)</small>
 
 ### Summary

package/README.md

@@ -44,12 +44,12 @@ Request / idea
    ↓
 vv-spec
    asks clarifying questions
-   writes .vvoc/specs/<id>/spec.xml
+   writes .vvoc/specs/YYYY-MM-DD-<slug>/spec.xml
    waits for spec approval
    ↓
 vv-plan
    reads the approved spec
-   writes .vvoc/specs/<id>/plan.xml
+   writes .vvoc/specs/YYYY-MM-DD-<slug>/plan.xml
    defines tasks, contracts, dependencies, and acceptance criteria
    waits for plan approval
    ↓
@@ -84,13 +84,15 @@ verification
 All artifacts for one feature live together:
 
 ```text
-.vvoc/specs/<id>/
+.vvoc/specs/YYYY-MM-DD-<slug>/
   spec.xml            # what should be built and why
   design-context.xml  # optional design memory
   plan.xml            # how to implement and verify it
 ```
 
-Specs and plans use a top-level lifecycle status: `draft` while being written, `approved` after explicit user approval, and `applied` after successful execution. `vv-execute` archives applied artifact packages by moving the entire spec package directory `.vvoc/specs/<id>/` to `.vvoc/specs/archive/<id>-<timestamp>/`.
+New `vv-spec` packages use a date-prefixed id (`YYYY-MM-DD-<slug>`, for example `2026-06-24-cache-store`) so active packages sort by creation date.
+
+Specs and plans use a top-level lifecycle status: `draft` while being written, `approved` after explicit user approval, and `applied` after successful execution. `vv-execute` archives applied artifact packages by moving the entire spec package directory `.vvoc/specs/YYYY-MM-DD-<slug>/` to `.vvoc/specs/archive/YYYY-MM-DD-<slug>-<timestamp>/`.
 
 ### XML grep
 
@@ -245,7 +247,7 @@ OpenCode config          → ./.opencode/opencode.json(c)
 vvoc config              → ./.vvoc/vvoc.json
 Managed agent prompts    → ./.vvoc/agents/*.md
 Managed skills           → ./.vvoc/skills/*/SKILL.md
-Spec package directory   → ./.vvoc/specs/<id>/
+Spec package directory   → ./.vvoc/specs/YYYY-MM-DD-<slug>/
   spec.xml              # normative spec document (required)
   design-context.xml    # curated design memory (optional)
   plan.xml              # implementation plan (created by vv-plan)
@@ -261,9 +263,9 @@ Managed agent prompts    → $XDG_CONFIG_HOME/vvoc/agents/*.md  (global)
                            ./.vvoc/agents/*.md                 (project)
 Managed skills           → $XDG_CONFIG_HOME/vvoc/skills/*/SKILL.md  (global)
                            ./.vvoc/skills/*/SKILL.md               (project)
-Spec documents           → ./.vvoc/specs/<id>/spec.xml
-Optional design context  → ./.vvoc/specs/<id>/design-context.xml
-Implementation plans     → ./.vvoc/specs/<id>/plan.xml
+Spec documents           → ./.vvoc/specs/YYYY-MM-DD-<slug>/spec.xml
+Optional design context  → ./.vvoc/specs/YYYY-MM-DD-<slug>/design-context.xml
+Implementation plans     → ./.vvoc/specs/YYYY-MM-DD-<slug>/plan.xml
 Persisted data           → $XDG_DATA_HOME/vvoc/
 Repository memory       → ./.vvoc/lessons/*.xml              (lazy vv-reflect fallback)
                            ./.vvoc/runbooks/*.xml             (lazy vv-reflect fallback)
@@ -312,7 +314,7 @@ Five workflow skills are scaffolded alongside agents:
 
 | Skill | When to use it | What it gives you |
 |---|---|---|
-| `vv-spec` | You have a feature or creative request and no agreed contract yet | A guided interview, recommended options, and a saved spec in `.vvoc/specs/<id>/spec.xml` |
+| `vv-spec` | You have a feature or creative request and no agreed contract yet | A guided interview, recommended options, and a saved spec in `.vvoc/specs/YYYY-MM-DD-<slug>/spec.xml` |
 | `vv-plan` | A spec is approved and ready to implement | A task-level implementation plan with file targets, contracts, dependencies, and acceptance criteria |
 | `vv-execute` | A plan is approved and you want it applied step by step | Ordered execution with verification and applied spec/plan archival |
 | `vv-review` | You want findings, not fixes | A review-only workflow that reports spec/code issues and stops before implementation |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.35.29",
+  "version": "0.35.30",
   "description": "A curated, opinionated set of OpenCode plugins for spec-first, review-driven, safer agentic development.",
   "type": "module",
   "main": "./dist/index.js",

package/schemas/vvoc/v3.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.35.29/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.35.30/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/templates/agents/vv-controller.md

@@ -127,7 +127,7 @@ Execution order for implementation mode: 1. `vv-implementer` 2. launch all requi
 </large_feature_protocol>
 
 <plan_artifacts>
-- **vv-plan implementation plans** live in spec packages. The canonical layout is: `.vvoc/specs/<id>/{spec.xml, design-context.xml optional, plan.xml}`.
+- **vv-plan implementation plans** live in spec packages. The canonical layout is: `.vvoc/specs/YYYY-MM-DD-<slug>/{spec.xml, design-context.xml optional, plan.xml}`.
   - **spec.xml** is normative — the single source of truth for requirements and design decisions.
   - **design-context.xml** (optional) is explanatory/non-normative curated design memory for planners and reviewers. It is NOT treated as additional requirements.
   - **plan.xml** is the vv-plan implementation plan, saved in the same package.

package/templates/skills/vv-plan/SKILL.md

@@ -14,7 +14,7 @@ You are the vv-plan skill. Your job is to take an approved spec and write an imp
 </language>
 
 <prerequisites>
-<rule>An approved spec MUST exist at .vvoc/specs/&lt;id&gt;/spec.xml before planning begins. The spec package directory &lt;id&gt; derives from the feature name used during vv-spec.</rule>
+<rule>An approved spec MUST exist at .vvoc/specs/&lt;id&gt;/spec.xml before planning begins. For newly created specs, vv-spec derives &lt;id&gt; as a date-prefixed package id in the form YYYY-MM-DD-&lt;slug&gt; from the feature name.</rule>
 <rule>Read the spec file in full.</rule>
 <rule>Check whether a sibling design-context.xml exists at .vvoc/specs/&lt;id&gt;/design-context.xml. If it exists, read it as explanatory context only. design-context.xml does NOT override or expand spec.xml — spec.xml remains normative and wins on conflicts.</rule>
 <rule>The spec's top-level &lt;status&gt; MUST be approved. If the status is draft, missing, applied, or any other value, stop and tell the user the spec must be explicitly approved before planning.</rule>

package/templates/skills/vv-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vv-spec
-description: Use BEFORE any implementation or planning — interviews the user one question at a time, proposes approaches, presents a design, writes a spec document to .vvoc/specs/<id>/spec.xml, and optionally creates a design-context.xml companion for complex sessions
+description: Use BEFORE any implementation or planning — interviews the user one question at a time, proposes approaches, presents a design, writes a spec document to .vvoc/specs/YYYY-MM-DD-<slug>/spec.xml, and optionally creates a design-context.xml companion for complex sessions
 ---
 
 <skill>
@@ -51,12 +51,12 @@ UX cues (roadmap, progress markers, depth estimates, checkpoints) are TRANSPAREN
 <rule>When first saving the spec, set &lt;status&gt;draft&lt;/status&gt;. Only change it to approved after the user explicitly approves the final spec. Never set applied yourself; applied is reserved for vv-execute after the approved plan has been fully executed.</rule>
 <location>Canonical layout — all artifacts for one feature live in a single spec package directory:</location>
 <layout>
-.vvoc/specs/&lt;id&gt;/
+.vvoc/specs/YYYY-MM-DD-&lt;slug&gt;/
   spec.xml              # normative spec document (required)
   design-context.xml    # curated design memory (optional)
   plan.xml              # implementation plan (created by vv-plan)
 </layout>
-<rule>Save spec.xml to .vvoc/specs/&lt;id&gt;/spec.xml. Derive &lt;id&gt; as a safe slug from the feature name (e.g., cache-store, batch-migration). Ensure the slug: (a) contains only lowercase alphanumeric characters, hyphens, and underscores; (b) does not start or end with a hyphen or underscore. Reject reserved names: draft, archive, template, plan, spec, vvoc, or names that match path-like patterns (contain /, \, .., or match an existing filesystem path separator). If .vvoc/specs/&lt;id&gt;/ already exists, check whether it is a continuation of the same draft session (same spec package from the same feature) — if yes, overwrite; if not, stop and ask the user for a different id or explicit overwrite approval. Do not silently overwrite or merge an unrelated existing package. Do not use date prefixes — the package directory is the organizational unit.</rule>
+<rule>Save spec.xml to .vvoc/specs/&lt;id&gt;/spec.xml, where &lt;id&gt; is a date-prefixed package id in the form YYYY-MM-DD-&lt;slug&gt; (for example, 2026-06-24-cache-store). Derive &lt;slug&gt; as a safe slug from the feature name (e.g., cache-store, batch-migration), then prefix it with the current date at spec creation time in YYYY-MM-DD format. Ensure the slug portion: (a) contains only lowercase alphanumeric characters, hyphens, and underscores; (b) does not start or end with a hyphen or underscore. Reject reserved slug values: draft, archive, template, plan, spec, vvoc, or names that match path-like patterns (contain /, \, .., or match an existing filesystem path separator). If .vvoc/specs/&lt;id&gt;/ already exists, check whether it is a continuation of the same draft session (same spec package from the same feature and date) — if yes, overwrite; if not, stop and ask the user for a different slug or explicit overwrite approval. Do not silently overwrite or merge an unrelated existing package.</rule>
 <rule>After creating or updating spec.xml, consider whether the session warrants a design-context.xml companion (see design_context section below).</rule>
 </spec_document_format>
 
@@ -73,7 +73,7 @@ UX cues (roadmap, progress markers, depth estimates, checkpoints) are TRANSPAREN
 <trigger>the user explicitly asks to preserve reasoning or design rationale</trigger>
 <rule>Load the design context template from references/design-context-template.xml. Fill only the sections that are relevant — leave unused sections empty or omit them.</rule>
 <rule>Do NOT include the full interview transcript, raw conversation dumps, chain-of-thought traces, or repetitive restatements of spec.xml content.</rule>
-<rule>Save design-context.xml as a sibling of spec.xml in the same spec package directory: .vvoc/specs/&lt;id&gt;/design-context.xml</rule>
+<rule>Save design-context.xml as a sibling of spec.xml in the same date-prefixed spec package directory: .vvoc/specs/&lt;id&gt;/design-context.xml</rule>
 </design_context>
 
 <self_review>
@@ -98,6 +98,6 @@ UX cues (roadmap, progress markers, depth estimates, checkpoints) are TRANSPAREN
 </handoff>
 
 <task>
-Your current task is the ongoing user request. Walk the decision tree relentlessly — one branch at a time. Propose approaches, present a design section by section, get approval at each stage. Load the spec template from references/spec-template.xml and fill every element with confirmed decisions. Save to .vvoc/specs/&lt;id&gt;/spec.xml as XML with document status draft. Optionally create .vvoc/specs/&lt;id&gt;/design-context.xml for complex sessions. After explicit user approval, update the saved spec status to approved. Stop before any implementation or planning.
+Your current task is the ongoing user request. Walk the decision tree relentlessly — one branch at a time. Propose approaches, present a design section by section, get approval at each stage. Load the spec template from references/spec-template.xml and fill every element with confirmed decisions. Save to .vvoc/specs/&lt;id&gt;/spec.xml, where &lt;id&gt; is YYYY-MM-DD-&lt;slug&gt; using the current date at spec creation time, as XML with document status draft. Optionally create .vvoc/specs/&lt;id&gt;/design-context.xml for complex sessions. After explicit user approval, update the saved spec status to approved. Stop before any implementation or planning.
 </task>
 </skill>