Skip to content

Commit 9cd07fb

Browse files
committed
fix(extensions): harden assess slug handling and clarify verdict logic
Address the second review round on github#3568: - Slug path traversal: intake and all four downstream commands (research, define, shape, decide) now normalize an explicit or user-supplied slug to the [a-z0-9-] alphabet (dropping '.', '/', '\\') and reject an empty normalized result before constructing ASSESS_DIR. This guarantees a slug like `../..` cannot escape .specify/assessments/. - Metadata accuracy: the extension.yml and catalog.json descriptions no longer imply a "build/kill" call is handed to /speckit.specify — only a `go` hands off; a `kill` closes the assessment. - Verdict determinism (decide): a `go` now explicitly requires evidence strength `adequate`+ (never weak/unknown), resolving the conflict with the thin-evidence guardrail. - Risk polarity (decide): renamed the "Risk" criterion to "Risk posture" with positive polarity (strong = risks understood and mitigated) so it composes with the other scores that feed the verdict. - README: aligned the go-threshold guardrail with the evidence rule and documented the slug-normalization safety property. The PR description was also updated to drop the stale before_specify hook claim (the hook was removed in the previous commit). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <[email protected]> Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
1 parent 6e2d81d commit 9cd07fb

8 files changed

Lines changed: 17 additions & 12 deletions

File tree

‎extensions/assess/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,8 @@ specify extension enable assess
9494
- Only `speckit.assess.*` commands write, and only inside `.specify/assessments/<slug>/`. **None of them modify source code** — solution design and implementation belong to the SDD lifecycle (`/speckit.specify` onward).
9595
- Web content fetched during `intake`/`research` is treated as untrusted data, governed by an explicit URL Trust Policy (allowlisted public sources fetched freely; unknown hosts prompted or skipped; loopback/RFC1918/metadata endpoints refused).
9696
- Evidence is never over-claimed: unsourced statements are tagged `ASSUMPTION`, and `research.md` always includes an *Evidence Against the Idea* section.
97-
- Verdicts are never over-claimed: a `go` requires a valid problem and a shaped concept; otherwise the honest verdict is `needs-clarification`.
97+
- Verdicts are never over-claimed: a `go` requires a valid problem, `adequate`+ evidence (never weak/unknown), and a shaped concept; otherwise the honest verdict is `needs-clarification`.
98+
- Slugs are normalized to `[a-z0-9-]` and an empty result is rejected, so an assessment directory can never escape `.specify/assessments/`.
9899
- No command overwrites an existing artifact without confirmation; in automated mode it refuses.
99100

100101
## Relationship to Other Extensions

‎extensions/assess/commands/speckit.assess.decide.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Decide **judges; it does not spec or build.** It weighs the evidence already gat
1414
$ARGUMENTS
1515
```
1616

17-
Resolve the slug: explicit `slug=…` → conversation context (a slug reported earlier this session, confirmed by an existing `.specify/assessments/<slug>/` directory) → ask (interactive) → single existing directory (automated) → otherwise stop and ask. Set `ASSESS_SLUG` and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>`.
17+
Resolve the slug: explicit `slug=…` → conversation context (a slug reported earlier this session, confirmed by an existing `.specify/assessments/<slug>/` directory) → ask (interactive) → single existing directory (automated) → otherwise stop and ask. **Slug safety**: normalize any explicit or user-supplied slug — lowercase; whitespace/underscores → `-`; keep only `[a-z0-9-]` (drop every other character, including `.`, `/`, `\`); collapse and trim `-`; reject an empty normalized result. Only then set `ASSESS_SLUG` (the normalized value) and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>` — this keeps every read and write inside `.specify/assessments/`.
1818

1919
## Prerequisites
2020

@@ -31,9 +31,9 @@ Resolve the slug: explicit `slug=…` → conversation context (a slug reported
3131
- **Value vs. cost of inaction** — does solving it beat doing nothing? (from `problem.md`)
3232
- **Feasibility / appetite fit** — is there a credible option within a sane appetite? (from `concept.md`)
3333
- **Strategic fit** — does it align with the project's constitution/goals, if known?
34-
- **Risk** — what could make this fail or backfire?
34+
- **Risk posture** — are the major risks understood and acceptably mitigated? Rate with the same positive polarity as the other criteria: `strong` = key risks identified and credibly mitigated; `weak` = serious, unmitigated risk. (from all artifacts)
3535
2. **Reach a verdict**:
36-
- **go** — the idea is worth specifying. Requires problem validity `adequate`+ and a recommended concept option.
36+
- **go** — the idea is worth specifying. Requires problem validity `adequate`+, **evidence strength `adequate`+ (never `weak` or `unknown`)**, and a recommended concept option. If evidence is `weak`/`unknown`, the verdict is `needs-clarification`, not `go`.
3737
- **needs-clarification** — promising but blocked on specific unknowns. List exactly what must be answered and which stage to revisit.
3838
- **kill** — not worth building now. State the decisive reason plainly (weak problem, better alternative exists, cost > value, out of scope, superseded).
3939
3. **Record the rationale** so the decision is auditable months later. Any `unknown` score must be acknowledged, not glossed.
@@ -58,7 +58,7 @@ Write `ASSESS_DIR/decision.md`:
5858
| Value vs. inaction | … | … |
5959
| Feasibility / appetite | … | … |
6060
| Strategic fit | … | … |
61-
| Risk | … | … |
61+
| Risk posture | … | … |
6262

6363
## Verdict & Rationale
6464

‎extensions/assess/commands/speckit.assess.define.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Define **frames the problem; it does not shape or choose a solution.** If the in
1414
$ARGUMENTS
1515
```
1616

17-
Resolve the slug: explicit `slug=…` → conversation context (a slug reported earlier this session, confirmed by an existing `.specify/assessments/<slug>/` directory) → ask (interactive) → single existing directory (automated) → otherwise stop and ask. Set `ASSESS_SLUG` and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>`.
17+
Resolve the slug: explicit `slug=…` → conversation context (a slug reported earlier this session, confirmed by an existing `.specify/assessments/<slug>/` directory) → ask (interactive) → single existing directory (automated) → otherwise stop and ask. **Slug safety**: normalize any explicit or user-supplied slug — lowercase; whitespace/underscores → `-`; keep only `[a-z0-9-]` (drop every other character, including `.`, `/`, `\`); collapse and trim `-`; reject an empty normalized result. Only then set `ASSESS_SLUG` (the normalized value) and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>` — this keeps every read and write inside `.specify/assessments/`.
1818

1919
## Prerequisites
2020

‎extensions/assess/commands/speckit.assess.intake.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,13 @@ If the input is empty, ask the user for the idea (interactive), or stop with a n
2727

2828
Each idea gets its own directory under `.specify/assessments/<slug>/`. Resolve the slug in this order:
2929

30-
1. **User-provided slug**: If the user explicitly passes a slug (e.g., `slug=offline-mode`, `--slug offline-mode`, or an obvious slug-like token), use it verbatim after normalization (lowercase; hyphen-separated; no spaces; keep only lowercase letters `a–z`, digits `0–9`, and `-`). Do not append timestamps or numbers.
30+
1. **User-provided slug**: If the user explicitly passes a slug (e.g., `slug=offline-mode`, `--slug offline-mode`, or an obvious slug-like token), normalize it: lowercase; convert runs of whitespace/underscores to `-`; keep only lowercase letters `a–z`, digits `0–9`, and `-`; drop every other character (including `.`, `/`, `\`); collapse repeated `-`; strip leading/trailing `-`. Do not append timestamps or numbers.
3131
2. **Interactive mode** (a human is driving): If no slug was provided, **ask the user** and wait. Suggest a 2–4 word kebab-case candidate derived from the idea as a default.
3232
3. **Automated / non-interactive mode** (no human to ask): Generate a concise slug yourself (2–4 kebab-case words). The generated slug **MUST** produce a unique directory — if `.specify/assessments/<slug>/` already exists, append the shortest disambiguating suffix (`-2`, `-3`, …) or a short ISO-style date (`-20260715`). Never overwrite an existing assessment directory.
3333

34-
After resolution, set `ASSESS_SLUG` and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>`.
34+
**Reject unsafe slugs.** If the normalized slug is empty (e.g. the input was `../..`, `/`, or non-ASCII-only), refuse it: ask again (interactive) or stop with a note (automated). Never build a path from an unnormalized slug — normalization strips `.`, `/`, and `\`, which guarantees `ASSESS_DIR` cannot escape `.specify/assessments/`.
35+
36+
After resolution, set `ASSESS_SLUG` (the normalized, validated value) and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>`.
3537

3638
## Prerequisites
3739

‎extensions/assess/commands/speckit.assess.research.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,13 @@ $ARGUMENTS
1616

1717
The input carries the slug and (optionally) research direction or links. Resolve the slug:
1818

19-
1. **Explicit slug** (`slug=…`, `--slug …`, or an obvious token) — use it verbatim after normalization.
19+
1. **Explicit slug** (`slug=…`, `--slug …`, or an obvious token) — normalize it (see **Slug safety** below).
2020
2. **Conversation context** — if this session just ran `__SPECKIT_COMMAND_ASSESS_INTAKE__`, reuse the slug it reported. Confirm by checking that `.specify/assessments/<slug>/intake.md` exists; if not, fall through.
2121
3. **Interactive** — ask the user for the slug and wait.
2222
4. **Automated** — if exactly one assessment directory exists, use it; otherwise stop and ask.
2323

24+
**Slug safety**: normalize any explicit or user-supplied slug to the slug alphabet — lowercase; whitespace/underscores → `-`; keep only `[a-z0-9-]` (drop every other character, including `.`, `/`, `\`); collapse and trim `-`. **Reject** a slug whose normalized form is empty. Only then set `ASSESS_SLUG` (the normalized value) and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>` — this keeps every read and write inside `.specify/assessments/`.
25+
2426
Set `ASSESS_SLUG` and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>`.
2527

2628
## Prerequisites

‎extensions/assess/commands/speckit.assess.shape.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Shape **outlines options at the boundaries; it does not produce a spec or a plan
1414
$ARGUMENTS
1515
```
1616

17-
Resolve the slug: explicit `slug=…` → conversation context (a slug reported earlier this session, confirmed by an existing `.specify/assessments/<slug>/` directory) → ask (interactive) → single existing directory (automated) → otherwise stop and ask. Set `ASSESS_SLUG` and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>`.
17+
Resolve the slug: explicit `slug=…` → conversation context (a slug reported earlier this session, confirmed by an existing `.specify/assessments/<slug>/` directory) → ask (interactive) → single existing directory (automated) → otherwise stop and ask. **Slug safety**: normalize any explicit or user-supplied slug — lowercase; whitespace/underscores → `-`; keep only `[a-z0-9-]` (drop every other character, including `.`, `/`, `\`); collapse and trim `-`; reject an empty normalized result. Only then set `ASSESS_SLUG` (the normalized value) and `ASSESS_DIR = .specify/assessments/<ASSESS_SLUG>` — this keeps every read and write inside `.specify/assessments/`.
1818

1919
## Prerequisites
2020

‎extensions/assess/extension.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ extension:
44
id: assess
55
name: "Idea Assessment Pipeline"
66
version: "1.0.0"
7-
description: "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide, then hand a build/kill call to /speckit.specify. Assessments live under .specify/assessments/<slug>/"
7+
description: "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments/<slug>/"
88
category: "process"
99
effect: "read-write"
1010
author: spec-kit-core

‎extensions/catalog.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
"name": "Idea Assessment Pipeline",
2222
"id": "assess",
2323
"version": "1.0.0",
24-
"description": "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide, then hand a build/kill call to /speckit.specify. Assessments live under .specify/assessments/<slug>/",
24+
"description": "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments/<slug>/",
2525
"author": "spec-kit-core",
2626
"repository": "https://github.com/github/spec-kit",
2727
"bundled": true,

0 commit comments

Comments
 (0)