@event4u/agent-config 7.5.0 → 8.0.0

package/dist/agent-src/commands/pr/create.md

@@ -92,7 +92,7 @@ trunk (that rot is exactly what the PR-gate replaces; see
 Run the deterministic sweep:
 
 ```bash
-python3 .augment/scripts/archive_completed_roadmaps.py   # --changed-only (default)
+./agent-config roadmap:archive   # --changed-only (default)
 ```
 
 It `git mv`s each completed roadmap (that this branch touched, per
@@ -178,7 +178,7 @@ github-api
 
 **Hard prohibitions** (each one cost 3+ extra tool calls in past runs):
 
-- ❌ `python3 -c "import urllib..."` / `python3 - <<PY ... PY` heredocs
+- ❌ `node -e "..."` / shell heredoc hacks
   to serialize the body or POST it.
 - ❌ `save-file PR_BODY.md` → read back → `curl -d @PR_BODY.md`.
 - ❌ `gh pr create --body-file …` shelling out when `github-api` is
@@ -252,24 +252,53 @@ Per `verbosity.post_action_reports` (default `minimal`):
   \`gh pr ready N\` to flip` when silent-draft (rule 4); omit on ready.
 - `full` → multi-line: PR number, URL, draft state, base/head, ready-reminder.
 
-#### 4c. Jira transition (only when transitioned)
+#### 4c. Status claims — verified facts only (MANDATORY)
+
+```
+NEVER STATE CI, CHECK, MERGEABILITY, OR DRAFT STATUS FROM ASSUMPTION.
+EVERY STATUS CLAIM IN THE REPLY CITES A COMMAND RUN THIS TURN.
+"BLOCKED" IS NEVER PARAPHRASED AS "CI IS STILL RUNNING".
+```
+
+Any statement about the PR's state — in the creation reply, after a
+conflict-resolution push, after ANY push to the PR branch — must be
+backed by fresh command output from the same reply:
+
+| Claim | Required evidence |
+|---|---|
+| Draft / ready | `gh pr view <n> --json isDraft` — quote the value |
+| CI green / red / running | `gh pr checks <n>` — report the actual fail list; a single `fail` row means FAIL, not "running" |
+| Mergeable / conflicts | `gh pr view <n> --json mergeable,mergeStateStatus` |
+
+`mergeStateStatus: BLOCKED` has several distinct causes (failing
+checks, draft state, missing reviews, branch protection). Resolving
+WHICH one requires `gh pr checks` — never guess the cause. If checks
+are still pending, say "pending" and name the pending jobs; never
+declare an outcome the output does not show.
+
+This is the [`direct-answers` Iron Law 2](../rules/direct-answers.md)
+live-state clause applied to the PR surface: git/PR/CI state decays
+silently and is NEVER reported from memory or inference.
+
+#### 4d. Jira transition (only when transitioned)
 
 Linked ticket + `routine_confirmations: true` → ask `1. Yes / 2. No`.
 Default (`false`) → skip silently. **Only emit a transition line when
 an actual Jira API call succeeded** — never announce "skipped".
 
-#### 4d. Settings short-circuit — single read per run
+#### 4e. Settings short-circuit — single read per run
 
 `verbosity.routine_confirmations`, `verbosity.post_action_reports`, and
 `commands.create_pr.preview_description` are read **once** at the top
 of the run and cached for the whole `/create-pr` invocation. Do **not**
-re-read `.agent-settings.yml` in 4b / 4c — both branches resolve from
+re-read `.agent-settings.yml` in 4b / 4d — both branches resolve from
 the cached values from step 1.
 
 When all three resolve to their silent defaults (`false` / `minimal` /
-`false`), steps 4b–4c collapse to the single `→ #N opened: <url>` line
-from 4b and a silent 4c. No extra file reads, no "checking settings…"
-narration, no confirmation prompts.
+`false`), steps 4b + 4d collapse to the single `→ #N opened: <url>` line
+from 4b and a silent 4d. No extra file reads, no "checking settings…"
+narration, no confirmation prompts. Step 4c is never collapsed — status
+claims always carry evidence.
 
 ### Rules
 

package/dist/agent-src/commands/prediction-pool.md

@@ -79,7 +79,7 @@ no silent best-guess.
 
 ### 2. Resolve the per-event analysis (state ground-truth)
 
-Look for `agents/tmp/prediction-pool/<slug>.md`.
+Look for `agents/runtime/tmp/prediction-pool/<slug>.md`.
 
 - **None →** start a new analysis (created at Step 9, never before).
 - **Exists →** read it. Then:
@@ -178,7 +178,7 @@ pool / site. If yes, loop Steps 3–7 for that pool.
 
 ### 9. Persist / extend the analysis (only now)
 
-Append a run-stamped section to `agents/tmp/prediction-pool/<slug>.md`: pool
+Append a run-stamped section to `agents/runtime/tmp/prediction-pool/<slug>.md`: pool
 URL(s), parsed rules, the entered tips with state `entered, not submitted`
 (or `submitted` if Step 7 submitted), council verdicts if any, and
 standing notes. Append-only — earlier runs stay as history. This is the

package/dist/agent-src/commands/profile/activate.md

@@ -32,7 +32,7 @@ not-installed pack, expands the `requires_hint` closure, and writes the
 overlay **atomically**):
 
 ```bash
-python3 -m scripts.config.session_profiles activate <name…> --json
+./scripts-run src/scripts/config/session_profiles activate <name…> --json
 ```
 
 - **Exit 0** → parse the JSON: `active_packs`, `closure_added`, `notes`.
@@ -49,7 +49,7 @@ Announce, using the helper's output:
 > surfaced: {N} commands, {M} skills ({H} hidden behind inactive packs)
 ```
 
-Get the counts from `python3 -m scripts.config.session_profiles show --json`.
+Get the counts from `./scripts-run src/scripts/config/session_profiles show --json`.
 
 ### 3. Re-bias the surface for the rest of the session
 
@@ -58,7 +58,7 @@ From now until `/profile deactivate` (or a new session), when the user asks
 set. Compute it with:
 
 ```bash
-python3 -m scripts.config.session_profiles surface --json
+./scripts-run src/scripts/config/session_profiles surface --json
 ```
 
 `shown` = surface these; `hidden` = do not list them proactively. Core /

package/dist/agent-src/commands/profile/deactivate.md

@@ -30,14 +30,14 @@ no silent session reset.
 - `/profile deactivate` (no args) → clear the whole overlay:
 
   ```bash
-  python3 -m scripts.config.session_profiles deactivate --json
+  ./scripts-run src/scripts/config/session_profiles deactivate --json
   ```
 
 - `/profile deactivate <name…>` → remove only the **named packs** from the
   active set (never their closure), so a shared dependency survives:
 
   ```bash
-  python3 -m scripts.config.session_profiles deactivate <name…> --json
+  ./scripts-run src/scripts/config/session_profiles deactivate <name…> --json
   ```
 
 Parse `active_packs` from the JSON.

package/dist/agent-src/commands/profile/show.md

@@ -28,7 +28,7 @@ from its cause.
 ### 1. Read the state
 
 ```bash
-python3 -m scripts.config.session_profiles show --json
+./scripts-run src/scripts/config/session_profiles show --json
 ```
 
 Fields: `active_packs`, `commands_shown`, `skills_shown`, `hidden_total`.
@@ -37,7 +37,7 @@ For a **non-technical employee**, render plain language instead — deterministi
 template (no LLM), the right content for an employee-facing surface:
 
 ```bash
-python3 -m scripts.config.session_profiles show --plain
+./scripts-run src/scripts/config/session_profiles show --plain
 ```
 
 Shape: [`session-profile-overlay` § Plain status surface](../../../../docs/contracts/session-profile-overlay.md#plain-status-surface).
@@ -64,7 +64,7 @@ Shape: [`session-profile-overlay` § Plain status surface](../../../../docs/cont
 If the user asks *which* artefacts are hidden, run:
 
 ```bash
-python3 -m scripts.config.session_profiles surface --json
+./scripts-run src/scripts/config/session_profiles surface --json
 ```
 
 and list `hidden[]` (name + packs). Keep it scannable; group by pack if long.

package/dist/agent-src/commands/research/deep.md

@@ -87,6 +87,11 @@ Read {fields_path} to get all field definitions.
    field names whose value contains `[uncertain]` or could not be
    sourced.
 4. All field values in English.
+5. Cite claims from fetched sources by paraphrase; verbatim quoting
+   follows `content-quoting-floor` (≤15 words, one quote per source).
+6. Fresh-lookup-class fields (current status, versions, prices, dates)
+   require a cited live source per `asking-and-brevity-examples § Volatile-fact
+   freshness` — never fill from model memory.
 
 ## Output path
 {output_path}

package/dist/agent-src/commands/research/report.md

@@ -80,7 +80,8 @@ script, no Python runtime.**
 | **List of dicts** | One row per dict, `key:value` pairs joined with ` \| `. |
 | **Plain list** | Short → comma-joined; long (> 5 items) → bullet list. |
 | **Nested dict** | Recurse; render with `;` between sibling keys or hard-break on long values. |
-| **Long text** | Strings > 100 chars → wrap in a blockquote or insert `<br>`. |
+| **Long text** | Strings > 100 chars → wrap in a blockquote or insert `<br>`. Verbatim source excerpts follow `content-quoting-floor` (≤15 words, one quote per source) — paraphrase the rest. |
+| **Freshness** | Fresh-lookup-class fields (status, version, price, date) render as reported by `/research:deep`, never re-derived from model memory at report time — see `asking-and-brevity-examples § Volatile-fact freshness`. |
 | **Extra fields** | JSON keys not declared in `fields.yaml` → group under `### Other info`. Filter `_source_file`, `uncertain`, and category-container keys. |
 | **`uncertain` array** | Render each entry on its own line under `### Uncertain fields`; never condense to a one-liner. |
 | **Skip conditions** | Field value contains `[uncertain]` · field name in `uncertain` · value is `null` / empty string. |

package/dist/agent-src/commands/roadmap/create.md

@@ -139,7 +139,20 @@ and ask (in the user's language):
 
 Only when the search is empty: save to the chosen location and show the final path.
 
-### 7. Update the progress dashboard
+### 7. Move consumed inbox file (if applicable)
+
+User pointed at a file in `agents/tmp/` as the roadmap source
+(e.g. "create a roadmap from `agents/tmp/my-idea.md`") →
+
+```bash
+mv agents/tmp/<filename> agents/tmp.old/<filename>
+```
+
+Automatic, same reply as saving — no confirmation (gitignored, local-only,
+reversible). Move ONLY files explicitly named as input. Never touch other
+`agents/tmp/` files.
+
+### 8. Update the progress dashboard
 
 Regenerate `agents/roadmaps-progress.md` so the new roadmap shows up:
 
@@ -149,7 +162,7 @@ Regenerate `agents/roadmaps-progress.md` so the new roadmap shows up:
 
 Mention the new overall count to the user.
 
-### 8. Offer council review (B1 hook, verbosity-gated)
+### 9. Offer council review (B1 hook, verbosity-gated)
 
 Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
 (default `false`):
@@ -181,21 +194,86 @@ If the user picks **1**:
 
 If the user picks **2** → continue.
 
-### 9. Offer execution
+### 10. Ask the execution mode — ONE question, then write frontmatter
 
-After saving (and any council review), ask the user (in their language) whether to start executing the roadmap immediately.
+Ask (in the user's language) exactly one numbered-options question:
+
+> How should this roadmap be executed later?
+>
+> 1. Fully autonomous — one run-start contract confirmation, then no
+>    interruptions except the safety floors
+> 2. Checkpoint at phase boundaries — compact status + continue prompt
+>    per phase
+> 3. Interactive — every gate fires as today
+>
+> **Recommendation:** 1
+
+Write the pick to frontmatter as `execution.mode:`
+(`autonomous` | `phase-checkpoints` | `interactive`). Rules:
+
+- Pick 3 → omit the field entirely (`interactive` is the absent-field
+  default; don't write noise).
+- Follow-up roadmaps (`parent_roadmap` set): pre-select the parent's
+  mode as the recommended option, but still ask — mode never inherits
+  silently (per template rule 18).
+- This question is about a **future** run's interaction pattern. It is
+  a declaration of intent, never a permission grant, and it does NOT
+  soften the step-11 hard stop: asking it must not morph into offering
+  execution now.
+- Semantics + contract mechanics:
+  [`templates/roadmaps.md` rule 18](../../templates/roadmaps.md) and
+  [`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md).
+- **Authoring check for pick 1 (`autonomous`):** scan the drafted steps
+  for vague phrasings (`improve/optimize` without a target, `make it
+  better/cleaner`, `clean up` without scope, `fix this` without a
+  symptom, `use best practices`, `handle errors properly`) and for
+  pre-existing `[~]` items. Surface each finding to the user for a
+  quick rephrase **before saving** — vagueness is cheap to resolve now
+  and expensive as a mid-run ambiguity halt; pre-existing `[~]` items
+  guarantee the archival gate interrupts the run.
+  `lint_roadmap_complexity` warns on the same patterns as a backstop.
+
+### 11. Hand back — HARD STOP, never auto-offer execution
+
+```
+ROADMAP SAVED → STOP. NEVER ASK "READY TO START?" / "BEGIN PHASE 1?"
+/ "SOFORT AUSFÜHREN?". CREATE = ARTIFACT ONLY. EXECUTION NEEDS A
+FRESH, EXPLICIT EXECUTION VERB FROM THE USER.
+```
 
-If yes → switch to [`/roadmap:process-phase`](process-phase.md) with
-the newly created file (the default execution scope of the `/roadmap`
-cluster). Offer [`process-step`](process-step.md) and
-[`process-full`](process-full.md) as alternatives. The legacy
-`/roadmap execute` command was removed — autonomous execution is the
-only path now.
+Emit a single hand-back line citing the saved path and (if regenerated)
+the new dashboard count. Then **stop the turn**.
+
+- Do **not** present numbered options for "start execution / pick
+  process-phase / pick process-step / pick process-full". The user
+  picks the next move when they're ready — silence on execution.
+- Do **not** soft-route ("*the roadmap is ready, kicking off E1.1…*").
+  That is a hand-off to execution disguised as a status line.
+- Do **not** include "Recommended next step: `/roadmap:process-phase`"
+  in the hand-back. Mentioning the command back-channels the same
+  ask.
+- The user resumes with an explicit execution verb (`implement`,
+  `build`, `start Phase A`, `arbeite die Roadmap ab`, `mach weiter
+  mit Phase 1`) on a **later turn**. That verb — not this command —
+  authorizes execution. See [`scope-mechanics § Post-artifact hard
+  stop`](../../contexts/authority/scope-mechanics.md).
+
+Failure modes covered by this hard stop:
+
+- Asking *"Soll ich jetzt mit Phase A anfangen?"* after the save line.
+- Offering *"1. Start now / 2. Review first / 3. Cancel"* — the user
+  did not ask for an execution menu, the create verb covered authoring
+  only.
+- Treating a thumbs-up / *"sieht gut aus"* / *"passt"* as authorization
+  to start. None of those are execution verbs.
 
 ### Rules
 
 - **Do NOT auto-generate content** — always ask the user for input.
 - **Do NOT commit or push.**
+- **Do NOT offer execution after save** — Step 11 is a hard stop.
+  Execution starts on a later turn with an explicit execution verb
+  ([`scope-control § Authoring vs. implementation`](../rules/scope-control.md#authoring-vs-implementation)).
 - **Do NOT include commit steps in the roadmap** unless the user explicitly
   requested them. See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
   Roadmaps plan **work**; commits are a separate delivery decision.

package/dist/agent-src/commands/roadmap/materialize.md

@@ -47,7 +47,7 @@ roadmap, writes one ticket per materialisable step into
 Run the build-readiness lint before handing back:
 
 ```bash
-python3 src/scripts/lint_ticket_buildable.py
+./scripts-run src/scripts/lint_ticket_buildable
 ```
 
 A `lite` ticket that fails the self-containedness floor is rejected or escalated

package/dist/agent-src/commands/roadmap/process-full.md

@@ -34,16 +34,29 @@ with the **scope delta below**.
 
 ## Scope delta
 
+- **Execution mode:** read `execution.mode` from frontmatter. Under
+  `autonomous` / `phase-checkpoints` the loop's § 3 pre-scan derives
+  the run-start **execution contract**
+  ([`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md));
+  ONE acceptance activates all run grants (feature branch, chunked
+  commits, push to that branch only, PR-open, batched artifact
+  drafting, council auto-enable) — no further asks until a safety
+  floor. `mode: autonomous` is the flagship pairing for this wrapper:
+  full working set + contract = uninterrupted run to the defined end
+  state.
 - **Working set:** every open step across every phase, in document
   order. Phase-internal annotations like `(deferred)` / `(optional)` /
   "gated on Phase N" do not narrow the working set.
 - **Stop after:** the entire roadmap reaches `count_open == 0`, or a
-  halt condition fires (Hard-Floor, council-off + ambiguity,
+  halt condition fires (Hard-Floor, council-off + ambiguity — the
+  latter only outside an accepted contract with council available,
   security-sensitive, scope-out-of-roadmap, test/quality red).
 - **Phase boundary handling:** at every phase boundary, run the
   per-phase quality pipeline when `quality_cadence: per_phase` (or
   `per_step`). On red → stop, surface, do **not** silently roll into
-  the next phase.
+  the next phase. Under `mode: phase-checkpoints`, additionally emit
+  the compact status + continue prompt at every boundary; under
+  `autonomous`, boundaries are silent (quality pipeline aside).
 - **Final archival:** when the roadmap is fully closed, run the
   archival check from
   [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).

package/dist/agent-src/commands/roadmap/process-phase.md

@@ -30,12 +30,20 @@ Sibling of [`/roadmap:process-step`](process-step.md) and
 Run the canonical loop in
 [`contexts/execution/roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md)
 with the **scope delta below**. The loop file owns roadmap discovery,
-pre-run summary, cadence resolution, commit-step pre-scan, the step
-loop with AI-council branching, halt conditions, and the archival
-check.
+pre-run summary, cadence resolution, the § 3 pre-scan (execution
+contract when frontmatter declares `execution.mode: autonomous |
+phase-checkpoints` — see
+[`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md) —
+otherwise the legacy commit-step ask), the step loop with AI-council
+branching, halt conditions, and the archival check.
 
 ## Scope delta
 
+- **Execution mode:** read `execution.mode` from frontmatter; under
+  `autonomous` / `phase-checkpoints` the run-start contract governs
+  the run's grants. `phase-checkpoints` behaves like `autonomous`
+  inside this single phase (its checkpoint prompt fires at the
+  boundary, where this wrapper stops anyway).
 - **Working set:** all open steps in the **first phase with
   `count_open > 0`**. If every phase is closed → report "Roadmap
   already complete." and run the archival check from
@@ -52,11 +60,15 @@ check.
 - **Autonomous within the phase, never beyond.** The user picks
   `process-step` for one step or `process-full` for the whole roadmap.
 - **No commit, push, branch, PR, tag, or bulk-destructive op** without
-  explicit permission this turn — see
-  [`commit-policy`](../../rules/commit-policy.md) and
+  explicit permission this turn **or an accepted run-start execution
+  contract** (whose grants cover exactly: the run's feature branch,
+  chunked commits on it, push to that branch only, PR-open — never
+  merge; see
+  [`roadmap-execution-contract § 3`](../../contexts/execution/roadmap-execution-contract.md)) —
+  see [`commit-policy`](../../rules/commit-policy.md) and
   [`scope-control § git-ops`](../../rules/scope-control.md#git-operations--permission-gated).
   Roadmap-listed commit steps follow the single-upfront-ask flow in
-  [`roadmap-process-loop § 3`](../../contexts/execution/roadmap-process-loop.md#3-commit-step-pre-scan--one-upfront-ask).
+  [`roadmap-process-loop § 3`](../../contexts/execution/roadmap-process-loop.md#3-pre-scan--execution-contract-or-commit-step-ask).
 - **Every checkbox edit syncs the dashboard in the same response** per
   [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
 - **AI-council consultations run silently when council is on.** No

package/dist/agent-src/commands/roadmap/process-step.md

@@ -32,6 +32,10 @@ with the **scope delta below**.
 
 ## Scope delta
 
+- **Execution mode:** `execution.mode` frontmatter is **ignored by this
+  wrapper** — a single-step run derives no execution contract
+  ([`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md)
+  stays unloaded); existing per-step behavior applies unchanged.
 - **Working set:** the **first checkbox `[ ]` in document order**
   inside the first phase with `count_open > 0`. If every step is
   closed → report "Roadmap already complete." and run the archival

package/dist/agent-src/commands/roadmap.md

@@ -74,7 +74,7 @@ each only binds a scope delta.
 - **Do NOT commit, push, or open a PR** unless the sub-command
   explicitly authorizes it. Roadmap-listed commit steps follow the
   single-upfront-ask flow in
-  [`roadmap-process-loop § 3`](../contexts/execution/roadmap-process-loop.md#3-commit-step-pre-scan--one-upfront-ask).
+  [`roadmap-process-loop § 3`](../contexts/execution/roadmap-process-loop.md#3-pre-scan--execution-contract-or-commit-step-ask).
 - **Do NOT chain sub-commands.** One `/roadmap <sub>` per turn.
 - If the user invokes `/roadmap` with no argument, **show the menu** —
   do not guess which sub-command they meant.

package/dist/agent-src/commands/security-audit-config.md

@@ -30,7 +30,7 @@ Agentic Applications. Consumer-facing counterpart to the suite's own
 ### 1. Run the static audit
 
 ```bash
-python3 src/scripts/security_audit_config.py --root <repo> --json
+./scripts-run src/scripts/security_audit_config --root <repo> --json
 ```
 
 (omit `--root` to audit the current repo). Reuses the Phase-1 detection library

package/dist/agent-src/commands/sync-agent-settings.md

@@ -49,7 +49,7 @@ Use when:
 - To create `.agent-project-settings.yml` (team file) → that is a
   separate concern; this command only touches the developer file.
 - To migrate a legacy flat `.agent-settings` → run
-  `python3 scripts/install.py` first; the installer owns migrations.
+  `npx @event4u/agent-config install` first; the installer owns migrations.
 
 ## Steps
 

package/dist/agent-src/commands/sync-gitignore/fix.md

@@ -74,7 +74,7 @@ stop — there is nothing to fix:
 Run:
 
 ```bash
-python3 <script> --cleanup-legacy --dry-run
+./scripts-run <script> --cleanup-legacy --dry-run
 ```
 
 Capture stdout (unified diff) and stderr (summary line listing the
@@ -102,7 +102,7 @@ legacy entries that would be removed). Three outcomes:
 
 - `1` (Apply) → re-run **without** `--dry-run`:
   ```bash
-  python3 <script> --cleanup-legacy
+  ./scripts-run <script> --cleanup-legacy
   ```
   Confirm with the script's own summary lines (removed-legacy count and
   added-entries count both surface there).
@@ -139,12 +139,48 @@ from this command. One line of guidance is enough:
 - **Do NOT push, commit, or modify other files** — this command writes
   to `.gitignore` only.
 
+### 5. Ignored-but-tracked detection pass
+
+After the legacy-cleanup sync, run the tracked-but-ignored check:
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/scripts/check_tracked_but_ignored.ts
+```
+
+Files reported →
+
+```
+> ⚠️  Tracked but now ignored — will appear in every `git status` until untracked.
+> Fix (files stay on disk):
+>
+>   git rm --cached \
+>     <file1> \
+>     <file2>
+>
+> Then commit. One-time cleanup.
+```
+
+NEVER run `git rm --cached` automatically — git-ops are user-owned.
+
+### 6. Agent artefacts not covered
+
+Manifest-vs-block coverage check (`agents-paths.yml` is the reference):
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/scripts/check_gitignore_freshness.ts
+```
+
+Fails → offer block re-sync (option 1 sync / 2 skip).
+
 ## See also
 
 - [`/sync-gitignore`](../sync-gitignore.md) — append-only sync of the
   managed block (no legacy cleanup)
-- [`scripts/sync_gitignore.py`](../../../scripts/sync_gitignore.py) —
+- [`scripts/sync_gitignore.ts`](../../../src/scripts/sync_gitignore.ts) —
   the helper (`--cleanup-legacy` flag)
-- [`scripts/install.sh`](../../../scripts/install.sh) —
-  `migrate_legacy_root_infra` (moves the **files**, complement to this
-  command which fixes the **ignore rules**)
+- [`scripts/check_tracked_but_ignored.ts`](../../../src/scripts/check_tracked_but_ignored.ts) —
+  ignored-but-tracked detection
+- [`scripts/check_gitignore_freshness.ts`](../../../src/scripts/check_gitignore_freshness.ts) —
+  manifest vs block coverage
+- [`docs/contracts/agents-layout.md`](../../../docs/contracts/agents-layout.md) —
+  classification contract for `agents/` entries

package/dist/agent-src/commands/team-knowledge/bootstrap.md

@@ -0,0 +1,106 @@
+---
+model_tier: medium
+name: team-knowledge-bootstrap
+pack: meta
+tier: 2
+visibility: internal
+cluster: team-knowledge
+sub: bootstrap
+description: One-shot deterministic seed for a fresh project's knowledge layer — stages template pages from real config/directory detection, never LLM-invented claims. Review-then-commit.
+skills: []
+suggestion:
+  eligible: true
+  trigger_description: "bootstrap the knowledge base, seed project knowledge, initialize agents/knowledge, onboard this project's knowledge layer"
+  trigger_context: "a project has no agents/knowledge/ typed pages yet and the user wants a starting baseline"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /team-knowledge bootstrap
+
+Seeds a fresh project's `agents/knowledge/` typed pages from
+**deterministic static analysis only** — directory names and known
+config filenames, never file content, never an LLM-invented claim.
+Fast first pass; the deeper analyzers (`project-analysis-*`,
+`standards-from-config`, `module-detect-on-the-fly`) remain the tools
+for filling in what this script cannot know.
+
+## Steps
+
+### 1. Run the detector
+
+```bash
+./scripts-run src/scripts/bootstrap_knowledge
+```
+
+Writes 5 template pages to the gitignored `agents/.bootstrap-staging/`
+directory — never directly to `agents/knowledge/`:
+
+- `concepts/structure.md` — detected package manifest + top-level
+  directories (evidence: the manifest filename / directory name)
+- `concepts/standards.md` — WHICH lint/format/test config files exist
+  (not their content — run `standards-from-config` for that)
+- `concepts/modules.md` — empty seed, `[HUMAN: verify]` (module
+  boundaries need code reading, which this script never does)
+- `procedures/api-conventions.md` — empty seed, fills in from
+  `api_shape_learned` events over time
+- `sessions/common-mistakes.md` — empty seed, fills in from
+  `mistake_made` events over time
+
+### 2. Review with the user
+
+Present the 5 staged pages. Every inferential line carries
+`[HUMAN: verify]` — read them together before committing anything:
+
+```
+> Bootstrap staged 5 pages under agents/.bootstrap-staging/:
+>
+> 1. Review each page now
+> 2. Move all as-is into agents/knowledge/
+> 3. Move selected pages only
+> 4. Discard — start knowledge capture organically instead
+```
+
+**Never move a staged page into `agents/knowledge/` without this
+review** — a bootstrap page moved in blind defeats the "no invented
+claims" guarantee just as surely as inventing the claim directly.
+
+### 3. Move approved pages, regenerate the index
+
+For each approved page:
+
+```bash
+mkdir -p agents/knowledge/<type>
+mv agents/.bootstrap-staging/<type>/<file>.md agents/knowledge/<type>/<file>.md
+```
+
+Then:
+
+```bash
+./scripts-run src/scripts/generate_knowledge_index
+```
+
+The team-sharing gate still applies at commit time — none of these
+pages should carry `visibility: private`.
+
+### 4. Discard the rest
+
+Delete `agents/.bootstrap-staging/` once done (or leave it — it is
+gitignored and regenerates on the next bootstrap run).
+
+## Rules
+
+- Never reads file CONTENTS beyond checking whether a known manifest
+  filename exists — this is what makes the secret/PII exclusion
+  structural rather than a redaction pass that could fail.
+- Never runs automatically — one-shot, user-invoked.
+- Never writes directly to `agents/knowledge/` — staging is mandatory.
+- Do NOT commit the moved pages — that is the user's call.
+
+## See also
+
+- [`/team-knowledge consolidate`](consolidate.md) — the ongoing capture loop this one-shot seed feeds into.
+- [`standards-from-config`](../../skills/standards-from-config/SKILL.md) — the full pointer+digest derivation for coding standards.
+- [`project-analysis-core`](../../skills/project-analysis-core/SKILL.md) / [`module-detect-on-the-fly`](../../skills/module-detect-on-the-fly/SKILL.md) — the deeper analyzers for `modules.md`.