prizmkit 1.1.173 → 1.1.175

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -142,7 +142,7 @@ Before questions, check optional context files (never block if absent):
142
142
  - `.prizmkit/prizm-docs/root.prizm` (architecture/project context)
143
143
  - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
144
144
  - Existing test suite (critical for behavior preservation assessment)
145
- - Existing `.prizmkit/plans/refactor-list.json` (if appending additional items)
145
+ - Existing `.prizmkit/plans/refactor-list.json` (if appending additional items; inspect it only through the bounded commands below)
146
146
  - If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure:
147
147
  ```bash
148
148
  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
@@ -153,6 +153,28 @@ Before questions, check optional context files (never block if absent):
153
153
  - If no test suite detected, WARN: "No test suite found. Behavior preservation will rely on manual verification. Consider writing tests before refactoring."
154
154
  - Record test suite status in planning context for downstream use
155
155
 
156
+ ## Bounded Existing-List Context (Hard Rule)
157
+
158
+ For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
159
+
160
+ 1. Load only bounded project and recent-task context:
161
+ ```bash
162
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
163
+ ```
164
+ Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and exactly the five most recently appended top-level refactors as `{id, description}` pairs (or all available refactors when fewer than five exist).
165
+ 2. Inspect those five pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
166
+ 3. When a material relationship exists, incorporate only the minimum exact information whose omission would make the new refactor's scope, behavior preservation, compatibility, acceptance criteria, or dependency ordering incorrect. Do not write vague text such as `related to R-123`, do not copy an entire historical description merely because it overlaps, and add an old ID to `dependencies` only when it is a real execution prerequisite.
167
+ 4. Load a complete historical refactor only when the user explicitly identifies its ID for modification or detailed review, or a validation error identifies it:
168
+ ```bash
169
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
170
+ ```
171
+ 5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this draft.
172
+ 6. Merge and validate outside AI context:
173
+ ```bash
174
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
175
+ ```
176
+ The command validates the existing base, sequential new IDs, dependencies, and the complete DAG before atomically replacing the final list. Existing `generate` behavior remains the full-draft path for a new list and explicit full-list rewrites.
177
+
156
178
  ## Operation Modes
157
179
 
158
180
  ### Mode A: Interactive (default)
@@ -293,12 +315,17 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
293
315
  **Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
294
316
 
295
317
  **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
296
- 1. Write a draft JSON to `.prizmkit/plans/refactor-list.draft.json` with all collected refactor data.
297
- 2. Call the generate script to validate and produce the final file:
298
- ```bash
299
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
300
- ```
301
- The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
318
+ 1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object.
319
+ 2. Use the matching deterministic writer:
320
+ - New list or explicit full-list rewrite:
321
+ ```bash
322
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
323
+ ```
324
+ - Ordinary existing-list append:
325
+ ```bash
326
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
327
+ ```
328
+ `generate` fills root defaults for a complete draft. `append` preserves root metadata and historical refactors, defaults missing new statuses, and writes only after the merged full list validates.
302
329
  3. If validation fails -> fix the draft and retry (max 3 attempts)
303
330
  4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
304
331
  5. If review and validation pass -> present final summary
@@ -324,7 +351,7 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
324
351
 
325
352
  Run this gate after `.prizmkit/plans/refactor-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final refactor entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
326
353
 
327
- Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. Repeat the Headless Context Completeness Gate for every reviewed new or changed refactor. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
354
+ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed refactor. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
328
355
 
329
356
  ## Output Rules
330
357
 
@@ -10,7 +10,7 @@ For simple refactoring with minimal scope.
10
10
  - Existing test coverage for target area
11
11
 
12
12
  ## Fast Path Workflow
13
- 1. Confirm refactoring scope with user
13
+ 1. If `.prizmkit/plans/refactor-list.json` exists, run the parent Skill's bounded `context` command and consume only root context plus the five recent `{id, description}` pairs; never read the complete historical list or perform default keyword search. Then confirm refactoring scope with the user.
14
14
  2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
15
15
 
16
16
  ```
@@ -31,12 +31,12 @@ For simple refactoring with minimal scope.
31
31
  **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
32
32
  3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
33
33
  4. Run the mandatory Phase 6 Headless Context Completeness Gate on every drafted item; repair the draft until each returns `PASS` without conversation history or `user_context`.
34
- 5. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
34
+ 5. Write `.prizmkit/plans/refactor-list.draft.json`. For a new list, use the complete final-list draft and `generate`; for an existing list, write only the additions-only `refactors` object and call:
35
35
  ```bash
36
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
36
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
37
37
  ```
38
38
  6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
39
- 7. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
39
+ 7. If invalid -> apply fixes to the draft and re-run the same writer (`generate` for a new list, `append` for an existing list; max 2 attempts, then escalate to full workflow)
40
40
 
41
41
  ## When NOT to Use Fast Path
42
42
  - More than 2 refactor items
@@ -8,22 +8,23 @@ Run only when the current `refactor-planner` session generated, appended, or rew
8
8
 
9
9
  ## Direct Artifact Reads
10
10
 
11
- Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files directly:
11
+ Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
12
12
 
13
- - Final list: `.prizmkit/plans/refactor-list.json`
14
- - Draft/source list when present: `.prizmkit/plans/refactor-list.draft.json`
15
- - Pre-session final list snapshot if captured in memory before edits
13
+ - Final list: `.prizmkit/plans/refactor-list.json` — run the `context` command for root prose and recent IDs; do not load the complete historical list into AI context
14
+ - Draft/source list when present: `.prizmkit/plans/refactor-list.draft.json` — ordinary incremental flow contains only additions and may be read completely
15
+ - Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
16
16
  - In-memory draft object if the session has not written a draft file yet
17
+ - Newly appended or explicitly modified final entries — load each known ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN`
17
18
 
18
19
  Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
19
20
 
20
21
  ## Review Scope
21
22
 
22
- 1. If a pre-session final list exists, compare by stable refactor IDs (`R-*`).
23
- 2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
24
- 3. Treat refactors as changed only when item fields changed; review newly added refactor IDs and changed refactor IDs.
25
- 4. Preserve unchanged historical refactors. Read unchanged entries only when needed to verify dependency references or behavior-preservation interactions with reviewed refactors.
26
- 5. If no snapshot exists, review all refactor entries produced by the current generation flow.
23
+ 1. For ordinary append flow, use the additions-only draft and the append result's stable refactor IDs (`R-*`) as the change set; do not compare complete pre/post historical arrays in AI context.
24
+ 2. Root project prose is reviewable content, not generator metadata. Read it through `context`; review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
25
+ 3. Treat refactors as changed only when item fields changed; load and review newly added refactor IDs and explicitly changed refactor IDs through `show`.
26
+ 4. Preserve unchanged historical refactors. Do not load unchanged entries merely to establish review completeness. Use the full-list validator for dependency/DAG truth; use `show` for an old dependency or behavior-preservation interaction only when a specific reviewed refactor requires semantic inspection.
27
+ 5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
27
28
 
28
29
  ## Review Checklist
29
30
 
@@ -74,13 +75,21 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
74
75
  1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
75
76
  2. Accept only findings that improve planner correctness, completeness, or downstream behavior-preserving execution readiness.
76
77
  3. Apply accepted fixes to `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft object first.
77
- 4. Regenerate the final list through the existing generator:
78
+ 4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
79
+
80
+ ```bash
81
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --replace-tail
82
+ ```
83
+
84
+ `--replace-tail` is allowed only for the exact final-list suffix whose IDs match this session's additions, so accepted local-review fixes replace the current session's entries without duplicating or loading history. If the suffix does not match exactly, stop rather than rewriting another task.
85
+
86
+ For a new list or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
78
87
 
79
88
  ```bash
80
89
  python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
81
90
  ```
82
91
 
83
- 5. Re-run validation/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth.
92
+ 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth.
84
93
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
85
94
  7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
86
95
 
@@ -6,12 +6,18 @@ for the dev-pipeline system.
6
6
  Commands:
7
7
  validate Validate an existing .prizmkit/plans/refactor-list.json
8
8
  template Generate a blank template .prizmkit/plans/refactor-list.json
9
+ context Print bounded project context plus the five most recent refactors
10
+ show Print one explicitly requested refactor
11
+ append Merge an additions-only draft into an existing validated list
9
12
  generate Validate a draft JSON and generate final refactor-list.json with defaults
10
13
  summary Print a summary table of refactors from a .prizmkit/plans/refactor-list.json
11
14
 
12
15
  Usage:
13
16
  python3 validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json [--output validated.json]
14
17
  python3 validate-and-generate-refactor.py template --output .prizmkit/plans/refactor-list.json
18
+ python3 validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
19
+ python3 validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-001
20
+ python3 validate-and-generate-refactor.py append --input additions.json --output .prizmkit/plans/refactor-list.json
15
21
  python3 validate-and-generate-refactor.py generate --input draft.json --output .prizmkit/plans/refactor-list.json
16
22
  python3 validate-and-generate-refactor.py summary --input .prizmkit/plans/refactor-list.json [--format markdown|json]
17
23
 
@@ -20,10 +26,12 @@ Python 3.6+ required. No external dependencies.
20
26
 
21
27
  import argparse
22
28
  import collections
29
+ import copy
23
30
  import json
24
31
  import os
25
32
  import re
26
33
  import sys
34
+ import tempfile
27
35
  from datetime import datetime, timezone
28
36
 
29
37
  # ---------------------------------------------------------------------------
@@ -102,6 +110,25 @@ def _write_json(path, data):
102
110
  fh.write("\n")
103
111
 
104
112
 
113
+ def _write_json_atomic(path, data):
114
+ """Atomically replace *path* with pretty-printed JSON data."""
115
+ parent = os.path.dirname(os.path.abspath(path))
116
+ if parent and not os.path.isdir(parent):
117
+ os.makedirs(parent, exist_ok=True)
118
+ fd, temp_path = tempfile.mkstemp(prefix=".refactor-list-", suffix=".tmp", dir=parent)
119
+ try:
120
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
121
+ json.dump(data, fh, indent=2, ensure_ascii=False)
122
+ fh.write("\n")
123
+ os.replace(temp_path, path)
124
+ except Exception:
125
+ try:
126
+ os.unlink(temp_path)
127
+ except OSError:
128
+ pass
129
+ raise
130
+
131
+
105
132
  # ---------------------------------------------------------------------------
106
133
  # Cycle detection (Kahn's algorithm)
107
134
  # ---------------------------------------------------------------------------
@@ -728,6 +755,148 @@ def cmd_template(args):
728
755
  return 0
729
756
 
730
757
 
758
+ def _load_valid_existing(path):
759
+ """Load and validate one existing refactor list."""
760
+ data, load_err = _load_json(path)
761
+ if load_err:
762
+ _err(load_err)
763
+ return None, None, 2
764
+ if not isinstance(data, dict):
765
+ _err("Refactor list root must be an object")
766
+ return None, None, 1
767
+
768
+ result = validate_refactor_list(data)
769
+ if not result["valid"]:
770
+ _err("Existing refactor list is invalid")
771
+ for error in result["errors"]:
772
+ _err(" " + error)
773
+ return None, result, 1
774
+ return data, result, 0
775
+
776
+
777
+ def _next_top_level_id(refactors):
778
+ """Return the next R-NNN ID, or None when numeric capacity is exhausted."""
779
+ numbers = []
780
+ for refactor in refactors:
781
+ match = REFACTOR_ID_RE.match(str(refactor.get("id", "")))
782
+ if match:
783
+ numbers.append(int(str(refactor["id"])[2:]))
784
+ next_number = max(numbers, default=0) + 1
785
+ if next_number > 999:
786
+ return None
787
+ return "R-{:03d}".format(next_number)
788
+
789
+
790
+ def cmd_context(args):
791
+ """Print bounded existing-list context for incremental planning."""
792
+ data, _, exit_code = _load_valid_existing(args.input)
793
+ if exit_code:
794
+ return exit_code
795
+
796
+ refactors = data["refactors"]
797
+ next_id = _next_top_level_id(refactors)
798
+ if next_id is None:
799
+ _err("Refactor ID capacity exhausted at R-999")
800
+ return 1
801
+
802
+ context = {
803
+ "project_name": data.get("project_name"),
804
+ "project_description": data.get("project_description"),
805
+ "global_context": data.get("global_context") or {},
806
+ "task_count": len(refactors),
807
+ "next_id": next_id,
808
+ "recent_tasks": [
809
+ {"id": refactor.get("id"), "description": refactor.get("description")}
810
+ for refactor in refactors[-5:]
811
+ ],
812
+ }
813
+ print(json.dumps(context, indent=2, ensure_ascii=False))
814
+ return 0
815
+
816
+
817
+ def cmd_show(args):
818
+ """Print one explicitly requested top-level refactor."""
819
+ data, _, exit_code = _load_valid_existing(args.input)
820
+ if exit_code:
821
+ return exit_code
822
+ if not REFACTOR_ID_RE.match(str(args.id)):
823
+ _err("Refactor ID '{}' must match R-NNN".format(args.id))
824
+ return 1
825
+
826
+ for refactor in data["refactors"]:
827
+ if refactor.get("id") == args.id:
828
+ print(json.dumps(refactor, indent=2, ensure_ascii=False))
829
+ return 0
830
+ _err("Refactor '{}' not found".format(args.id))
831
+ return 1
832
+
833
+
834
+ def cmd_append(args):
835
+ """Append a collection-only draft to an existing validated refactor list."""
836
+ base, _, exit_code = _load_valid_existing(args.output)
837
+ if exit_code:
838
+ return exit_code
839
+
840
+ draft, load_err = _load_json(args.input)
841
+ if load_err:
842
+ _err(load_err)
843
+ return 2
844
+ if not isinstance(draft, dict) or set(draft.keys()) != {"refactors"}:
845
+ _err("Additions draft must be an object containing only 'refactors'")
846
+ return 1
847
+ additions = draft.get("refactors")
848
+ if not isinstance(additions, list) or not additions:
849
+ _err("Additions draft 'refactors' must be a non-empty array")
850
+ return 1
851
+ if not all(isinstance(refactor, dict) for refactor in additions):
852
+ _err("Every refactor addition must be an object")
853
+ return 1
854
+
855
+ merge_base = copy.deepcopy(base)
856
+ if args.replace_tail:
857
+ addition_ids = [refactor.get("id") for refactor in additions]
858
+ tail_ids = [refactor.get("id") for refactor in base["refactors"][-len(additions):]]
859
+ if len(base["refactors"]) < len(additions) or tail_ids != addition_ids:
860
+ _err("--replace-tail requires additions IDs to match the existing final-list suffix exactly")
861
+ return 1
862
+ merge_base["refactors"] = merge_base["refactors"][:-len(additions)]
863
+
864
+ next_id = _next_top_level_id(merge_base["refactors"])
865
+ if next_id is None:
866
+ _err("Refactor ID capacity exhausted at R-999")
867
+ return 1
868
+ start_number = int(next_id[2:])
869
+ prepared = copy.deepcopy(additions)
870
+ for offset, refactor in enumerate(prepared):
871
+ expected_id = "R-{:03d}".format(start_number + offset)
872
+ if start_number + offset > 999:
873
+ _err("Refactor ID capacity exhausted at R-999")
874
+ return 1
875
+ if refactor.get("id") != expected_id:
876
+ _err("Refactor addition {} must use next sequential ID '{}'".format(offset, expected_id))
877
+ return 1
878
+ refactor.setdefault("status", "pending")
879
+
880
+ merged = copy.deepcopy(merge_base)
881
+ merged["refactors"].extend(prepared)
882
+ result = validate_refactor_list(merged)
883
+ result["appended_ids"] = [refactor["id"] for refactor in prepared]
884
+ print(json.dumps(result, indent=2, ensure_ascii=False))
885
+ if not result["valid"]:
886
+ _err("Merged refactor list validation failed")
887
+ for error in result["errors"]:
888
+ _err(" " + error)
889
+ return 1
890
+
891
+ try:
892
+ _write_json_atomic(args.output, merged)
893
+ except Exception as exc:
894
+ _err("Failed to write merged refactor list: {}".format(exc))
895
+ return 2
896
+ _info("Appended {} refactor(s) to {}".format(len(prepared), args.output))
897
+ return 0
898
+
899
+
731
900
  def cmd_generate(args):
732
901
  """Handle the 'generate' command.
733
902
 
@@ -815,6 +984,9 @@ def main():
815
984
  " %(prog)s validate --input .prizmkit/plans/refactor-list.json\n"
816
985
  " %(prog)s validate --input .prizmkit/plans/refactor-list.json --output validated.json\n"
817
986
  " %(prog)s template --output .prizmkit/plans/refactor-list.json\n"
987
+ " %(prog)s context --input .prizmkit/plans/refactor-list.json\n"
988
+ " %(prog)s show --input .prizmkit/plans/refactor-list.json --id R-001\n"
989
+ " %(prog)s append --input additions.json --output .prizmkit/plans/refactor-list.json\n"
818
990
  " %(prog)s generate --input draft.json --output .prizmkit/plans/refactor-list.json\n"
819
991
  " %(prog)s summary --input .prizmkit/plans/refactor-list.json\n"
820
992
  " %(prog)s summary --input .prizmkit/plans/refactor-list.json --format json\n"
@@ -844,6 +1016,44 @@ def main():
844
1016
  "--output", required=True, help="Path to write template file"
845
1017
  )
846
1018
 
1019
+ # -- context --
1020
+ p_context = subparsers.add_parser(
1021
+ "context",
1022
+ help="Print root context and the five most recent refactor id/description pairs",
1023
+ )
1024
+ p_context.add_argument(
1025
+ "--input", required=True, help="Path to existing .prizmkit/plans/refactor-list.json"
1026
+ )
1027
+
1028
+ # -- show --
1029
+ p_show = subparsers.add_parser(
1030
+ "show",
1031
+ help="Print one explicitly requested top-level refactor",
1032
+ )
1033
+ p_show.add_argument(
1034
+ "--input", required=True, help="Path to existing .prizmkit/plans/refactor-list.json"
1035
+ )
1036
+ p_show.add_argument(
1037
+ "--id", required=True, help="Exact top-level refactor ID"
1038
+ )
1039
+
1040
+ # -- append --
1041
+ p_append = subparsers.add_parser(
1042
+ "append",
1043
+ help="Append a refactors-only draft to an existing validated refactor list",
1044
+ )
1045
+ p_append.add_argument(
1046
+ "--input", required=True, help="Path to additions-only draft JSON"
1047
+ )
1048
+ p_append.add_argument(
1049
+ "--output", required=True, help="Path to existing final refactor-list.json"
1050
+ )
1051
+ p_append.add_argument(
1052
+ "--replace-tail",
1053
+ action="store_true",
1054
+ help="Replace the exact existing suffix with the same IDs after local review",
1055
+ )
1056
+
847
1057
  # -- generate --
848
1058
  p_generate = subparsers.add_parser(
849
1059
  "generate",
@@ -880,6 +1090,9 @@ def main():
880
1090
  dispatch = {
881
1091
  "validate": cmd_validate,
882
1092
  "template": cmd_template,
1093
+ "context": cmd_context,
1094
+ "show": cmd_show,
1095
+ "append": cmd_append,
883
1096
  "generate": cmd_generate,
884
1097
  "summary": cmd_summary,
885
1098
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.173",
3
+ "version": "1.1.175",
4
4
  "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
5
5
  "type": "module",
6
6
  "bin": {