setspec 0.3.0__tar.gz → 0.4.0__tar.gz

{setspec-0.3.0 → setspec-0.4.0}/CHANGELOG.md

@@ -7,6 +7,44 @@ packaging and release standards §3.
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-08-29
+
+### Added
+
+- **`setspec.prompts`** (Phase 5): prompt records and prompt packs, moved from
+  `freeweight.services.prompts` — `PromptRecord`, `PromptLibrary`, `load_record()`, `load_pack()`,
+  `build_manifest()`/`write_manifest()`, and the pack's three hashes
+  (`prompt_record_hash`/`prompt_subset_hash`/`pack_hash`, ADR-0028). Rendering runs through a
+  sandboxed, loader-less Jinja2 `Environment` with `StrictUndefined` (prompt-management-standards
+  §2.1): a referenced-but-unsupplied variable is an error, a template cannot reach the filesystem,
+  and dunder attribute access is refused. `load_pack()`'s `root` parameter is required — the
+  package carries no opinion about an application's pack layout; an application wanting a default
+  location supplies its own thin wrapper (FreeWeight's `freeweight.services.prompts.load_pack`
+  keeps its old default this way).
+
+  FreeWeight's own prompt pack adopts this module in the same change (pulling its P12 forward):
+  `freeweight.services.prompts` is now a re-export shim over `setspec.prompts`, verified to
+  produce a byte-identical `pack_hash` and per-record hash for every shipped prompt before and
+  after the move, with FreeWeight's own gate green afterwards. Two applications reading the same
+  pack format from two processes is the scenario ADR-0028's hashes exist for; the FreeWeight move
+  is the first proof of it.
+
+- **JSON Schema for `prompt.record` and `prompt.manifest`**, committed as package data under
+  `setspec/schemas/prompt.record/1.0.json` and `setspec/schemas/prompt.manifest/1.0.json`, with
+  golden examples under `setspec/goldens/prompt.{record,manifest}/1.0/{full,minimal}.json`. Both
+  are hand-authored rather than generated: `PromptRecord` is a plain dataclass, not a pydantic
+  envelope payload — a prompt record is a pack file on disk, never wrapped in a `SchemaEnvelope` —
+  so neither schema is registered in `PUBLISHED_SCHEMAS`/reachable through `json_schema_for()`,
+  and the goldens are illustrative examples rather than inputs to the envelope contract-test
+  matrix in `tests/contract/test_goldens.py`. Every golden round-trips through the real
+  `load_pack()` loader (not just schema validation) and its `pack_sha256` is the module's own
+  computed hash, not a hand-typed value.
+
+### Changed
+
+- Bumped to 0.4.0 for the `setspec.prompts` addition (packaging standards §3: additive,
+  non-breaking).
+
 ## [0.3.0] — 2026-08-28
 
 ### Added

{setspec-0.3.0 → setspec-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: setspec
-Version: 0.3.0
+Version: 0.4.0
 Summary: Every versioned data contract that crosses an application boundary: benchmark results, capability evidence, event/error envelopes, prompt records.
 Project-URL: Homepage, https://github.com/JPKell/SetSpec
 Project-URL: Documentation, https://github.com/JPKell/SetSpec/tree/main/docs

setspec-0.4.0/docs/prompts-adoption-checklist.md

@@ -0,0 +1,86 @@
+# `setspec.prompts` Adoption Checklist
+
+For an application that owns a prompt pack today (its own `PromptRecord`/`load_pack`-shaped code,
+or an equivalent) and wants to move onto `setspec.prompts` instead of maintaining a second copy of
+prompt-record loading, hashing and rendering. Written against the first adopter, FreeWeight P12
+(§5 below is that migration, completed); the steps are what the *next* adopter — IdeaPress or
+LoadCoach, whichever writes its first prompt pack second — should follow.
+
+## 1. What to delete outright
+
+Anything that duplicates, byte-for-byte in behaviour, what `setspec.prompts` now provides:
+`PromptRecord`/`VariableSpec`/`RenderedPrompt`/`PromptReference`/`PromptLibrary`, `load_record()`,
+`load_pack()`, `build_manifest()`/`write_manifest()`, `prompt_record_hash()`/`prompt_subset_hash()`/
+`pack_hash()`, and the sandboxed `StrictUndefined` Jinja2 environment. If your pack format matches
+prompt-management-standards §2.1–§3 (schema_version/prompt_id/version/template/purpose/metadata,
+a manifest with pack_id/pack_version/prompts/pack_sha256), there should be nothing left to keep.
+
+## 2. The one thing every adopter supplies itself: pack location
+
+`load_pack(root: Path, *, override_root: Path | None = None)` takes `root` as a required
+positional argument — the package has no opinion about where an application's pack lives on disk,
+and no default. If your call sites currently call a zero-argument `load_pack()`, write a one-line
+wrapper in your own package that supplies your pack's fixed location and forwards everything else:
+
+```python
+from pathlib import Path
+from setspec.prompts import load_pack as _setspec_load_pack, PromptLibrary
+
+PACK_ROOT = Path(__file__).resolve().parent.parent / "prompts"
+
+def load_pack(root: Path = PACK_ROOT, *, override_root: Path | None = None) -> PromptLibrary:
+    return _setspec_load_pack(root, override_root=override_root)
+```
+
+Do this even if every current call site could be edited to pass `root` explicitly — a re-export
+shim at your old import path means the migration touches one file instead of every call site, and
+is the difference between a multi-file diff and a four-file one (§5).
+
+## 3. Behaviour to re-verify, not assume
+
+* **Hashing is over `canonical_json`, not file bytes.** If you ever hashed a record file's raw
+  bytes, that is not the same value `prompt_record_hash()` produces; re-indenting a file must not
+  change its hash, and canonical-JSON hashing already guarantees that here.
+* **Declared-and-unused is a load-time error, same as undeclared-and-used.** A variable in the
+  record's `variables` block that the template never references fails validation — not just the
+  reverse. Audit existing records for this before the first `load_pack()` call in CI.
+  See [`goldens/prompt.record/1.0/full.json`](../src/setspec/goldens/prompt.record/1.0/full.json)
+  for a record where every declared variable — including a non-string one with `min`/`max` — is
+  used in the template.
+* **The Jinja2 environment has no loader.** `{% include %}` / `{% extends %}` fail at render time
+  (`PromptRenderError`), not load time — a template that used either against your old environment
+  needs rewriting, not just re-pointing.
+* **`pack_hash()` is provenance, never a fingerprint input** (ADR-0028 §1). If your evidence
+  payloads folded a pack-wide hash into a capability fingerprint, stop — only
+  `prompt_subset_hash()` over the *specific prompts a benchmark declares* belongs there.
+
+## 4. Tests that must still pass, unchanged
+
+Whatever exercises your prompt pack today — rendering determinism, unknown-variable rejection,
+sandboxing (no filesystem reach, no dunder attribute access from a template) — should still pass
+against `setspec.prompts` with no change to the test's assertions, only to its imports. A test that
+needed a new assertion to pass found a real behaviour difference; treat that as a bug to resolve,
+not a test to relax, before shipping the migration.
+
+## 5. Verification: FreeWeight P12 (completed)
+
+FreeWeight adopted `setspec.prompts` in the same change that added it to `setspec` (Phase 5 pulled
+FreeWeight's own P12 forward, rather than leaving `setspec.prompts` unused until a later phase).
+The proof this checklist rests on:
+
+1. **Before**: captured the pack hash and every individual record hash from FreeWeight's original,
+   pre-migration `freeweight.services.prompts` — `pack_hash: sha256:b1b0ffd0a5941fee5e0013d2a826732ea02a285b229bdc006ebd6dd25ff4ceb4`
+   plus 18 individual record hashes spanning `benchmarks.agent.goal` through `goals.judge.rubric`.
+2. **After, direct**: loaded the same pack through `setspec.prompts.load_pack()` directly and
+   recomputed every hash — identical.
+3. **After, through the shim**: rewrote `freeweight/services/prompts.py` as a thin re-export over
+   `setspec.prompts` (§2's pattern, `PACK_ROOT` default preserved) and recomputed through
+   FreeWeight's own public import path — identical again.
+4. **Full gate, unchanged**: FreeWeight's complete pre-PR gate (ruff, mypy strict over 265 files,
+   import-linter, pytest) passed with no test assertions changed — 2297 passed, 28 skipped, 21
+   deselected (performance). The only non-shim source edit was 3 import statements in
+   `tests/security/test_goal_pack_import.py`, which reached into the module's private
+   `_environment()` directly for a sandboxing assertion; every other call site needed no change.
+
+Final diff: 4 files changed. The next adopter should expect a diff of similar shape — one shim
+file, a dependency bump, and an edit only where a test reached past the public API.

{setspec-0.3.0 → setspec-0.4.0}/src/setspec/__about__.py

@@ -1,3 +1,3 @@
 """Single source of the package version, read by hatchling at build time."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

setspec-0.4.0/src/setspec/goldens/prompt.manifest/1.0/full.json

@@ -0,0 +1,19 @@
+{
+  "pack_id": "freeweight.core",
+  "pack_version": "1.4.0",
+  "schema_version": "1.0",
+  "generated_at": "2026-08-21T00:00:00Z",
+  "prompts": [
+    {
+      "prompt_id": "stages.draft.article",
+      "version": "2.1.0",
+      "sha256": "sha256:2316b1ae73d0298e17a78677e2da9fd5f0b664ae09cc3dd7625f26921a9630c5"
+    },
+    {
+      "prompt_id": "stages.notify.digest",
+      "version": "1.0.0",
+      "sha256": "sha256:21829b05324468ff96ddb14ea45d4ca3a3409c4d0928f1475089aa0467c276a0"
+    }
+  ],
+  "pack_sha256": "sha256:39e13d67c588be76c08d82073e8de6953c73974740d1ceedf1d66394d5e4efef"
+}

setspec-0.4.0/src/setspec/goldens/prompt.manifest/1.0/minimal.json

@@ -0,0 +1,14 @@
+{
+  "pack_id": "ideapress.core",
+  "pack_version": "1.0.0",
+  "schema_version": "1.0",
+  "generated_at": "1970-01-01T00:00:00Z",
+  "prompts": [
+    {
+      "prompt_id": "stages.notify.digest",
+      "version": "1.0.0",
+      "sha256": "sha256:21829b05324468ff96ddb14ea45d4ca3a3409c4d0928f1475089aa0467c276a0"
+    }
+  ],
+  "pack_sha256": "sha256:2f0a1d2047e54d2dac5da63af4ee49a5e50c6bf931af9fe105374f73c89f6e7f"
+}

setspec-0.4.0/src/setspec/goldens/prompt.record/1.0/full.json

@@ -0,0 +1,54 @@
+{
+  "schema_version": "1.0",
+  "prompt_id": "stages.draft.article",
+  "version": "2.1.0",
+  "purpose": "Produce a first draft of one article section from a compiled requirement set.",
+  "system": "You are drafting one section of an article. Follow every hard requirement.",
+  "template": "SECTION: {{ section_title }}\n\nREQUIREMENTS\n{{ requirements_json }}\n\nCONTEXT\n{{ context }}\n\nWrite roughly {{ word_target }} words.",
+  "variables": {
+    "section_title": {
+      "type": "string",
+      "required": true,
+      "description": "Human-readable section title"
+    },
+    "requirements_json": {
+      "type": "string",
+      "required": true,
+      "description": "Canonical JSON of compiled requirements"
+    },
+    "context": {
+      "type": "string",
+      "required": false,
+      "default": "",
+      "description": "Bounded prior context"
+    },
+    "word_target": {
+      "type": "integer",
+      "required": false,
+      "default": 800,
+      "min": 100,
+      "max": 5000,
+      "description": "Target word count for the drafted section"
+    }
+  },
+  "task": "content.article_draft",
+  "capability": "creative_writing",
+  "response": {
+    "format": "text",
+    "json_schema_ref": null,
+    "expectations": ["No headings above H3", "No meta-commentary about being an AI"]
+  },
+  "model_requirements": {
+    "min_context_tokens": 8192,
+    "requires_capabilities": [],
+    "recommended_temperature": 0.7
+  },
+  "metadata": {
+    "author": "suite",
+    "created_at": "2026-08-21T00:00:00Z",
+    "changed_at": "2026-08-21T00:00:00Z",
+    "change_reason": "Tightened the requirement-compliance instruction after audit-pass regressions.",
+    "supersedes": "2.0.0",
+    "tags": ["content", "draft"]
+  }
+}

setspec-0.4.0/src/setspec/goldens/prompt.record/1.0/minimal.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": "1.0",
+  "prompt_id": "stages.notify.digest",
+  "version": "1.0.0",
+  "purpose": "Static prompt with no variables, exercising the record format's floor.",
+  "template": "Summarize today's queue in three bullet points.",
+  "metadata": {
+    "change_reason": "Initial version."
+  }
+}