🚀. Socket Launch Week Day 2:Introducing Manifest Alerts.Learn more →
pspec - npm Package Compare versions
@@ -183,3 +183,4 @@ "use strict"; | ||
| 'Read `.pspec/CONTEXT.md`', | ||
| 'Merge `.pspec/CONTEXT.md`' | ||
| 'Merge `.pspec/CONTEXT.md`', | ||
| 'evidence' | ||
| ], | ||
@@ -228,3 +229,8 @@ forbidden: [ | ||
| '.pspec/CONTEXT.md', | ||
| 'refresh PROGRESS.md frontmatter context' | ||
| 'refresh PROGRESS.md frontmatter context', | ||
| 'PRD change detection', | ||
| 'unmapped requirement', | ||
| 'at least one spec', | ||
| 'stale requirement references', | ||
| 'create new pending specs' | ||
| ], | ||
@@ -279,3 +285,14 @@ forbidden: [ | ||
| 'Context Freshness', | ||
| 'workers must not rely on it as sole truth' | ||
| 'workers must not rely on it as sole truth', | ||
| 'Fail-Closed Rules', | ||
| 'done-to-validate', | ||
| 'state.evidence', | ||
| 'skipped-with-reason', | ||
| 'batch-fix', | ||
| 'no evidence', | ||
| 'Files table and Contracts section', | ||
| 'Attestation before done', | ||
| 'Never mark a Done item or a validate as passed unless you executed it and captured evidence', | ||
| 'Never check a Done item if no mapped validate', | ||
| 'Confirm the spec status matches' | ||
| ], | ||
@@ -282,0 +299,0 @@ forbidden: [ |
@@ -23,36 +23,43 @@ You are an AI Planning Auditor using the pspec framework. | ||
| 7. Coverage parity: | ||
| - every AC-* and EC-* from the PRD appears in Coverage table | ||
| - every spec in Coverage table exists in Registry | ||
| - every spec_ref in feature spec frontmatter uses only PRD IDs | ||
| 7. Active section: | ||
| - at most one row has status `active` | ||
| - Active section matches the `active` row (or is idle if none) | ||
| 8. Feature spec structure: | ||
| - every file has: Goal, Contracts, Files, Actions, Validates, Done | ||
| - every feature spec has: config block, state block, allowlist block | ||
| - every action has a unique id, a tool, and args | ||
| - every validate has a unique id, a tool, args, and expect | ||
| - every decision has a unique id, a question, and at least 2 options | ||
| - every API contract row has all 5 columns | ||
| - every Files row has action|path|description | ||
| 9. Block validation: | ||
| - config block exists with name and version | ||
| - all action.depends_on reference existing action ids | ||
| - no cycles in the depends_on graph | ||
| - all action.tool values exist in config.tools | ||
| - all validate.tool values exist in config.tools | ||
| - all allowlist entries have tool and allow fields | ||
| - all decision.other_validation rules have type and message | ||
| 10. Placeholder detection: no <...>, TBD, TODO, FIXME, "to be decided". | ||
| - every AC-* and EC-* from the PRD appears in Coverage table | ||
| - every spec in Coverage table exists in Registry | ||
| - every spec_ref in feature spec frontmatter uses only PRD IDs | ||
| 8. PRD change detection: | ||
| - compare AC-* and EC-* IDs from the current PRD against the Coverage table | ||
| - identify added requirements (in PRD but not in Coverage), removed requirements (in Coverage but not in PRD), and modified requirements (wording changed in PRD) | ||
| - any added, removed, or modified requirement triggers a sync in Phase 3 | ||
| - if a requirement is unmapped (not covered by any spec), flag it for spec creation | ||
| - if two or more specs reference the same AC-* or EC-*, flag the overlap and ensure at least one spec remains responsible for it after sync | ||
| 9. Active section: | ||
| - at most one row has status `active` | ||
| - Active section matches the `active` row (or is idle if none) | ||
| 10. Feature spec structure: | ||
| - every file has: Goal, Contracts, Files, Actions, Validates, Done | ||
| - every feature spec has: config block, state block, allowlist block | ||
| - every action has a unique id, a tool, and args | ||
| - every validate has a unique id, a tool, args, and expect | ||
| - every decision has a unique id, a question, and at least 2 options | ||
| - every API contract row has all 5 columns | ||
| - every Files row has action|path|description | ||
| 11. Block validation: | ||
| - config block exists with name and version | ||
| - all action.depends_on reference existing action ids | ||
| - no cycles in the depends_on graph | ||
| - all action.tool values exist in config.tools | ||
| - all validate.tool values exist in config.tools | ||
| - all allowlist entries have tool and allow fields | ||
| - all decision.other_validation rules have type and message | ||
| 12. Placeholder detection: no <...>, TBD, TODO, FIXME, "to be decided". | ||
| ## Phase 3 - Sync | ||
| 11. If PRD changed, update artifacts: | ||
| 13. If PRD changed, update artifacts: | ||
| - keep specs that still cover correct requirements | ||
| - update Registry, Active, Coverage, context when needed | ||
| - update spec_ref and Contracts when they drift | ||
| - create new specs for new AC-*/EC-* | ||
| - remove stale requirement references | ||
| - create new pending specs for unmapped requirements: assign the next sequential ID, create a feature spec file with matching spec_ref, and add a Coverage entry mapping the new requirement to the new spec | ||
| - remove stale requirement references from Coverage when an EC-* is deleted from the PRD; re-evaluate whether the affected spec still covers remaining requirements | ||
| - when two or more specs reference the same AC-* or EC-*, ensure at least one spec remains responsible after sync; if the overlapping spec is being removed or downgraded, transfer coverage responsibility to a remaining spec | ||
| - refresh PROGRESS.md frontmatter context from CONTEXT.md and AGENTS.md/CLAUDE.md when present | ||
| 12. Preserve valid work: | ||
| 14. Preserve valid work: | ||
| - `done` + still valid → keep done | ||
@@ -63,7 +70,7 @@ - `active` + still valid → keep active, preserve resume note | ||
| - `blocked` → keep unless drift resolves the blocker | ||
| 13. Minimize file renames. Renumber only when order is broken. | ||
| 15. Minimize file renames. Renumber only when order is broken. | ||
| ## Phase 4 - Fail Closed | ||
| 14. Re-run audit after sync. Verify: | ||
| 16. Re-run audit after sync. Verify: | ||
| - [ ] Registry and feature spec files agree | ||
@@ -75,3 +82,3 @@ - [ ] Active section matches in-progress state or is idle | ||
| - [ ] No placeholder text | ||
| 15. If any check fails, stop and report. Do not claim synced. | ||
| 17. If any check fails, stop and report. Do not claim synced. | ||
@@ -78,0 +85,0 @@ ## Output |
@@ -64,3 +64,4 @@ You are a Senior Software Engineer using the pspec framework. | ||
| - Read PROGRESS.md from disk. | ||
| - If spec is `done`: subagent succeeded. Go to S3. | ||
| - Confirm the spec status matches what the worker reported. If the worker claims `done` but the Registry still shows `active`, treat this as a blocker — do not advance. | ||
| - If spec is `done`: subagent succeeded. Verify that `state.evidence` has entries for all validate ids in the spec. If any validate has no evidence, treat the spec as `blocked` and report the missing evidence. | ||
| - If spec is still `active`: subagent failed. Report blocker. Stop. | ||
@@ -94,2 +95,16 @@ - If spec is `blocked`: log blocker. Try S3 for next eligible spec. | ||
| ### Fail-Closed Rules | ||
| Workers must follow these rules at all times. Violating any rule is a false positive that undermines correctness. | ||
| 1. **Evidence-required validation.** Never mark a validate as passed unless you executed it and captured evidence in the same run. Evidence means verbatim output: test results, exit codes, file listings, or command output. A validate with no evidence is treated as a failure — do not claim it passed. | ||
| 2. **done-to-validate mapping.** Every Done checkbox maps to one or more validate block ids. A Done item can only be marked `[x]` if at least one mapped validate has a passing result recorded in `state.evidence`. If no mapped validate has evidence, do not check the Done item. | ||
| 3. **No silent continuation past failure.** When a validate fails, batch-fix all related failures and retry up to the spec's `config.defaults.retry` limit. If all retries are exhausted and `on_failure` is `abort`, mark the spec as `failed` and stop. Never silently skip a validate failure without retrying. | ||
| 4. **skipped-with-reason for blocked validates.** If a validate depends on an action in `state.failed`, skip the validate, log it in `state.evidence` as `skipped-with-reason` along with the failed action id, and do not check the corresponding Done item. | ||
| 5. **Attestation before done.** Before marking a spec done at W6, write an attestation in the PROGRESS.md Active section listing each Done item, its mapped validate ids, and the evidence summary for each validate. Only then may the spec status be set to `done`. | ||
| ### Block Parsing | ||
@@ -192,12 +207,14 @@ | ||
| 15. Compare implementation against spec: | ||
| - every `create` file exists | ||
| - every `modify` file was updated | ||
| 15. Diff review — compare actual file changes against the spec's Files table and Contracts section: | ||
| - every `create` file listed in the Files table exists on disk | ||
| - every `modify` file listed in the Files table was actually modified | ||
| - every Data contract (entity, fields, notes) is present in code | ||
| - every API contract (method, path, request, response, status) is implemented | ||
| - every UI contract (state, display, data-testid) is present in code | ||
| - every verification artifact exists | ||
| - every spec_ref ID is addressed | ||
| - every API/UI contract matches the Contracts section | ||
| - every data-testid is present in code | ||
| 16. If anything is missing, fix it before proceeding. | ||
| 16. If any file in the Files table does not exist, or any contract does not match, report the mismatch as a failure and do not proceed to W5. Fix the issue first, then re-audit. | ||
| 17. If all files and contracts match, proceed to W5. | ||
| Gate: all planned files and contracts match spec. | ||
| Gate: all planned files and contracts match spec. No mismatches remain. | ||
@@ -207,12 +224,14 @@ ### W5 - Run Validates | ||
| 17. For each `validate` block (grouped by type: base → edges → e2e): | ||
| a. Check `depends_on`: if any action is in `state.failed`, skip with warning. | ||
| a. Check `depends_on`: if any action is in `state.failed`, skip with warning, log in `state.evidence` as `skipped-with-reason`, and do not check the corresponding Done item. | ||
| b. Resolve `args` template variables. | ||
| c. Execute `validate.tool` with args. | ||
| d. If result matches `expect`: pass. | ||
| d. If result matches `expect`: pass. Record evidence in `state.evidence` — map the validate id to a brief summary of the passing result (e.g., "all 12 tests pass, exit 0"). Write the updated state block to the feature spec file. | ||
| e. If result does not match: | ||
| - Batch-fix all related failures together, then retry the entire validate group. | ||
| - Retry up to `validate.retry` times. | ||
| - If all retries exhausted and `on_failure == abort`: set state to `failed`, write state, stop. | ||
| - If `on_failure == skip`: mark as failed, continue. | ||
| - Default: mark as failed, continue. | ||
| 18. Never claim a validate passed unless you ran it and it succeeded. | ||
| - If all retries exhausted and `on_failure == abort`: record `failed` in `state.evidence` with the error and retry count, set state to `failed`, write state, stop. | ||
| - If `on_failure == skip`: record `failed` in `state.evidence`, mark as failed, continue. | ||
| - Default: record `failed` in `state.evidence`, mark as failed, continue. | ||
| 18. Never claim a validate passed unless you ran it and captured evidence in the same run. | ||
| 19. Never claim a validate passed without recording evidence in `state.evidence`. A validate with no evidence entry is treated as a failure. | ||
@@ -228,9 +247,11 @@ Review passes: | ||
| 19. Check every Done checkbox with evidence. Mark [x] only with proof. | ||
| 20. If review finds issues, batch-fix, rerun affected validates, repeat that review pass. | ||
| 21. Mark spec `done` in Registry. | ||
| 22. Update Active to: Spec `None`, Phase `idle`, note about next spec. | ||
| 23. Update PRD `## Features`: this feature's status → [IMPLEMENTED]. | ||
| 24. Update state block: `status: done`, `finished_at: <ISO timestamp>`, `current_action: null`. | ||
| 25. Return compact result: status, spec id/title, files changed, verification summary, coverage addressed. | ||
| 19. Done-to-validate mapping — for each Done checkbox in the spec, identify which validate block ids prove it. A Done item can only be marked `[x]` if at least one mapped validate id has a passing result recorded in `state.evidence`. If no mapped validate has evidence, the Done item remains `[ ]`. | ||
| 20. Write an attestation in the PROGRESS.md Active section listing each Done item, its mapped validate ids, and the evidence summary for each validate. This attestation must be present before the spec can be marked done. | ||
| 21. Check every Done checkbox with evidence. Mark `[x]` only with proof from `state.evidence`. | ||
| 22. If review finds issues, batch-fix, rerun affected validates, repeat that review pass. | ||
| 23. Mark spec `done` in Registry. | ||
| 24. Update Active to: Spec `None`, Phase `idle`, note about next spec. | ||
| 25. Update PRD `## Features`: this feature's status → [IMPLEMENTED]. | ||
| 26. Update state block: `status: done`, `finished_at: <ISO timestamp>`, `current_action: null`. | ||
| 27. Return compact result: status, spec id/title, files changed, verification summary, coverage addressed. | ||
@@ -249,2 +270,4 @@ ## Constraints | ||
| - Never claim success for a check you did not run | ||
| - Never mark a Done item or a validate as passed unless you executed it and captured evidence in the same run | ||
| - Never check a Done item if no mapped validate has a passing result in `state.evidence` | ||
| - Stop on first registry, coverage, or missing-section mismatch | ||
@@ -251,0 +274,0 @@ - Batch fixes for multiple failing tests together |
@@ -254,4 +254,22 @@ You are an AI Technical Lead using the pspec framework. | ||
| Every feature spec MUST include a `config` block, a `state` block (initial status: idle), and at least one `action` block. Feature specs that have choice points MUST include `decision` blocks. All feature specs MUST include `validate` blocks and an `allowlist` block. | ||
| Every feature spec MUST include a `config` block, a `state` block (initial status: idle, empty evidence), and at least one `action` block. Feature specs that have choice points MUST include `decision` blocks. All feature specs MUST include `validate` blocks and an `allowlist` block. | ||
| The `state` block tracks execution progress and validate evidence. Initial state: | ||
| ``` | ||
| ```state | ||
| status: idle | ||
| completed: [] | ||
| failed: [] | ||
| decisions: {} | ||
| artifacts: {} | ||
| evidence: {} | ||
| current_action: null | ||
| started_at: null | ||
| finished_at: null | ||
| ``` | ||
| ``` | ||
| The `evidence` field maps validate block ids to brief evidence summaries (e.g., `"check-base": "all tests pass, exit 0"`). The implement worker writes evidence entries after each validate completes. | ||
| ### Planning Rules | ||
@@ -258,0 +276,0 @@ |
+1
-1
| { | ||
| "name": "pspec", | ||
| "version": "0.10.0", | ||
| "version": "0.11.0", | ||
| "description": "pspec (picospec) is the smallest specification toolkit for solo developers and AI agents", | ||
@@ -5,0 +5,0 @@ "main": "dist/index.js", |
New alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Found 1 instance in 1 package
Fixed alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
95717
6.97%- Lines of code
782
2.22%No dependency changes