@winton979/task-cli 1.3.0 → 1.3.2

package/README.md

@@ -46,6 +46,8 @@ Compatible Grill Me implementations may also work.
 
 If no Grill Me compatible skill is installed, `task-fast`, `task-explore`, and `bug-explore` fall back to built-in clarification prompts.
 
+When `.ai/decisions/decisions.md` contains real entries, those skills should inspect it before finalizing a brief and pull in only the decisions that materially constrain the current task or bug.
+
 ---
 
 ## Usage
@@ -162,10 +164,12 @@ Calling `/decision-log` after every task is easy to forget. As a lower-friction
 /decision-sweep-weekly
 ```
 
-The skill scans archived task and bug briefs from the past 7 days, judges which ones contain a decision worth keeping (cross-task impact, rejected alternatives, counter-intuitive choices, externally driven calls, or instructive cancellations), drafts the entries, and waits for confirmation before appending to `.ai/decisions/decisions.md`.
+The skill scans archived task and bug briefs from the past 7 days, judges which ones contain a decision worth keeping (cross-task impact, rejected alternatives, counter-intuitive choices, externally driven calls, or instructive cancellations), drafts the entries, and waits for confirmation before writing anything to `.ai/decisions/decisions.md`. When a draft overlaps with or updates an existing decision, it should present the old and new versions together and ask whether to append, revise, merge, supersede, or skip.
 
 Use `decision-log` for in-the-moment recording and `decision-sweep-weekly` for periodic cleanup. Either alone is enough; using both is fine.
 
+The decisions file is intentionally narrow. It is meant to hold durable project invariants and reusable constraints, not a running transcript of every local implementation choice. The default write mode should still be append, but revisions to existing entries are reasonable when explicitly reviewed and confirmed by the user.
+
 ## Philosophy
 
 Task CLI is intentionally lightweight.
@@ -180,6 +184,8 @@ Instead of maintaining large specifications, it focuses on:
 
 The goal is to improve quality without slowing down iteration speed.
 
+That decision history is meant to be selectively reusable. Explore and fast-path skills should consult it to avoid violating existing project decisions, but only the parts that materially constrain the current work belong in the new brief.
+
 ## Compared with OpenSpec-Style Workflows
 
 Task CLI is designed as a lightweight alternative to heavier spec-driven systems such as OpenSpec.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winton979/task-cli",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Lightweight task workflow CLI for AI-assisted development",
   "license": "MIT",
   "type": "module",

package/src/init.js

@@ -19,6 +19,17 @@ const GRILL_ME_HINTS = [
   'grill me',
 ];
 
+const DECISIONS_READ_GUIDANCE = `Decision Intake
+
+Before finalizing the brief, inspect .ai/decisions/decisions.md if it exists and contains real entries beyond the title.
+
+Use it narrowly:
+
+* extract only decisions that materially constrain this task
+* ignore unrelated historical notes
+* treat the file as a source of durable project invariants, not as a second specification
+* if relevant decisions exist, summarize them briefly in Context or Constraints instead of copying them verbatim`;
+
 const SKILLS = {
   'task-fast': {
     name: 'task-fast',
@@ -37,18 +48,22 @@ Workflow
 
 1. If a Grill Me compatible skill is available in the current environment, use it for requirement clarification.
 2. If no Grill Me compatible skill is available, clarify the requirement yourself with focused questions just far enough to remove ambiguity.
-3. Create a concise task brief and save it to:
+3. Read the project code and conventions needed to avoid obvious conflicts.
+4. Read .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
+5. Create a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-4. Show the brief before coding.
-5. If the user does not object, implement immediately.
-6. Verify the result against the acceptance criteria.
-7. Archive the brief automatically by moving it to:
+6. Show the brief before coding.
+7. If the user does not object, implement immediately.
+8. Verify the result against the acceptance criteria.
+9. Archive the brief automatically by moving it to:
 
 .ai/tasks/archive/YYYY-MM-DD-task-name.md
 
-8. Summarize the outcome and any follow-up risks.
+10. Summarize the outcome and any follow-up risks.
+
+${DECISIONS_READ_GUIDANCE}
 
 Task Brief Format
 
@@ -105,11 +120,14 @@ Workflow
 3. Continue until the task is sufficiently understood.
 4. Do not write code.
 5. Do not create implementation details.
-6. Once the requirement is clear, generate a concise task brief and save it to:
+6. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain this task.
+7. Once the requirement is clear, generate a concise task brief and save it to:
 
 .ai/tasks/active/YYYY-MM-DD-task-name.md
 
-7. Show the saved brief and stop.
+8. Show the saved brief and stop.
+
+${DECISIONS_READ_GUIDANCE}
 
 Task Brief Format
 
@@ -292,11 +310,14 @@ Rules
    * expected behavior
    * assumptions
 
-8. Once the bug is sufficiently understood, generate a brief and save it to:
+8. Before writing the brief, inspect .ai/decisions/decisions.md if it exists and has entries. Pull in only decisions that materially constrain the observed behavior, expected behavior, or likely root cause.
+9. Once the bug is sufficiently understood, generate a brief and save it to:
 
 .ai/bugs/active/YYYY-MM-DD-bug-name.md
 
-9. Show the saved brief and stop.
+10. Show the saved brief and stop.
+
+${DECISIONS_READ_GUIDANCE}
 
 Bug Brief Format
 
@@ -445,10 +466,10 @@ BUG_CANCELLED
 
   'decision-log': {
     name: 'decision-log',
-    description: 'Record implementation decisions to .ai/decisions/decisions.md. Append-only, max 10 lines per entry.',
+    description: 'Record implementation decisions to .ai/decisions/decisions.md. Default to append; if updating an existing decision, require explicit user confirmation first. Max 10 lines per entry.',
     content: `---
 name: decision-log
-description: Record implementation decisions to .ai/decisions/decisions.md. Append-only, max 10 lines per entry.
+description: Record implementation decisions to .ai/decisions/decisions.md. Default to append; if updating an existing decision, require explicit user confirmation first. Max 10 lines per entry.
 user-invocable: true
 ---
 
@@ -456,6 +477,8 @@ Purpose
 
 Record important implementation decisions.
 
+Only record decisions that are likely to matter beyond a single task. Good candidates are durable constraints, architecture boundaries, rejected alternatives someone may retry later, externally forced choices, and intentional behavior that otherwise looks incorrect.
+
 Save Location
 
 .ai/decisions/decisions.md
@@ -483,7 +506,10 @@ What alternatives were rejected.
 Requirements
 
 * Maximum 10 lines per decision
-* Append only
+* Default to append
+* If a new entry appears to revise, merge with, or supersede an existing decision, do not edit or append yet
+* Instead, show the relevant prior entry, explain the overlap or conflict, and ask the user whether to append, revise, merge, supersede, or skip
+* Only modify an existing entry after explicit user confirmation
 * Keep concise
 `,
   },
@@ -513,8 +539,9 @@ Workflow
 4. For each candidate, draft a decision entry using the four-section format.
 5. Present a single review list: every scanned brief with a verdict (write / skip / insufficient info), then the proposed drafts grouped at the end.
 6. Do NOT append anything yet. Wait for the user to confirm which drafts to keep, edit, or drop.
-7. Only after confirmation, append the approved entries to .ai/decisions/decisions.md, oldest first, under the matching YYYY-MM-DD section heading.
-8. Report what was appended and what was skipped.
+7. If a proposed draft appears to overlap with, conflict with, or refine an existing decision, include that prior entry in the review and present explicit options such as append as new, revise existing, merge, supersede, or skip.
+8. Only after confirmation, apply the approved action for each draft. Default to appending new entries oldest first under the matching YYYY-MM-DD section heading; revise or merge only when the user explicitly selects that action.
+9. Report what was appended, revised, merged, superseded, and skipped.
 
 Sediment Conditions
 
@@ -555,9 +582,9 @@ What alternatives were rejected.
 Requirements
 
 * Maximum 10 lines per decision
-* Append only
+* Default to append
 * One date section per day; multiple decisions on the same day stack under the same heading
-* Never edit or delete prior entries
+* Never edit, merge, supersede, or delete prior entries without explicit user confirmation
 `,
   },
 };