craftassay 0.1.0 → 0.1.1

package/README.md

@@ -18,10 +18,11 @@ The report is an assessment, not a certification.
 ## Review, then decide
 
 Submit a tool, a site, a skill, a spec, or a portfolio. The agent
-writes `report.md` plus a scorecard, findings, and coverage. The
-skill does not edit the source.
+writes a dated run folder with `report.md` plus a scorecard,
+findings, and coverage. The skill does not edit the source.
 
 A later pass with the earlier report attached becomes a comparison.
+It does not overwrite the earlier folder.
 
 ## Install
 
@@ -29,19 +30,21 @@ A later pass with the earlier report attached becomes a comparison.
 pnpm add -D craftassay
 ```
 
-Copy `node_modules/craftassay/skills/craftassay` to
+Copy `node_modules/craftassay/skills/craftassay/` to
 `.cursor/skills/craftassay`. Or skip npm and
-[install the skill](https://craftassay.dev/docs/skill) as a folder.
+[install the skill](https://craftassay.dev/docs/install) as a folder.
 
-Markdown you point an agent at. Nothing scans the tree. v1 has no CLI.
+The package does not run an automatic scanner. The reviewing agent
+may inspect project files you point it at. v1 has no CLI.
 
-## Not Cold-eye
+## CraftAssay and Cold-eye
 
 [Cold-eye](https://coldeye.dev) reviews readiness for a claimed
 first-use path. CraftAssay reviews usefulness, clarity, quality, and
-presentation. [Smell Check](https://smellcheck.dev) reviews unearned
-language. [Detangler](https://detangler.dev) reviews what editing
-tangled.
+presentation, including first-use friction that affects those
+scores. It does not issue a release-readiness verdict.
+[Smell Check](https://smellcheck.dev) reviews unearned language.
+[Detangler](https://detangler.dev) reviews what editing tangled.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "craftassay",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"private": false,
 	"type": "module",
 	"description": "Evidence-backed reviews of usefulness, clarity, quality, and presentation. An agent with the skill writes the report.",

package/skills/craftassay/SKILL.md

@@ -3,7 +3,7 @@ name: craftassay
 description: >-
   Evidence-backed review of usefulness, clarity, quality, and
   presentation. Review or compare a tool, site, skill, spec, or
-  portfolio. Not Cold-eye, line editing, or implementing findings.
+  portfolio. First-use findings stay. Not a readiness verdict.
 ---
 
 # CraftAssay
@@ -11,8 +11,16 @@ description: >-
 You write the review. The subject does not change.
 
 CraftAssay asks how useful, clear, credible, and well-presented the
-work is, and what should improve. Cold-eye asks whether a newcomer
-can use what is presented as ready. Do not run Cold-eye's job here.
+work is, and what should improve. Inspect the discovery-to-first-use
+path when it bears on those seven dimensions. Report missing
+prerequisites, unusable onboarding, and other first-use friction
+when the evidence supports it.
+
+Cold-eye asks whether a newcomer can use what is presented as ready.
+Do not issue a release-readiness verdict. That conclusion is
+Cold-eye's. The two reviews may share evidence. The distinction
+governs the conclusion, not which facts you may record.
+
 You may recommend a Cold-eye pass, or import a supplied Cold-eye
 review as a source. Preserve its version, scope, date, and evidence.
 
@@ -27,23 +35,21 @@ rubric v1.0. If a full spec file is in the repo
 (`craftassay-review-spec-v1.1.md`), read it when a rule here is
 thin. These reference files win for the report shape you emit.
 
-## The hour
+## Review workflow
 
-1. Locate the subject (a project, site, skill, spec, portfolio, or
-   what they pasted). If none, ask. Establish the intended audience
-   and included surfaces before scoring.
-2. `<stem>` is the filename without its last extension.
-   `README.md` → folder `README.craftassay/` next to the file.
-   A folder or system they named → `craftassay/` at that root.
-   A paste with no file → `subject.craftassay/` in the working
-   directory.
+1. Locate the subject (a project, site, skill, spec, portfolio, a
+   URL, or what they pasted). If none, ask. Establish the intended
+   audience and included surfaces before scoring.
+2. Choose a **new run folder**. Follow `references/output.md`.
+   Never write into a folder that already has `report.md`. Never
+   overwrite a supplied baseline.
 3. Follow `references/coverage.md`. Record what you inspected.
    Stop once the evidence is enough for the stated depth.
 4. Write the deliverables using `references/report.md`.
-   Create the folder if needed.
-5. If they attached an earlier CraftAssay review, also follow
-   `references/comparison.md`. Title that report
-   `CraftAssay Comparison: <subject>`.
+   Create the run folder if needed.
+5. If they attached an earlier CraftAssay review, or you found one
+   locally, also follow `references/comparison.md`. Title that
+   report `CraftAssay Comparison: <subject>`.
 6. Hand over the report. Stop. Do not edit the subject. Do not
    write implementation specs unless they asked in a separate
    instruction.
@@ -83,8 +89,10 @@ Do not lower a score only because confidence is lower.
 Read `references/findings.md` before you emit.
 
 Every material finding needs an id, a classification, a surface,
-evidence, a consequence, a priority, and a smallest sufficient
-change. No action → drop it.
+evidence, a consequence, a priority, and either the smallest
+useful correction or a specific verification step. Drop vague
+criticism. Keep a concrete unresolved question when the next
+check is clear. That is what `verify-first` is for.
 
 ## Rules
 
@@ -97,8 +105,9 @@ change. No action → drop it.
 
 ## When to read the reference files
 
+- `references/output.md` — before you choose a folder.
 - `references/report.md` — before you write `report.md`.
 - `references/dimensions.md` — before you assign scores.
 - `references/findings.md` — before you emit a finding.
 - `references/coverage.md` — before you claim what was checked.
-- `references/comparison.md` — when a baseline review is supplied.
+- `references/comparison.md` — when a baseline review exists.

package/skills/craftassay/references/comparison.md

@@ -1,9 +1,12 @@
 # Comparison
 
-Use this file only when an earlier CraftAssay review is supplied.
+Use this file when an earlier CraftAssay review is supplied or
+found locally. Follow `output.md`. Write the comparison into a
+**new** run folder. Do not overwrite the baseline.
 
 1. Retain the original report, date, identities, scores, coverage,
-   and findings. Do not silently rewrite earlier ratings.
+   and findings. Do not silently rewrite earlier ratings. Do not
+   write into the baseline directory.
 2. Inspect current sources and draft the new rationale before
    focusing on numerical deltas.
 3. Record additions, removals, renames, and changed boundaries.

package/skills/craftassay/references/findings.md

@@ -14,7 +14,7 @@ subject_version: null
 confidence: "high | medium | low"
 consequence: "Why this matters to the intended user"
 priority: "P1 | P2 | P3"
-recommended_change: "Smallest sufficient correction"
+recommended_change: "Smallest useful correction, or a specific next check"
 acceptance_criteria: []
 verification_needed: "Focused next check, if any"
 status: "open | resolved | partially-resolved | unchanged | regressed | not-rechecked | superseded | withdrawn"
@@ -30,8 +30,9 @@ prior_finding_id: null
 - **claim-risk** — wording is broader than the presented evidence
 - **presentation-judgment** — editorial or visual assessment on
   the user's path
-- **verify-first** — an unresolved implementation question. Say
-  what to inspect before prescribing a fix
+- **verify-first** — an unresolved implementation question. Keep
+  it when the next check is specific. Do not drop it for lack of
+  a fix. Drop only vague criticism with no check and no correction.
 
 ## Priority
 

package/skills/craftassay/references/output.md

@@ -0,0 +1,33 @@
+# Output folders
+
+Each review run gets its own directory. Required filenames stay
+`report.md`, `scorecard.md`, `findings.md`, and `coverage.md`
+inside that run folder.
+
+## Parent folder
+
+| Subject | Parent |
+| --- | --- |
+| A file | `<stem>.craftassay/` next to the file. `README.md` → `README.craftassay/` |
+| A named folder or system | `craftassay/` at that root |
+| A URL or paste with no project directory | `subject.craftassay/` in the working directory |
+
+## Run folder
+
+Write to `<parent>/<YYYY-MM-DD>/`.
+
+If that directory already exists, use `<YYYY-MM-DD>-2`, then
+`-3`, and so on.
+
+Never write into a directory that already contains `report.md`.
+Never write into a supplied baseline path.
+
+## Finding an earlier local review
+
+1. A baseline they attached wins. Use it. Do not modify it.
+2. Else look under the parent folder for the newest run that
+   contains `report.md`. Prefer a `CraftAssay Review:` or
+   `CraftAssay Comparison:` title.
+3. If none exists, this is the first review.
+
+A dated or numbered run folder is enough. No database.