* chore(#604): rename get-shit-done/ runtime directory to gsd-core/ Renames the installed runtime directory `get-shit-done/` to `gsd-core/` so the on-disk name matches the package (`@opengsd/gsd-core`), repo, and binary (`gsd-tools`). The npm package name and binary are unchanged; npx/npm consumers are unaffected. Mechanical (bulk, ~90% of the diff): - `git mv get-shit-done gsd-core` - Swept path/identifier references across the repo via `perl -pe 's/get-shit-done(?!-\w)/gsd-core/g'`. The negative lookahead preserves the five legitimate slug variants that are NOT the directory: get-shit-done-{OLD,cc,classic,cli,redux} (old package/repo names). - Build/manifest wiring: package.json (bin, files, coverage globs), tsconfig.build.json (outDir), ~86 .gitignore build-output entries, stryker.config.mjs, scan-ignore files, install.js path strings. - Frozen (not rewritten): CHANGELOG.md history; translated docs (README.<locale>.md and docs/{ja-JP,ko-KR,pt-BR,zh-CN}/). New logic (review here): - src/installer-migrations/003-rename-get-shit-done-to-gsd-core.cts: a proper ADR-0008 installer migration. On upgrade it walks the legacy `~/.claude/get-shit-done/` tree, classifies each file via the prior install manifest, and emits remove-managed / backup-and-remove for managed files while PRESERVING unknown user-added files. Symlink-safe (skips a symlinked root and symlinked entries; bounds-checks every path under configDir). The framework rolls back on install failure. Emptied dirs may remain (framework has no recursive dir-removal primitive) — documented. - scripts/lint-legacy-dir-name.cjs: CI regression guard forbidding the bare `get-shit-done` directory token (split token to avoid self-match; case- insensitive; `(?!-\w)` lookahead allows the slug variants; allowlists CHANGELOG, translated docs, and `gsd-allow-legacy-name` marker lines). Wired into the lint-tests CI job. - Restored scripts/lint-package-identity-drift.cjs detection regexes (the mechanical sweep had wrongly rewritten the old-name patterns it exists to detect) and marked them as intentional legacy references. - TDD tests for the migration and the guard; do.md slash-command guard regex tightened so a `/gsd-core/bin` path segment is not mistaken for a command; changeset + docs/installer-migrations.md row added. Breaking: the installed runtime path moves `~/.claude/get-shit-done/` -> `~/.claude/gsd-core/`. Migration 003 removes the stale legacy dir's managed files (preserving user files) on upgrade. Users with custom hooks/configs hardcoding the old path must update them. Closes #604 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): unsweep pending changesets + allowlist injection-example docs CI fixes for the rename PR: - Do not sweep pending .changeset/*.md (ephemeral release-note fragments, like CHANGELOG); reverted those body edits so 5 pre-existing malformed fragments (missing type/pr) no longer enter the PR diff and trip docs-lint. Allowlisted .changeset/ in the legacy-name guard accordingly. - Allowlisted TEST-EXAMPLES.md and docs/explanation/security-model.md in prompt-injection-scan.sh: they contain intentional injection examples / security-model prose; the path-reference rewrites are kept. CodeQL alerts on this PR are pre-existing (alert lines unchanged by this PR; none in the new migration/guard) and are out of scope for the rename. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): resolve CodeQL alerts surfaced on this PR The rename diff touched files carrying pre-existing CodeQL findings; per the no-pre-existing-dismissal rule, fixing every surfaced alert rather than waving them off. All behavior-preserving: - scripts/ci-test-scope.cjs: build the config-path match from string .includes() instead of a RegExp over an arg-derived value (js/regex-injection). - src/profile-output.cts: escape backslashes before pipe-escaping desc/safeName so the table-cell escape is complete (js/incomplete-sanitization). - tests/{bug-2643,bug-2808,docs-parity-live-registry}: two-pass HTML-comment strip so a bare/unclosed `<!--` cannot survive (js/incomplete-multi-character-sanitization). - tests/inline-plan-threshold: drop the no-op `\s`->`\s` identity replace, keep the meaningful POSIX-class conversion (js/identity-replacement). Verified: build:lib green; the touched test files + ci-test-scope + profile-output suites pass; lint:legacy-name clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): correctly resolve remaining CodeQL alerts (regex-injection + sanitization) The prior commit's fixes for two alerts were ineffective: - ci-test-scope.cjs js/regex-injection: the alert is the CLI-arg-derived `file` reaching static regex `.test(file)` calls (not the config rule). Removed ALL regex over file/t — startsWith/includes/=== string checks + an isWindowsHint helper — so there is no regex sink for the tainted value. - js/incomplete-multi-character-sanitization (3 test files): a single `.replace(/<!--...-->/g,'')` can let `<!--` re-form. Replaced with a fixpoint loop (replace until stable) plus a final bare-opener strip. Verified: no regex over file/t remains; ci-test-scope + the 3 test suites pass; lint:legacy-name clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): make ci-test-scope + comment-strippers regex-free to clear CodeQL CodeQL flags the regex PATTERNS syntactically (regex-injection on the --files arg split; incomplete-multi-character-sanitization on the <!--...--> replace), so loop fixes do not satisfy it. Made these paths regex-free: - ci-test-scope.cjs splitFiles: char-by-char separator tokenizer (no /[,\\s]+/). - 3 test files: indexOf/slice HTML-comment stripper (no .replace(/<!--/)). Behavior preserved; ci-test-scope + the 3 suites pass; guard clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): unblock security base64 scan on the large rename diff The security job hit its 10m timeout: base64-scan.sh choked on the binary test fixture tests/feat-3594-parser-property-style.test.cjs (embedded NUL/ non-UTF8 bytes -> thousands of bogus blobs + "ignored null byte" warnings), and the ~800-file rename diff is slow to scan regardless. - scripts/base64-scan.sh: skip binary-by-content files (grep -Iq .) — they can't carry base64-obfuscated *text* and feeding NUL bytes through the per-line scanner is pathologically slow. collect_files already filtered binary *extensions*; this catches binary *content* in text extensions. - .github/workflows/security-scan.yml: raise the security job timeout 10m->30m to accommodate very large diffs (the scan itself is unchanged). Verified locally: scan skips the fixture, 0 "ignored null byte" warnings, 0 findings, exit 0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): sweep get-shit-done refs introduced by merging next The branch was updated with next (#614/#384/#618 etc.), which reference the get-shit-done/ dir (still named that on next). Swept the stale references in the merged files to gsd-core so the rename stays consistent and lint:legacy-name passes: - commands/gsd/discuss-phase.md (runtime-launcher shim paths) - src/core.cts (getAgentsDir layout comments) - tests/bug-384-agents-runtime-aware.test.cjs (require path to runtime lib) Verified: guard 0 violations; build green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): exclude gsd-core/ path segments from bug-3683 command cross-ref invariant The #614 runtime-launcher shim added to discuss-phase.md references `${_GSD_RUNTIME_ROOT}/gsd-core/bin/...`. bug-3683's REF_PATTERN excluded path-y refs only via lookbehind, but `}` precedes `/gsd-core/` in the shim, so it mis-read the directory path as a dangling `/gsd-core` command ref (same class as the #604 bug-2954 fix). Added a trailing `(?![\w-]*\/)` so `/gsd-<x>/...` path segments are not treated as slash-command references. Verified locally on BOTH platforms before pushing: - mac (node 26) full suite: 0 failures - gsd-test-runner (linux, node22 image) full suite: 0 failures - bug-3683 + bug-2954 pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): lazily resolve findProjectRoot in gsd-tools (harden flaky CI) CI intermittently failed state.test's gsd-tools subprocess with "findProjectRoot is not a function" (flip-flopping across legs; not reproducible on mac full suite, gsd-test linux full suite, test:unit, or state.test x8). findProjectRoot is a re-export from core.cjs (sourced from project-root.cjs); binding it via destructure at module-load can be undefined under a load-ordering edge. Resolve it lazily at call time via a small wrapper so the lookup happens after core.cjs is fully initialized. Verified green on BOTH platforms before pushing: - mac (node 26) full suite: 0 failures - gsd-test-runner (linux, node22) full suite: 0 failures - state.test.cjs: 106/106; gsd-tools loads cleanly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#604): allowlist verification-patterns.md placeholder examples in secret scan The rename git-mv'd references/verification-patterns.md into gsd-core/, pulling it into the secret-scan diff. It documents stub/placeholder RED-FLAG env-var examples (illustrative Stripe test-key / database-URL / API-key placeholders) — not real credentials. Added it to .secretscanignore with the strict annotation, mirroring the existing gsd-core/workflows/plan-phase.md exception. Verified locally: secret-scan-lint --strict OK; secret-scan --diff origin/next exits 0 with 0 findings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
339
gsd-core/workflows/ingest-docs.md
Normal file
339
gsd-core/workflows/ingest-docs.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# Ingest Docs Workflow
|
||||
|
||||
Scan a repo for mixed planning documents (ADR, PRD, SPEC, DOC), synthesize them into a consolidated context, and bootstrap or merge into `.planning/`.
|
||||
|
||||
- `[path]` — optional target directory to scan (defaults to repo root)
|
||||
- `--mode new|merge` — override auto-detect (defaults: `new` if `.planning/` absent, `merge` if present)
|
||||
- `--manifest <file>` — YAML file listing `{path, type, precedence?}` per doc; overrides heuristic classification
|
||||
- `--resolve auto|interactive` — conflict resolution (v1: only `auto` is supported; `interactive` is reserved)
|
||||
|
||||
---
|
||||
|
||||
<step name="banner">
|
||||
|
||||
Display the stage banner:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► INGEST DOCS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="parse_arguments">
|
||||
|
||||
Parse `$ARGUMENTS`:
|
||||
|
||||
- First positional token (if not a flag) → `SCAN_PATH` (default: `.`)
|
||||
- `--mode new|merge` → `MODE` (default: auto-detect)
|
||||
- `--manifest <file>` → `MANIFEST_PATH` (optional)
|
||||
- `--resolve auto|interactive` → `RESOLVE_MODE` (default: `auto`; reject `interactive` in v1 with message "interactive resolution is planned for a future release")
|
||||
|
||||
**Validate paths:**
|
||||
|
||||
```bash
|
||||
case "{SCAN_PATH}" in *..*) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;; esac
|
||||
test -d "{SCAN_PATH}" || echo "PATH_NOT_FOUND"
|
||||
if [ -n "{MANIFEST_PATH}" ]; then
|
||||
case "{MANIFEST_PATH}" in *..*) echo "SECURITY_ERROR: manifest path contains traversal"; exit 1 ;; esac
|
||||
test -f "{MANIFEST_PATH}" || echo "MANIFEST_NOT_FOUND"
|
||||
fi
|
||||
```
|
||||
|
||||
**Containment (required):** After resolving `SCAN_PATH` and `MANIFEST_PATH` relative to the repo root, canonicalize each with `realpath` (or platform equivalent) and assert the result is under `realpath("$REPO_ROOT")`. Reject absolute paths outside the repo (e.g. `/tmp`, `C:\Windows`) even when they do not contain `..`.
|
||||
|
||||
If `PATH_NOT_FOUND` or `MANIFEST_NOT_FOUND`: display error and exit.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="init_and_mode_detect">
|
||||
|
||||
Run the init query:
|
||||
|
||||
```bash
|
||||
INIT=$(node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" init ingest-docs)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
Parse `project_exists`, `planning_exists`, `has_git`, `git_worktree_root`, `in_nested_subdir`, `project_path` from INIT.
|
||||
|
||||
**Auto-detect MODE** if not set:
|
||||
- `planning_exists: true` → `MODE=merge`
|
||||
- `planning_exists: false` → `MODE=new`
|
||||
|
||||
If user passed `--mode new` but `.planning/` already exists: display warning and require explicit confirm via `AskUserQuestion` (approve-revise-abort from `references/gate-prompts.md`) before overwriting.
|
||||
|
||||
Git initialisation (Bug #3491 — never create a nested `.git` inside an existing worktree):
|
||||
|
||||
- If `has_git: true` and `in_nested_subdir: true`: do NOT run `git init`. Surface a warning that planning files will be tracked by the outer repo at `git_worktree_root`.
|
||||
- If `has_git: true` and `in_nested_subdir: false`: already at a worktree root, skip `git init`.
|
||||
- If `has_git: false` and `MODE=new`: initialize git:
|
||||
|
||||
```bash
|
||||
git init
|
||||
```
|
||||
|
||||
**Detect runtime** using the same pattern as `new-project.md`:
|
||||
- execution_context path `/.codex/` → `RUNTIME=codex`
|
||||
- `/.gemini/` → `RUNTIME=gemini`
|
||||
- `/.opencode/` or `/.config/opencode/` → `RUNTIME=opencode`
|
||||
- else → `RUNTIME=claude`
|
||||
|
||||
Fall back to env vars (`CODEX_HOME`, `GEMINI_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`) if execution_context is unavailable.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="discover_docs">
|
||||
|
||||
Build the doc list from three sources, in order:
|
||||
|
||||
**1. Manifest (if provided)** — authoritative:
|
||||
|
||||
Read `MANIFEST_PATH`. Expected YAML shape:
|
||||
|
||||
```yaml
|
||||
docs:
|
||||
- path: docs/adr/0001-db.md
|
||||
type: ADR
|
||||
precedence: 0 # optional, lower = higher precedence
|
||||
- path: docs/prd/auth.md
|
||||
type: PRD
|
||||
```
|
||||
|
||||
Each entry provides `path` (required, relative to repo root) + `type` (required, one of ADR|PRD|SPEC|DOC) + `precedence` (optional integer).
|
||||
|
||||
**2. Directory conventions** (skipped when manifest is provided):
|
||||
|
||||
```bash
|
||||
# ADRs
|
||||
find {SCAN_PATH} -type f \( -path '*/adr/*' -o -path '*/adrs/*' -o -name 'ADR-*.md' -o -regex '.*/[0-9]\{4\}-.*\.md' \) 2>/dev/null
|
||||
|
||||
# PRDs
|
||||
find {SCAN_PATH} -type f \( -path '*/prd/*' -o -path '*/prds/*' -o -name 'PRD-*.md' \) 2>/dev/null
|
||||
|
||||
# SPECs / RFCs
|
||||
find {SCAN_PATH} -type f \( -path '*/spec/*' -o -path '*/specs/*' -o -path '*/rfc/*' -o -path '*/rfcs/*' -o -name 'SPEC-*.md' -o -name 'RFC-*.md' \) 2>/dev/null
|
||||
|
||||
# Generic docs (fall-through candidates)
|
||||
find {SCAN_PATH} -type f -path '*/docs/*' -name '*.md' 2>/dev/null
|
||||
```
|
||||
|
||||
De-duplicate the union (a file matched by multiple patterns is one doc).
|
||||
|
||||
**3. Content heuristics** (run during classification, not here) — the classifier handles frontmatter `type:` and H1 inspection for docs that didn't match a convention.
|
||||
|
||||
**Cap:** hard limit of 50 docs per invocation (documented v1 constraint). If the discovered set exceeds 50:
|
||||
|
||||
```
|
||||
GSD > Discovered {N} docs, which exceeds the v1 cap of 50.
|
||||
Use --manifest to narrow the set to ≤ 50 files, or run
|
||||
/gsd:ingest-docs again with a narrower <path>.
|
||||
```
|
||||
|
||||
Exit without proceeding.
|
||||
|
||||
**Display discovered set** and request approval (see `references/gate-prompts.md` — `yes-no-pick` pattern works; or `approve-revise-abort`):
|
||||
|
||||
```
|
||||
Discovered {N} documents:
|
||||
{N} ADR | {N} PRD | {N} SPEC | {N} DOC | {N} unclassified
|
||||
|
||||
docs/adr/0001-architecture.md [ADR] (from manifest|directory|heuristic)
|
||||
docs/adr/0002-database.md [ADR] (directory)
|
||||
docs/prd/auth.md [PRD] (manifest)
|
||||
...
|
||||
```
|
||||
|
||||
**Text mode:** apply the same `--text`/`text_mode` rule as other workflows — replace `AskUserQuestion` with a numbered list.
|
||||
|
||||
Use `AskUserQuestion` (approve-revise-abort):
|
||||
- question: "Proceed with classification of these {N} documents?"
|
||||
- header: "Approve?"
|
||||
- options: Approve | Revise | Abort
|
||||
|
||||
On Abort: exit cleanly with "Ingest cancelled."
|
||||
On Revise: exit with guidance to re-run with `--manifest` or a narrower path.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="classify_parallel">
|
||||
|
||||
Create staging directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/intel/classifications/
|
||||
```
|
||||
|
||||
For each discovered doc, spawn `gsd-doc-classifier` in parallel. In Claude Code, issue all Task calls in a single message with multiple tool uses so the harness runs them concurrently. For Copilot / sequential runtimes, fall back to sequential dispatch.
|
||||
|
||||
Per-spawn prompt fields:
|
||||
- `FILEPATH` — absolute path to the doc
|
||||
- `OUTPUT_DIR` — `.planning/intel/classifications/`
|
||||
- `MANIFEST_TYPE` — the type from the manifest if present, else omit
|
||||
- `MANIFEST_PRECEDENCE` — the precedence integer from the manifest if present, else omit
|
||||
- `<required_reading>` — `agents/gsd-doc-classifier.md` (the agent definition itself)
|
||||
|
||||
Collect the one-line confirmations from each classifier. If any classifier errors out, surface the error and abort without touching `.planning/` further.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="synthesize">
|
||||
|
||||
Spawn `gsd-doc-synthesizer` once (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
|
||||
|
||||
```
|
||||
Agent({
|
||||
subagent_type: "gsd-doc-synthesizer",
|
||||
prompt: "
|
||||
CLASSIFICATIONS_DIR: .planning/intel/classifications/
|
||||
INTEL_DIR: .planning/intel/
|
||||
CONFLICTS_PATH: .planning/INGEST-CONFLICTS.md
|
||||
MODE: {MODE}
|
||||
EXISTING_CONTEXT: {paths to existing .planning files if MODE=merge, else empty}
|
||||
PRECEDENCE: {array from manifest defaults or default ['ADR','SPEC','PRD','DOC']}
|
||||
|
||||
<required_reading>
|
||||
- agents/gsd-doc-synthesizer.md
|
||||
- gsd-core/references/doc-conflict-engine.md
|
||||
</required_reading>
|
||||
"
|
||||
})
|
||||
```
|
||||
|
||||
> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read or synthesize any classified documents independently while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
|
||||
|
||||
The synthesizer writes:
|
||||
- `.planning/intel/decisions.md`, `.planning/intel/requirements.md`, `.planning/intel/constraints.md`, `.planning/intel/context.md`
|
||||
- `.planning/intel/SYNTHESIS.md`
|
||||
- `.planning/INGEST-CONFLICTS.md`
|
||||
|
||||
</step>
|
||||
|
||||
<step name="conflict_gate">
|
||||
|
||||
Read `.planning/INGEST-CONFLICTS.md`. Count entries in each bucket (the synthesizer always writes the three-bucket header; parse the `### BLOCKERS ({N})`, `### WARNINGS ({N})`, `### INFO ({N})` lines).
|
||||
|
||||
Apply the safety semantics from `references/doc-conflict-engine.md`. Operation noun: `ingest`.
|
||||
|
||||
**If BLOCKERS > 0:**
|
||||
|
||||
Render the report to the user, then display:
|
||||
|
||||
```
|
||||
GSD > BLOCKED: {N} blockers must be resolved before ingest can proceed.
|
||||
```
|
||||
|
||||
Exit WITHOUT writing PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md. The staging intel files remain for inspection. The safety gate holds — no destination files are written when blockers exist.
|
||||
|
||||
**If WARNINGS > 0 and BLOCKERS = 0:**
|
||||
|
||||
Render the report, then ask via AskUserQuestion (approve-revise-abort):
|
||||
- question: "Review the competing variants above. Resolve manually and proceed, or abort?"
|
||||
- header: "Approve?"
|
||||
- options: Approve | Abort
|
||||
|
||||
On Abort: exit cleanly with "Ingest cancelled. Staged intel preserved at `.planning/intel/`."
|
||||
|
||||
**If BLOCKERS = 0 and WARNINGS = 0:**
|
||||
|
||||
Proceed to routing silently, or optionally display `GSD > No conflicts. Auto-resolved: {N}.`
|
||||
|
||||
</step>
|
||||
|
||||
<step name="route_new_mode">
|
||||
|
||||
**Applies only when MODE=new.**
|
||||
|
||||
Audit PROJECT.md field requirements that `gsd-roadmapper` expects. For fields derivable from `.planning/intel/SYNTHESIS.md` (project scope, goals/non-goals, constraints, locked decisions), synthesize from the intel. For fields NOT derivable (project name, developer-facing success metric, target runtime), prompt via `AskUserQuestion` one at a time — minimal question set, no interrogation.
|
||||
|
||||
Delegate to `gsd-roadmapper` (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
|
||||
|
||||
```
|
||||
Agent({
|
||||
subagent_type: "gsd-roadmapper",
|
||||
prompt: "
|
||||
Mode: new-project-from-ingest
|
||||
Intel: .planning/intel/SYNTHESIS.md (entry point)
|
||||
Per-type intel: .planning/intel/{decisions,requirements,constraints,context}.md
|
||||
User-supplied fields: {collected in previous step}
|
||||
|
||||
Produce:
|
||||
- .planning/PROJECT.md
|
||||
- .planning/REQUIREMENTS.md
|
||||
- .planning/ROADMAP.md
|
||||
- .planning/STATE.md
|
||||
|
||||
Treat ADR-locked decisions as locked in PROJECT.md <decisions> blocks.
|
||||
"
|
||||
})
|
||||
```
|
||||
|
||||
> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more intel files, write planning artifacts, or create ROADMAP.md independently while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="route_merge_mode">
|
||||
|
||||
**Applies only when MODE=merge.**
|
||||
|
||||
Load existing `.planning/ROADMAP.md`, `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, all `CONTEXT.md` files under `.planning/phases/`.
|
||||
|
||||
The synthesizer has already hard-blocked on any LOCKED-in-ingest vs LOCKED-in-existing contradiction; if we reach this step, no such blockers remain.
|
||||
|
||||
Plan the merge:
|
||||
- **New requirements** from synthesized `.planning/intel/requirements.md` that do not overlap existing REQUIREMENTS.md entries → append to REQUIREMENTS.md
|
||||
- **New decisions** from synthesized `.planning/intel/decisions.md` that do not overlap existing CONTEXT.md `<decisions>` blocks → write to a new phase's CONTEXT.md or append to the next milestone's requirements
|
||||
- **New scope** → derive phase additions following the `new-milestone.md` pattern; append phases to `.planning/ROADMAP.md`
|
||||
|
||||
Preview the merge diff to the user and gate via approve-revise-abort before writing.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="finalize">
|
||||
|
||||
Commit the ingest results:
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" commit \
|
||||
"docs: ingest {N} docs from {SCAN_PATH} (#2387)" --files \
|
||||
.planning/PROJECT.md \
|
||||
.planning/REQUIREMENTS.md \
|
||||
.planning/ROADMAP.md \
|
||||
.planning/STATE.md \
|
||||
.planning/intel/ \
|
||||
.planning/INGEST-CONFLICTS.md
|
||||
```
|
||||
|
||||
(For merge mode, substitute the actual set of modified files.)
|
||||
|
||||
Display completion:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► INGEST DOCS COMPLETE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Show:
|
||||
- Mode ran (new or merge)
|
||||
- Docs ingested (count + type breakdown)
|
||||
- Decisions locked, requirements created, constraints captured
|
||||
- Conflict report path (`.planning/INGEST-CONFLICTS.md`)
|
||||
- Next step: `/gsd:plan-phase 1` (new mode) or `/gsd:plan-phase N` (merge, pointing at the first newly-added phase)
|
||||
|
||||
</step>
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
Do NOT:
|
||||
- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
|
||||
- Write PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md when BLOCKERs exist in the conflict report
|
||||
- Skip the 50-doc cap — larger sets must use `--manifest` to narrow the scope
|
||||
- Auto-resolve LOCKED-vs-LOCKED ADR contradictions — those are BLOCKERs in both modes
|
||||
- Merge competing PRD acceptance variants into a combined criterion — preserve all variants for user resolution
|
||||
- Bypass the discovery approval gate — users must see the classified doc list before classifiers spawn
|
||||
- Skip path validation on `SCAN_PATH` or `MANIFEST_PATH`
|
||||
- Implement `--resolve interactive` in this v1 — the flag is reserved; reject with a future-release message
|
||||
Reference in New Issue
Block a user