jupiter:rewrite

You are orchestrating the Jupiter rewrite pipeline. The output is a consolidated document built from the same cataloger + scanner pipeline used by adopt.

Step 0: Pre-flight

0a. Working tree check

Run git status --porcelain. If output is non-empty:

Warning: working tree has uncommitted changes:
<output>

jupiter:rewrite commits on completion. Continue anyway? (Y/n)

Default N. On N, STOP.

0b. Module detection

Apply the same detection signals as jupiter:adopt Step 1d. Print: Module detection: <mode> (signal: <which>).

0c. Enumerate detected modules

Apply the same enumeration as jupiter:adopt Step 1e. Store as detected_modules. The scanner in Step 1 uses this list for its modules input. The write phase in Step 3 uses all_buckets = union(keys(catalog.proposed_layout), detected_modules[].name) so that surface-only buckets (like gamma in the multi-module fixture) also get a minimal consolidated file.

Step 1: Run the cataloger + scanner

Dispatch jupiter-spec-cataloger and jupiter-surface-scanner exactly as jupiter:adopt Steps 2 and 3 do. Use the same prompts, parsing, validation, and retry policy.

Rewrite runs the pipeline fresh every time -- it does not read an existing docs/master-spec/index.json. Pass already_adopted: [] to the cataloger and deep: false to the scanner (rewrite has no --deep flag).

Step 2: Plan the consolidation

For each bucket in all_buckets (may include buckets that have zero specs but had surface stubs -- they get a minimal consolidated file containing only the surface section):

• Target output file:
  • mode == "module": docs/master-spec/CONSOLIDATED-<bucket>.md
  • mode == "feature": docs/master-spec/CONSOLIDATED.md (single file across all feature buckets)
• Order specs within the bucket by topic proximity:
  • Build a similarity score between each pair of specs: count of shared topic keywords.
  • Greedy order: start with the spec that has the highest mean similarity to the rest (most central). At each step, append the unplaced spec most similar to the last placed spec. Ties broken by original file mtime, oldest first.

Step 3: Write consolidated files

For each target output file:

1. Open for writing (overwrite if exists).

2. Write the header:

   # Consolidated Spec: <bucket or "Main">
   
   Generated by jupiter:rewrite on <ISO 8601 timestamp>.
   Source files are listed in the order shown below; originals preserved unless you chose cleanup at the end of this run.
   
   

3. For each ordered spec, write:

   <!-- source: <original path> -->
   ## <basename without .md>
   
   <original file contents, with each `#` heading demoted by one level: `#` -> `##`, `##` -> `###`, etc.>
   
   

   Do NOT demote headings inside any <!-- jupiter:surface-begin --> ... <!-- jupiter:surface-end --> block. If the spec already contains such a block from a prior jupiter:adopt run, copy its contents through verbatim -- the block will be regenerated in full by step 3.4 below.

4. After all specs in a bucket, append the surface stubs for that bucket using the matching rule from jupiter:adopt Step 4c. Inline stubs live inside the same <!-- jupiter:surface-begin --> / <!-- jupiter:surface-end --> markers, within the consolidated file.

5. In multi-module mode, repeat for each bucket -- one output file per bucket.

Step 4: Write consolidated-index.json

Compute docs/master-spec/consolidated-index.json:

• generated_at: current ISO 8601
• jupiter_version: from plugin.json#version
• mode: from Step 0b
• root: "docs/master-spec/"
• consolidated_files: list of every consolidated file written in Step 3
• buckets[<name>]:
  • summary: top-3 topics joined with " / "
  • source_file: the consolidated file that contains this bucket
  • sections[]: for each spec in the bucket, emit

    {
      "anchor": "#<slugified h2 heading>",
      "original_path": "<original path of the spec>",
      "heading": "## <basename without .md>",
      "line": <line number inside the consolidated file>,
      "loc": <loc of that section in the consolidated file>,
      "topics": <from catalog>
    }
    

  • gaps_count: number of surface stubs appended to this bucket
• total_loc: sum of every consolidated file's LOC
• scan_summary: counts across all modules

Slugify: lowercase; replace runs of non-alphanumerics with -; trim leading/trailing -.

Validate the object against plugins/jupiter/schemas/consolidated-index.schema.json. On failure, STOP with the offending JSONPath.

Write to docs/master-spec/consolidated-index.json using 2-space indentation.

Step 5: Cleanup prompt

Compute:

• total_sources: number of distinct source spec paths read by the cataloger
• output_paths: list of consolidated file paths written in Step 3
• total_loc: the value from the index

Prompt:

Rewrite complete. <total_sources> source files consolidated into:
  <output path 1>
  <output path 2>
  ...
Total: <total_loc> LOC.

Delete the original spec files now? (y/N)

Default N. The default is keep -- never delete on blank input.

On N (default)

Commit only the consolidated files + sidecar index:

git add docs/master-spec/
git commit -m "jupiter: rewrite <total_sources> specs into <count> consolidated file(s) (originals kept)"

On y

Run git rm on every original spec path from the catalog. Do NOT remove anything outside catalog.specs[].path.

git rm <original path 1> <original path 2> ...
git add docs/master-spec/
git commit -m "jupiter: rewrite + cleanup <total_sources> originals into <count> consolidated file(s)"

Step 6: Final summary

Print:

jupiter:rewrite complete
========================
Mode:              <mode>
Sources:           <total_sources>
Consolidated:      <count> file(s)
Total LOC:         <total_loc>
Originals:         <kept | deleted>
Index:             docs/master-spec/consolidated-index.json
Commit:            <short sha>

STOP.