@jaimevalasek/aioson 1.8.0 → 1.9.1

package/template/.aioson/docs/product/quality-lens.md

@@ -1,57 +1,57 @@
----
-description: "Product quality lens — strong patterns, anti-pattern replacements, and a compact scorecard for higher-quality PRDs."
----
-
-# Product Quality Lens
-
-Load this module before writing or updating any PRD.
-
-## Positive patterns
-
-High-quality product output usually does all of this:
-
-- names a specific user and a specific pain instead of a generic audience
-- shows the tension behind the first release: what matters now and what is deliberately deferred
-- captures edge cases, empty states, permissions, and failure behavior early
-- explains why this product should be chosen instead of a generic alternative
-- leaves downstream agents with decisions they can execute, not vague aspirations
-- preserves visual ambition when visual quality changes the product outcome
-
-## Anti-patterns and replacements
-
-| Anti-pattern | Replace with |
-|---|---|
-| Generic SaaS PRD that could fit any startup | A PRD with domain nouns, real user moments, and explicit constraints |
-| Feature list without decision tension | A scoped first release with clear deferrals |
-| User story with no operator or owner | Named roles, ownership, and state transitions |
-| Competitive claim with no evidence | Research-backed differentiation or explicit uncertainty |
-| Beautiful-product language with no design bar | A concrete `## Visual identity` direction or `pending-selection` |
-
-## Elevation moves
-
-Before finalizing, force at least one improvement from each category:
-
-- sharpen the user/problem statement
-- sharpen the scope boundary
-- sharpen one risk or edge case
-- sharpen one differentiator or positioning detail
-
-## Review scorecard
-
-Score the PRD from `1-5` on:
-
-- specificity
-- differentiation
-- scope discipline
-- downstream usefulness
-- operational realism
-
-If any score is `3` or lower, revise before finalizing.
-
-## Final pass
-
-Ask silently:
-
-- Would this still read as strong if the product name were removed?
-- Does at least one section prove the product is not a template clone?
-- Can `@analyst`, `@ux-ui`, and `@dev` act on this without guessing core intent?
+---
+description: "Product quality lens — strong patterns, anti-pattern replacements, and a compact scorecard for higher-quality PRDs."
+---
+
+# Product Quality Lens
+
+Load this module before writing or updating any PRD.
+
+## Positive patterns
+
+High-quality product output usually does all of this:
+
+- names a specific user and a specific pain instead of a generic audience
+- shows the tension behind the first release: what matters now and what is deliberately deferred
+- captures edge cases, empty states, permissions, and failure behavior early
+- explains why this product should be chosen instead of a generic alternative
+- leaves downstream agents with decisions they can execute, not vague aspirations
+- preserves visual ambition when visual quality changes the product outcome
+
+## Anti-patterns and replacements
+
+| Anti-pattern | Replace with |
+|---|---|
+| Generic SaaS PRD that could fit any startup | A PRD with domain nouns, real user moments, and explicit constraints |
+| Feature list without decision tension | A scoped first release with clear deferrals |
+| User story with no operator or owner | Named roles, ownership, and state transitions |
+| Competitive claim with no evidence | Research-backed differentiation or explicit uncertainty |
+| Beautiful-product language with no design bar | A concrete `## Visual identity` direction or `pending-selection` |
+
+## Elevation moves
+
+Before finalizing, force at least one improvement from each category:
+
+- sharpen the user/problem statement
+- sharpen the scope boundary
+- sharpen one risk or edge case
+- sharpen one differentiator or positioning detail
+
+## Review scorecard
+
+Score the PRD from `1-5` on:
+
+- specificity
+- differentiation
+- scope discipline
+- downstream usefulness
+- operational realism
+
+If any score is `3` or lower, revise before finalizing.
+
+## Final pass
+
+Ask silently:
+
+- Would this still read as strong if the product name were removed?
+- Does at least one section prove the product is not a template clone?
+- Can `@analyst`, `@ux-ui`, and `@dev` act on this without guessing core intent?

package/template/.aioson/docs/product/research-loop.md

@@ -1,65 +1,65 @@
----
-description: "Product research loop — extract short keyword phrases, consult research cache, search fresh sources, and fold the findings back into the PRD conversation."
----
-
-# Product Research Loop
-
-Load this module before the first synthesis, before any finalize decision, and before writing a non-trivial PRD.
-
-## Goal
-
-Prevent `@product` from relying only on the chat. Use a lightweight, fresh external evidence pass to sharpen questions, differentiate the PRD, and avoid generic product output.
-
-## Mandatory keyword extraction
-
-Derive `3-7` short keyword phrases from the current conversation. Favor concrete phrases with `2-6` words such as:
-
-- problem or pain point
-- user segment or buyer
-- workflow or operating motion
-- business model or pricing shape
-- trust, compliance, or risk concern
-- differentiation claim
-- visual or experience cue when it changes the product
-
-Good phrases are specific and searchable:
-
-- `ai intake form`
-- `b2b onboarding checklist`
-- `field service scheduling`
-- `subscription upgrade friction`
-
-Avoid broad phrases such as `app idea`, `dashboard`, or `better ux`.
-
-## Mandatory scouting pass
-
-1. Load `.aioson/skills/static/web-research-cache.md`
-2. Rank the extracted phrases by:
-   - freshness sensitivity
-   - product impact
-   - likelihood of improving the PRD
-3. Check the cache first for the top phrases
-4. Reuse fresh cache entries when they are less than 7 days old
-5. Search only the top `1-4` phrases that are stale or missing
-6. Save every search to `researchs/` before using the result
-
-At least one phrase must be validated through cache or fresh research whenever the PRD depends on an external market, product pattern, pricing model, competitor norm, compliance expectation, or time-sensitive UX convention.
-
-## How to use the findings
-
-Use research to:
-
-- ask sharper follow-up questions
-- surface missing constraints or edge cases
-- challenge commodity positioning
-- strengthen differentiation and first-release scope
-- improve acceptance of what should stay `TBD`
-
-Do not dump research into the chat. Surface only the deltas that materially change the product conversation.
-
-## Output discipline
-
-- Treat `researchs/` as a temporary shared evidence layer for current and nearby sessions
-- Mark inferred conclusions as inference, not as sourced fact
-- Never replace user confirmation with internet research
-- Never force a PRD rewrite because research exists; use it to improve judgment and questions
+---
+description: "Product research loop — extract short keyword phrases, consult research cache, search fresh sources, and fold the findings back into the PRD conversation."
+---
+
+# Product Research Loop
+
+Load this module before the first synthesis, before any finalize decision, and before writing a non-trivial PRD.
+
+## Goal
+
+Prevent `@product` from relying only on the chat. Use a lightweight, fresh external evidence pass to sharpen questions, differentiate the PRD, and avoid generic product output.
+
+## Mandatory keyword extraction
+
+Derive `3-7` short keyword phrases from the current conversation. Favor concrete phrases with `2-6` words such as:
+
+- problem or pain point
+- user segment or buyer
+- workflow or operating motion
+- business model or pricing shape
+- trust, compliance, or risk concern
+- differentiation claim
+- visual or experience cue when it changes the product
+
+Good phrases are specific and searchable:
+
+- `ai intake form`
+- `b2b onboarding checklist`
+- `field service scheduling`
+- `subscription upgrade friction`
+
+Avoid broad phrases such as `app idea`, `dashboard`, or `better ux`.
+
+## Mandatory scouting pass
+
+1. Load `.aioson/skills/static/web-research-cache.md`
+2. Rank the extracted phrases by:
+   - freshness sensitivity
+   - product impact
+   - likelihood of improving the PRD
+3. Check the cache first for the top phrases
+4. Reuse fresh cache entries when they are less than 7 days old
+5. Search only the top `1-4` phrases that are stale or missing
+6. Save every search to `researchs/` before using the result
+
+At least one phrase must be validated through cache or fresh research whenever the PRD depends on an external market, product pattern, pricing model, competitor norm, compliance expectation, or time-sensitive UX convention.
+
+## How to use the findings
+
+Use research to:
+
+- ask sharper follow-up questions
+- surface missing constraints or edge cases
+- challenge commodity positioning
+- strengthen differentiation and first-release scope
+- improve acceptance of what should stay `TBD`
+
+Do not dump research into the chat. Surface only the deltas that materially change the product conversation.
+
+## Output discipline
+
+- Treat `researchs/` as a temporary shared evidence layer for current and nearby sessions
+- Mark inferred conclusions as inference, not as sourced fact
+- Never replace user confirmation with internet research
+- Never force a PRD rewrite because research exists; use it to improve judgment and questions

package/template/.aioson/docs/sheldon/enrichment-paths.md

@@ -1,134 +1,134 @@
----
-description: "Sheldon enrichment paths — gap analysis dimensions, sizing, in-place vs phased plan outputs, enrichment log, and handoff."
----
-
-# Sheldon Enrichment Paths
-
-Load this module after source consolidation and before writing any enrichment output.
-
-## Gap analysis dimensions
-
-Analyze the PRD for:
-
-- missing requirements
-- edge cases
-- vague or absent acceptance criteria
-- unresolved technical decisions
-- unmapped external dependencies
-- incomplete user flows
-- internal contradictions
-
-Show improvements grouped by:
-
-- critical gaps
-- important improvements
-- refinements
-
-The user must choose which improvements to apply before you write anything.
-
-## Sizing decision
-
-Score the enriched scope using:
-
-| Criterion | Weight |
-|---|---|
-| Main entities above 3 | +1 each |
-| Distinct delivery phases above 1 | +2 each |
-| External integrations | +1 each |
-| User flows above 3 | +1 each |
-| AC complexity above 10 | +1 |
-
-Decision thresholds:
-
-- `0–3` → enrich PRD in place
-- `4–6` → enrich PRD in place and add `## Delivery plan`
-- `7+` → create external phased plan in `.aioson/plans/{slug}/`
-
-Present the decision and justification before creating any files.
-
-## Path A — In-place enrichment
-
-For scores `0–6`:
-
-- expand existing sections
-- add missing sections when needed
-- never remove existing content
-- never rewrite `Vision`, `Problem`, or `Users`
-- mark Sheldon-added content with `_(sheldon)_`
-
-For scores `4–6`, add `## Delivery plan` with numbered phases inside the PRD.
-
-Also add or update:
-
-- `## Reference sources (sheldon)`
-
-## Path B — External phased plan
-
-For scores `7+`, create:
-
-- `.aioson/plans/{slug}/manifest.md`
-- `.aioson/plans/{slug}/plan-{phase-slug}.md`
-
-Rules:
-
-- create `manifest.md` first
-- phase slugs must be descriptive
-- phases must be independently implementable
-- phase ACs must be independently verifiable
-- pre-made decisions are final
-- deferred decisions must state who decides and when
-
-## `manifest.md`
-
-Include:
-
-- target PRD
-- Sheldon version
-- created date
-- status
-- overview
-- phase table
-- pre-made decisions
-- deferred decisions
-- reference sources
-
-## `plan-{phase-slug}.md`
-
-Each phase file should include:
-
-- scope
-- new or modified entities
-- user flows covered
-- acceptance criteria
-- implementation sequence
-- external dependencies
-- notes for `@dev`
-- notes for `@qa`
-- phase-specific reference sources
-
-## Enrichment log
-
-Create or update `.aioson/context/sheldon-enrichment.md` at the end of every session.
-
-It must track:
-
-- target PRD
-- enrichment round count
-- last enrichment date
-- plan path or `null`
-- sizing score
-- sizing decision
-- sources used
-- improvements applied
-- improvements discarded
-
-## Handoff
-
-If enrichment stayed in-place:
-
-- tell the user to activate `@analyst`
-
-If an external phased plan was created:
-
-- tell the user where `manifest.md` lives
-- tell them to activate `@analyst`
+---
+description: "Sheldon enrichment paths — gap analysis dimensions, sizing, in-place vs phased plan outputs, enrichment log, and handoff."
+---
+
+# Sheldon Enrichment Paths
+
+Load this module after source consolidation and before writing any enrichment output.
+
+## Gap analysis dimensions
+
+Analyze the PRD for:
+
+- missing requirements
+- edge cases
+- vague or absent acceptance criteria
+- unresolved technical decisions
+- unmapped external dependencies
+- incomplete user flows
+- internal contradictions
+
+Show improvements grouped by:
+
+- critical gaps
+- important improvements
+- refinements
+
+The user must choose which improvements to apply before you write anything.
+
+## Sizing decision
+
+Score the enriched scope using:
+
+| Criterion | Weight |
+|---|---|
+| Main entities above 3 | +1 each |
+| Distinct delivery phases above 1 | +2 each |
+| External integrations | +1 each |
+| User flows above 3 | +1 each |
+| AC complexity above 10 | +1 |
+
+Decision thresholds:
+
+- `0–3` → enrich PRD in place
+- `4–6` → enrich PRD in place and add `## Delivery plan`
+- `7+` → create external phased plan in `.aioson/plans/{slug}/`
+
+Present the decision and justification before creating any files.
+
+## Path A — In-place enrichment
+
+For scores `0–6`:
+
+- expand existing sections
+- add missing sections when needed
+- never remove existing content
+- never rewrite `Vision`, `Problem`, or `Users`
+- mark Sheldon-added content with `_(sheldon)_`
+
+For scores `4–6`, add `## Delivery plan` with numbered phases inside the PRD.
+
+Also add or update:
+
+- `## Reference sources (sheldon)`
+
+## Path B — External phased plan
+
+For scores `7+`, create:
+
+- `.aioson/plans/{slug}/manifest.md`
+- `.aioson/plans/{slug}/plan-{phase-slug}.md`
+
+Rules:
+
+- create `manifest.md` first
+- phase slugs must be descriptive
+- phases must be independently implementable
+- phase ACs must be independently verifiable
+- pre-made decisions are final
+- deferred decisions must state who decides and when
+
+## `manifest.md`
+
+Include:
+
+- target PRD
+- Sheldon version
+- created date
+- status
+- overview
+- phase table
+- pre-made decisions
+- deferred decisions
+- reference sources
+
+## `plan-{phase-slug}.md`
+
+Each phase file should include:
+
+- scope
+- new or modified entities
+- user flows covered
+- acceptance criteria
+- implementation sequence
+- external dependencies
+- notes for `@dev`
+- notes for `@qa`
+- phase-specific reference sources
+
+## Enrichment log
+
+Create or update `.aioson/context/sheldon-enrichment.md` at the end of every session.
+
+It must track:
+
+- target PRD
+- enrichment round count
+- last enrichment date
+- plan path or `null`
+- sizing score
+- sizing decision
+- sources used
+- improvements applied
+- improvements discarded
+
+## Handoff
+
+If enrichment stayed in-place:
+
+- tell the user to activate `@analyst`
+
+If an external phased plan was created:
+
+- tell the user where `manifest.md` lives
+- tell them to activate `@analyst`

package/template/.aioson/docs/sheldon/harness-contract.md

@@ -0,0 +1,118 @@
+---
+description: "Sheldon harness contract generation procedure — schemas, criteria population, governor and contract_mode selection, MICRO/SMALL/MEDIUM rules."
+---
+
+# Sheldon Harness Contract Generation
+
+Load this module when `@sheldon` reaches RF-05 in a MEDIUM enrichment. Implements AC-HD-06 of `harness-driven-aioson`.
+
+## When to run
+
+Run **after** writing `sheldon-enrichment-{slug}.md`, gated by `project.context.md` classification:
+
+| Classification | Action |
+|---|---|
+| MICRO | Skip entirely. No contract, no progress.json. |
+| SMALL | Produce `progress.json` only (no `harness-contract.json`). |
+| MEDIUM | Produce both `harness-contract.json` and `progress.json`. |
+
+## Steps
+
+### 1. Initialize stub
+
+If `.aioson/plans/{slug}/harness-contract.json` is absent:
+
+```bash
+aioson harness:init . --slug={slug}
+```
+
+This creates the contract scaffold and `progress.json` in the same folder. If the CLI command is unavailable, write both files manually using the canonical schemas at the bottom of this doc.
+
+### 2. Populate `criteria[]`
+
+For every AC in the enriched PRD with an objective, mechanically verifiable assertion (file existence, test pass, lint clean, exact API shape, exit code), append to `criteria[]`:
+
+```json
+{
+  "id": "C1",
+  "description": "<AC text — human-readable for PR review>",
+  "assertion": "<machine-verifiable expression — e.g. 'tests/foo.test.js passes' or 'src/x/y.js exports parseX'>",
+  "binary": true
+}
+```
+
+ACs that are subjective (UX feel, code style preference) get `binary: false` and become advisory only — `@validator` ignores them in the score.
+
+**Rule of thumb:** if the assertion can be answered by a single shell command exit code or a single test, it qualifies as `binary: true`. Otherwise mark it advisory and let `@qa` cover it.
+
+### 3. Set `contract_mode`
+
+By classification and risk surface:
+
+- **SMALL** → `ECONOMICAL` (relaxed governor)
+- **MEDIUM (default)** → `BALANCED`
+- **MEDIUM with sensitive surface** (auth, money, ownership, secrets, uploads, external URLs) → `URGENT` (tight governor)
+
+### 4. Set `governor` block
+
+Safe defaults for `BALANCED`:
+
+```json
+{ "max_steps": 50, "cost_ceiling_usd": 2.00, "error_streak_limit": 5 }
+```
+
+- `URGENT` halves these.
+- `ECONOMICAL` doubles `error_streak_limit` only.
+
+## Authoring rules
+
+- The contract is **additive** to the enrichment log; both coexist. Enrichment explains *what* to enrich; contract defines *what "done" means*.
+- Contract criteria are derived from the **enriched** PRD ACs — never invent criteria not anchored to an AC.
+- Mention the contract path in the post-enrichment handoff message.
+- The user approves the contract as part of the post-enrichment gate. Do not declare the contract final without confirmation.
+- Once approved, the contract is the source of truth for `@validator`. Subsequent enrichment rounds may add new criteria, never remove approved ones without explicit user instruction.
+
+## Canonical schemas
+
+### `harness-contract.json`
+
+```json
+{
+  "feature": "<slug>",
+  "contract_mode": "ECONOMICAL | BALANCED | URGENT",
+  "governor": {
+    "max_steps": 50,
+    "cost_ceiling_usd": 2.00,
+    "error_streak_limit": 5
+  },
+  "criteria": [
+    {
+      "id": "C1",
+      "description": "...",
+      "assertion": "...",
+      "binary": true
+    }
+  ]
+}
+```
+
+### `progress.json`
+
+```json
+{
+  "feature": "<slug>",
+  "phase": 1,
+  "status": "in_progress | waiting_validation | done | circuit_open",
+  "completed_steps": [],
+  "last_error": null,
+  "session_count": 1,
+  "last_updated": "<ISO-8601>",
+  "circuit_state": "CLOSED | OPEN | HALF_OPEN"
+}
+```
+
+## Failure modes to anticipate
+
+- **No verifiable ACs in PRD** — go back to enrichment with `@product` and add concrete assertions before generating a contract.
+- **All ACs are advisory** — flag to user; the harness adds no value. Skip contract generation, document the decision in `sheldon-enrichment-{slug}.md`.
+- **`harness:init` CLI missing** — write stubs manually, but record in handoff that CLI was unavailable so `@dev` can install it.