@ryuenn3123/agentic-senior-core 3.0.46 → 3.0.47

package/.agent-context/prompts/init-project.md

@@ -26,12 +26,14 @@ If the user describes a project or feature, the agent must:
 If the user asks to create, complete, fix, or review project docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, or "lengkapkan docs", treat the request as documentation-first.
 
 The agent must:
-1. Materialize or refine required project docs before implementation: root `README.md` for every fresh or existing project; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` when APIs, firmware endpoints, CLI commands, or web application flows exist; `docs/database-schema.md` when persistent data exists; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
+1. Materialize or refine required project docs before implementation: root `README.md` for every fresh or existing project; `docs/doc-index.md` whenever `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` when APIs, firmware endpoints, CLI commands, or web application flows exist; `docs/database-schema.md` when persistent data exists; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
 2. Write formal project docs in English by default unless the user explicitly asks for another documentation language.
-3. Keep `README.md` public and developer friendly even for private projects: explain what the project is, who it is for, how to set it up, how to run the core workflow, how to configure it, and where deeper docs live. Do not put internal agent notes, private reasoning, secrets, or governance policy in the README.
-4. Keep documentation alive. When project behavior, setup, architecture, public contracts, data shape, deployment, or UI scope changes, update the matching docs in the same change.
-5. Avoid documentation sprawl. Add a new docs file only when the topic is stable, long enough to outgrow the README or core docs, or owned by a separate workflow such as hardware setup, deployment, troubleshooting, or testing validation.
-6. Stop after docs when the user only asked for docs. Do not write application, firmware, or UI code until the user explicitly asks for implementation or approves the implementation plan.
+3. Keep `docs/doc-index.md` short. Use it as the read-routing map with document path, purpose, reads-when triggers, status, and last-updated date. Do not duplicate the docs it points to.
+4. Keep `README.md` public and developer friendly even for private projects: explain what the project is, who it is for, how to set it up, how to run the core workflow, how to configure it, and where deeper docs live. Do not put internal agent notes, private reasoning, secrets, or governance policy in the README.
+5. Keep documentation alive. When project behavior, setup, architecture, public contracts, data shape, deployment, or UI scope changes, update the matching docs in the same change.
+6. Avoid documentation sprawl. Add a new docs file only when the topic is stable, long enough to outgrow the README or core docs, or owned by a separate workflow such as hardware setup, deployment, troubleshooting, or testing validation.
+7. Add PRD, SRS, technical-design, or separate ERD only when evidence triggers them. Use PRD for product roadmap/user-story ownership, SRS for contractual or multi-stakeholder acceptance criteria, technical-design for non-trivial architecture decisions, and a separate ERD only when `docs/database-schema.md` cannot stay readable with an embedded diagram.
+8. Stop after docs when the user only asked for docs. Do not write application, firmware, or UI code until the user explicitly asks for implementation or approves the implementation plan.
 
 ## Direct Constraint Mode
 

package/.agent-context/prompts/refactor.md

@@ -11,7 +11,7 @@ Before editing:
 3. If required project docs are missing, stop and bootstrap or update docs first.
 4. If the change touches UI, load .agent-context/prompts/bootstrap-design.md and .agent-context/rules/frontend-architecture.md before editing.
 5. If the change touches a dependency, framework, Docker, runtime, or ecosystem claim, verify current official docs before choosing.
-6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
+6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/doc-index.md` is missing while `docs/` exists, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
 7. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
 8. For backend/API scope, enforce layered boundaries, zero-trust input validation, safe centralized error responses, bounded list reads, transaction safety for multi-write mutations, idempotency for sensitive mutations, and behavior-focused API tests.
 9. Backend/API governance is global and stack-agnostic. Do not create stack-specific adapters or framework-specific rule branches; apply the global rules through the framework already present in the target project.

package/.agent-context/prompts/review-code.md

@@ -11,7 +11,7 @@ Before reviewing:
 3. Read .agent-context/review-checklists/architecture-review.md only when architecture or boundaries changed.
 4. Load only the rules relevant to the changed scope.
 5. For UI changes, load .agent-context/prompts/bootstrap-design.md, .agent-context/rules/frontend-architecture.md, docs/DESIGN.md, and docs/design-intent.json when present.
-6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
+6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
 7. Enforce single-source and lazy-loading policy: canonical rule source must be explicitly enforced, global domain governance must load lazily based on touched scope, and conflicting duplicate rule instructions must not appear during normal flow.
 
 Prioritize findings in this order:

package/.agent-context/review-checklists/pr-checklist.md

@@ -61,6 +61,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Scope applied: This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations
 - [ ] Style scope review is advisory and does not block merge when API docs are synced in the same commit and contract details are correct
 - [ ] Required docs exist before implementation: public and developer root README; project brief; architecture decision; flow overview; API/public contract when relevant; data model when relevant; and UI design contract when relevant.
+- [ ] `docs/doc-index.md` exists whenever `docs/` exists and acts as a compact read-routing map instead of duplicating requirements or architecture.
 - [ ] For docs-only or docs-first requests, implementation code was not changed unless the user explicitly asked for it or approved an implementation plan.
 - [ ] Formal project docs use English by default unless the user requested another language or existing docs established one.
 - [ ] Docs cover feature plan, architecture rationale, public contracts, data model, UI/design, security assumptions, testing strategy, delivery flow, and next validation actions where relevant.
@@ -73,6 +74,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Root README is public and developer friendly, even for private projects, and does not contain secrets, internal agent notes, private reasoning, or governance policy dumps.
 - [ ] Documentation grows with the project: README and matching docs were updated when setup, runtime, architecture, public contracts, data shape, deployment, validation, or UI scope changed.
 - [ ] Documentation file count stayed intentional: new docs files were added only for stable, distinct, or long workflows.
+- [ ] PRD, SRS, technical-design, or separate ERD files were added only when project evidence justified a distinct document.
 
 ## 7. UI And Accessibility
 
@@ -120,6 +122,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Security and testing requirements remain mandatory after static template purge.
 - [ ] Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing
 - [ ] Coding flow is blocked if root `README.md` is missing
+- [ ] Coding flow is blocked if `docs/doc-index.md` is missing while `docs/` exists
 - [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing
 
 ## Verdict

package/.agent-context/rules/api-docs.md

@@ -18,8 +18,12 @@ Choose README sections from project evidence. Do not force a fixed template when
 
 Documentation must evolve with the project. When behavior, setup, architecture, public contracts, data shape, deployment, or validation changes, update README and the matching docs in the same change.
 
+When `docs/` exists, keep `docs/doc-index.md` as the compact routing map for humans and agents. It should list active docs, their purpose, read triggers, status, and last update. It must not duplicate requirements, architecture, or API contracts.
+
 Start compact, then split only when a topic earns its own file. Good split signals are: the section is long, the workflow is owned separately, the content is referenced often, or the topic needs step-by-step care such as hardware setup, deployment, testing validation, operations, or troubleshooting.
 
+Use PRD, SRS, technical design, and ERD as conditional docs, not default boilerplate. PRD covers product intent and roadmap ownership. SRS covers contractual or complex acceptance criteria. Technical design covers architecture under pressure. ERD stays inside `docs/database-schema.md` unless the data model is large or relationship-heavy.
+
 ## Contract Rules
 
 - Document the public surface before or alongside implementation.

package/.agent-context/rules/architecture.md

@@ -33,6 +33,7 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Security and testing are non-negotiable baseline requirements.
 - Hard block before coding:
   - Root `README.md` must exist for every fresh or existing project and read as a public and developer entrypoint, not an internal agent note.
+  - `docs/doc-index.md` must exist whenever `docs/` exists. It is a compact read-routing map, not a replacement for project docs.
   - `docs/project-brief.md` must exist.
   - `docs/architecture-decision-record.md` (alias: `docs/Architecture-Decision-Record.md`) must exist.
   - `docs/flow-overview.md` must exist.
@@ -47,6 +48,19 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Keep docs current with project changes. Update README and the matching docs whenever setup, runtime, architecture, public contracts, data shape, UI scope, deployment, or validation flow changes.
 - Control docs file count. Keep the baseline compact, then add topic files only when a subject is stable, too long for README/core docs, or belongs to a distinct workflow such as hardware setup, deployment, testing validation, operations, or troubleshooting.
 
+## Documentation Read Routing and Conditional Specs
+
+Use `README.md` for human orientation, then use `docs/doc-index.md` to choose the smallest relevant read set. Do not broad-read every Markdown file in `docs/` by default.
+
+- Read `docs/project-brief.md`, `docs/architecture-decision-record.md`, and `docs/flow-overview.md` for broad planning, new features, or architecture changes.
+- Read `docs/api-contract.md` only when API, CLI, firmware endpoint, web flow, event, or library contract behavior is in scope.
+- Read `docs/database-schema.md` only when persistence, migrations, data shape, or query behavior is in scope.
+- Read `docs/DESIGN.md` and `docs/design-intent.json` only for UI, UX, frontend, layout, component, or visual work.
+- Add `docs/prd.md` only when there is product-roadmap, user-story, metrics, product-owner, or feature-flag ownership that would otherwise bloat the project brief.
+- Add `docs/srs.md` only for contractual, regulated, multi-stakeholder, or acceptance-criteria-heavy projects. Do not create both PRD and SRS unless those owners and purposes are distinct.
+- Add `docs/technical-design.md` only for non-trivial architecture decisions, major refactors, cross-cutting behavior, or system interactions that outgrow the ADR and flow overview.
+- Keep ERD inside `docs/database-schema.md` for small and medium schemas. Add a separate ERD file only when relationship complexity makes the schema doc hard to scan.
+
 ## Rules as Guardian (Cross-Session Consistency)
 
 - Session handoff must include active architecture contract summary.

package/.cursor/rules/agentic-senior-core.mdc

@@ -7,7 +7,7 @@ alwaysApply: true
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.

package/.cursorrules

@@ -1,6 +1,6 @@
 # .cursorrules - Legacy Thin Adapter
 
-Generated by Agentic-Senior-Core CLI v3.0.46
+Generated by Agentic-Senior-Core CLI v3.0.47
 Adapter Mode: legacy-thin
 Adapter Source: .agent-instructions.md when present; fallback .instructions.md
 Canonical baseline: .instructions.md

package/.gemini/instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../.instructions.md) as the canonical policy source.

package/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../.instructions.md) as the canonical policy source.

package/.github/instructions/agentic-senior-core.instructions.md

@@ -6,7 +6,7 @@ applyTo: "**"
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.

package/.instructions.md

@@ -97,7 +97,7 @@ Use `.agent-context/policies/` for quality gates, release thresholds, and audit
 
 ### Layer 9: Project Context
 
-Use root `README.md` as the public and developer entrypoint for every fresh or existing project. Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`, `database-schema.md`, `api-contract.md`, `flow-overview.md`, `DESIGN.md`, `design-intent.json`.
+Use root `README.md` as the public and developer entrypoint for every fresh or existing project. Use `docs/doc-index.md` as the compact routing map when `docs/` exists. Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`, `database-schema.md`, `api-contract.md`, `flow-overview.md`, `DESIGN.md`, `design-intent.json`.
 
 ## Mandatory Triggers
 
@@ -106,9 +106,10 @@ Use root `README.md` as the public and developer entrypoint for every fresh or e
 Trigger: docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, or "lengkapkan docs".
 
 1. Load `architecture.md`, `api-docs.md`, and only additional rules required by scope.
-2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` for APIs, firmware endpoints, CLI commands, or web application flows; `docs/database-schema.md` for persistent data; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
-3. Write formal project docs in English by default unless the user asks otherwise.
-4. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation.
+2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/doc-index.md` whenever `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` for APIs, firmware endpoints, CLI commands, or web application flows; `docs/database-schema.md` for persistent data; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
+3. Use `docs/doc-index.md` as the compact read-routing map. Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.
+4. Write formal project docs in English by default unless the user asks otherwise.
+5. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation.
 
 ### 2. New Project Planning
 

package/.windsurf/rules/agentic-senior-core.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.

package/.windsurfrules

@@ -1,6 +1,6 @@
 # .windsurfrules - Legacy Thin Adapter
 
-Generated by Agentic-Senior-Core CLI v3.0.46
+Generated by Agentic-Senior-Core CLI v3.0.47
 Adapter Mode: legacy-thin
 Adapter Source: .agent-instructions.md when present; fallback .instructions.md
 Canonical baseline: .instructions.md

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.

package/GEMINI.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.

package/README.md

@@ -34,6 +34,8 @@ One command to initialize rules, checklists, thin discovery adapters, and a comp
 > **See [docs/deep-dive.md](docs/deep-dive.md) and [docs/roadmap.md](docs/roadmap.md) for advanced configuration, planning mode, snapshot, and realtime options.**
 
 - This command writes `.agent-context/state/v3-purge-audit.json` and reports whether static directory deletion is safe.
+- When project docs are scaffolded, `docs/doc-index.md` is used as the compact map for deeper docs so agents can read the right files without scanning every Markdown file.
+- Local backup snapshots are written under `.agentic-backup/`; init and upgrade ensure that folder is ignored by the target repository.
 - Package scope is `@ryuenn3123`; the GitHub repository owner is `fatidaprilian`.
 
 ---
@@ -95,6 +97,8 @@ Use `--dry-run` first to preview changes safely, then apply with `--yes`.
 Upgrade now performs managed-surface synchronization by default: obsolete governance files under managed paths are pruned so the pack stays aligned with the latest release.
 Use `--no-prune` if you want to keep legacy managed files.
 
+When upgrade creates `.agentic-backup/`, it also keeps the target root `.gitignore` aligned with that local-only backup folder. The backup is for rollback safety, not a source of truth and not a file to commit.
+
 ## Instruction Entrypoints
 
 The canonical source is `.instructions.md`.

package/lib/cli/backup.mjs

@@ -4,6 +4,9 @@ import crypto from 'node:crypto';
 import { pathExists, ensureDirectory } from './utils.mjs';
 import { entryPointFiles, BACKUP_DIR_NAME } from './constants.mjs';
 
+const BACKUP_GITIGNORE_ENTRY = `${BACKUP_DIR_NAME}/`;
+const BACKUP_GITIGNORE_COMMENT = '# agentic-senior-core: local backup artifacts';
+
 /**
  * Calculates a SHA-256 hash of a file's contents.
  */
@@ -54,6 +57,7 @@ export async function createBackup(targetDirectoryPath) {
   await ensureDirectory(objectsDir);
 
   const pathsToTrack = [
+    path.join(targetDirectoryPath, '.gitignore'),
     ...entryPointFiles.map((entryPointFileName) => path.join(targetDirectoryPath, entryPointFileName)),
     path.join(targetDirectoryPath, '.agent-context'),
   ];
@@ -122,3 +126,36 @@ export async function createBackup(targetDirectoryPath) {
     durationMs: Date.now() - startTime
   };
 }
+
+export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
+  const gitignorePath = path.join(targetDirectoryPath, '.gitignore');
+  const existingContent = await pathExists(gitignorePath)
+    ? await fs.readFile(gitignorePath, 'utf8')
+    : '';
+  const existingLines = existingContent.split(/\r?\n/).map((line) => line.trim());
+
+  if (existingLines.includes(BACKUP_GITIGNORE_ENTRY) || existingLines.includes(BACKUP_DIR_NAME)) {
+    return {
+      status: 'unchanged',
+      gitignorePath,
+      entry: BACKUP_GITIGNORE_ENTRY,
+    };
+  }
+
+  let nextContent = existingContent;
+  if (nextContent.length > 0 && !nextContent.endsWith('\n')) {
+    nextContent += '\n';
+  }
+  if (nextContent.length > 0 && !nextContent.endsWith('\n\n')) {
+    nextContent += '\n';
+  }
+  nextContent += `${BACKUP_GITIGNORE_COMMENT}\n${BACKUP_GITIGNORE_ENTRY}\n`;
+
+  await fs.writeFile(gitignorePath, nextContent, 'utf8');
+
+  return {
+    status: existingContent ? 'updated' : 'created',
+    gitignorePath,
+    entry: BACKUP_GITIGNORE_ENTRY,
+  };
+}

package/lib/cli/commands/init.mjs

@@ -44,7 +44,7 @@ import {
   resolveDetectedSetupDecision,
 } from '../init-detection-flow.mjs';
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup } from '../backup.mjs';
+import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
 import {
   runProjectDiscovery,
   generateProjectDocumentation,
@@ -376,6 +376,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     detectionTransparency.decision.selectedProjectScopeLabel = selectedProjectScopeLabel;
 
     await createBackup(resolvedTargetDirectoryPath);
+    const backupGitignoreResult = await ensureBackupGitignoreEntry(resolvedTargetDirectoryPath);
+    if (backupGitignoreResult.status !== 'unchanged') {
+      console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
+    }
 
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
       includeMcpTemplate: shouldIncludeMcpTemplate,

package/lib/cli/commands/upgrade.mjs

@@ -41,7 +41,7 @@ import {
 } from '../compiler.mjs';
 
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup } from '../backup.mjs';
+import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
 import { performRollback } from '../rollback.mjs';
 import {
   detectProjectDocTemplateStaleness,
@@ -399,6 +399,10 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     }
 
     await createBackup(resolvedTargetDirectoryPath);
+    const backupGitignoreResult = await ensureBackupGitignoreEntry(resolvedTargetDirectoryPath);
+    if (backupGitignoreResult.status !== 'unchanged') {
+      console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
+    }
 
     try {
       const governanceSyncResult = await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {

package/lib/cli/compiler.mjs

@@ -422,8 +422,10 @@ export async function buildCompiledRulesContent({
       '3. .agent-context/prompts/review-code.md -> review, audit, check, analyze',
       '4. .agent-context/prompts/bootstrap-design.md -> ui, ux, layout, screen, tailwind, frontend, redesign',
       'Documentation-first policy:',
-      '- Create or refine required project docs before implementation: README.md for every fresh or existing project; docs/project-brief.md; docs/architecture-decision-record.md; docs/flow-overview.md; docs/api-contract.md when APIs, firmware endpoints, CLI commands, or web application flows exist; docs/database-schema.md when persistent data exists; and docs/DESIGN.md plus docs/design-intent.json for UI scope.',
+      '- Create or refine required project docs before implementation: README.md for every fresh or existing project; docs/doc-index.md whenever docs/ exists; docs/project-brief.md; docs/architecture-decision-record.md; docs/flow-overview.md; docs/api-contract.md when APIs, firmware endpoints, CLI commands, or web application flows exist; docs/database-schema.md when persistent data exists; and docs/DESIGN.md plus docs/design-intent.json for UI scope.',
       '- Keep README.md public and developer friendly, including for private projects: explain what the project is, who it is for, setup, usage, configuration, and links to deeper docs. Do not put secrets, internal agent notes, private reasoning, or governance policy dumps in it.',
+      '- Use docs/doc-index.md as the compact read-routing map before selecting deeper docs. Do not broad-read docs/*.md by default.',
+      '- Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.',
       '- Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
       '- Write formal project docs in English by default unless the user explicitly asks for another documentation language.',
       '- For docs-only/docs-first requests, do not write application, firmware, or UI code until the user asks or approves an implementation plan.',
@@ -546,14 +548,22 @@ export async function buildCompiledRulesContent({
 
   if (await pathExists(projectBriefPath)) {
     const hasRootReadme = await pathExists(path.join(resolvedTargetDirectoryPath, 'README.md'));
-    const projectDocsEntries = ['project-brief.md'];
+    const projectDocsEntries = [];
     const candidateDocFileNames = [
+      'doc-index.md',
+      'project-brief.md',
       'architecture-decision-record.md',
+      'technical-design.md',
+      'prd.md',
+      'srs.md',
       'database-schema.md',
+      'erd.md',
       'api-contract.md',
       'flow-overview.md',
       'DESIGN.md',
       'design-intent.json',
+      'runbook.md',
+      'troubleshooting.md',
     ];
 
     for (const candidateFileName of candidateDocFileNames) {
@@ -573,6 +583,7 @@ export async function buildCompiledRulesContent({
         '',
         'Universal SOP hard block policy:',
         '- README.md must exist and read as a public and developer entrypoint.',
+        '- docs/doc-index.md must exist whenever docs/ exists and act as the compact read-routing map.',
         '- Stop implementation if docs/project-brief.md is missing.',
         '- Stop implementation if docs/architecture-decision-record.md (alias: docs/Architecture-Decision-Record.md) is missing.',
         '- Stop implementation if docs/flow-overview.md is missing.',
@@ -580,6 +591,8 @@ export async function buildCompiledRulesContent({
         '- If the product exposes API or web application flows, docs/api-contract.md must exist before coding continues.',
         '- For UI scope, stop implementation if docs/DESIGN.md or docs/design-intent.json is missing.',
         '- Keep README.md overview-level, public, and developer friendly; do not put secrets, internal agent notes, private reasoning, or governance policy dumps in it.',
+        '- Use README.md plus docs/doc-index.md to choose the smallest relevant read set before loading deeper docs.',
+        '- Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.',
         '- Materialize missing docs first, then continue coding.',
         '- Bootstrap missing docs from real repo evidence and the latest user request. Do not write generic placeholder templates.',
         '- Separate confirmed facts from assumptions and end each major explanation with the next validation action.',
@@ -612,10 +625,12 @@ export async function buildCompiledRulesContent({
         '',
         'Bootstrap policy:',
         '- Create README.md as a public and developer entrypoint before coding continues.',
+        '- Create docs/doc-index.md as the compact read-routing map whenever docs/ exists.',
         '- Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
         '- docs/flow-overview.md must also exist before coding continues.',
         '- Add docs/database-schema.md when persistent data is involved.',
         '- Add docs/api-contract.md when API or web application flows are involved.',
+        '- Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.',
         '- For docs-only/docs-first requests, stop after docs unless the user asks for implementation or approves an implementation plan.',
         '- If docs/project-brief.md is missing, execute bootstrap-project-context prompt immediately.',
         hasBootstrapDesignPrompt

package/lib/cli/project-scaffolder/constants.mjs

@@ -6,6 +6,7 @@ export const PROJECT_DOC_FILE_NAMES = [
   'api-contract.md',
   'flow-overview.md',
 ];
+export const DOC_INDEX_FILE_NAME = 'doc-index.md';
 export const UI_DESIGN_CONTRACT_FILE_NAMES = ['DESIGN.md', 'design-intent.json'];
 
 // Legacy project docs may still carry this version header; keep for upgrade staleness checks.

package/lib/cli/project-scaffolder/discovery.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import { askChoice, askYesNo } from '../utils.mjs';
 import {
   ARCHITECTURE_STYLE_CHOICES,
+  DOC_INDEX_FILE_NAME,
   DOCKER_STRATEGY_CHOICES,
   SUPPORTED_DOC_LANGUAGES,
 } from './constants.mjs';
@@ -169,6 +170,7 @@ export function resolveProjectDocTargets(discoveryAnswers) {
     || discoveryAnswers.primaryDomain.toLowerCase().includes('fullstack');
 
   const requiredDocFileNames = [
+    DOC_INDEX_FILE_NAME,
     'project-brief.md',
     'architecture-decision-record.md',
     'flow-overview.md',

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -78,7 +78,9 @@ export function buildProjectContextBootstrapPrompt({
     '12. Treat topology as an agent decision unless the user explicitly constrained it. If monolith fits, explain why. If a service split fits, document the evidence and service boundary logic.',
     '13. Required docs coverage must include a public and developer README entrypoint, feature plan, architecture rationale, flow, public API or integration contracts when relevant, data model when relevant, UI/design when relevant, security assumptions, testing strategy, runtime/deployment notes, and next validation actions.',
     '14. README.md must be public and developer friendly, including for private projects: what it is, who it is for, setup, core workflow, configuration, and links to deeper docs. Do not include secrets, internal agent notes, private reasoning, or governance policy dumps.',
-    '15. Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
+    '15. docs/doc-index.md is the low-token routing map for docs/*. Keep it short, list each active doc, and explain when an agent should read it. Do not make it the source of truth for requirements or architecture.',
+    '16. Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
+    '17. Add SRS, PRD, technical-design, or ERD docs only when project evidence triggers them. Use PRD for product-roadmap/user-story ownership, SRS for contractual or multi-stakeholder acceptance criteria, technical-design for non-trivial architecture decisions, and ERD only as a separate file when the schema is too complex for docs/database-schema.md.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -105,10 +107,12 @@ export function buildProjectContextBootstrapPrompt({
     '## Required Execution',
     '1. Create all required docs files listed above with complete Markdown content.',
     '2. Make the docs adaptive to the real repo and prompt context. These are living references, not frozen templates.',
-    '3. In docs/project-brief.md and docs/architecture-decision-record.md, include explicit sections for confirmed facts, assumptions to validate, and next validation actions whenever context is incomplete.',
-    '4. Before implementation, use the docs to confirm stack, runtime, architecture, public contracts, data, validation, and delivery assumptions.',
-    '5. Keep content original, specific to this project, and actionable for implementation.',
-    '6. After writing docs, continue coding tasks using these docs as living project context.',
+    '3. In docs/doc-index.md, include a compact table with document path, purpose, reads-when triggers, status, and last-updated date.',
+    '4. In docs/project-brief.md and docs/architecture-decision-record.md, include explicit sections for confirmed facts, assumptions to validate, and next validation actions whenever context is incomplete.',
+    '5. Before implementation, use README.md plus docs/doc-index.md to select only the relevant docs for the current task instead of broad-reading docs/*.md.',
+    '6. Before implementation, use the docs to confirm stack, runtime, architecture, public contracts, data, validation, and delivery assumptions.',
+    '7. Keep content original, specific to this project, and actionable for implementation.',
+    '8. After writing docs, continue coding tasks using these docs as living project context.',
     '',
   ].join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.46",
+  "version": "3.0.47",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/validate/config.mjs

@@ -196,6 +196,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       '### 1. Documentation-First Mode',
       'root `README.md` for every fresh or existing project',
+      'docs/doc-index.md',
       'Stop after documentation when the user only asked for docs.',
       'Do not write application, firmware, or UI code',
     ],
@@ -205,6 +206,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       '## Universal SOP Baseline (Mandatory)',
       'Root `README.md` must exist for every fresh or existing project',
+      '`docs/doc-index.md` must exist whenever `docs/` exists',
       'Security and testing are non-negotiable baseline requirements.',
       'If required project context docs are missing, stop implementation and bootstrap docs before writing application code.',
     ],
@@ -214,6 +216,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       '## Documentation-First Requests',
       'root `README.md` for every fresh or existing project',
+      '`docs/doc-index.md` whenever `docs/` exists',
       'Stop after docs when the user only asked for docs.',
       'Write formal project docs in English by default',
     ],
@@ -230,19 +233,20 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
   {
     path: '.agent-context/prompts/review-code.md',
     snippets: [
-      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).',
+      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).',
     ],
   },
   {
     path: '.agent-context/prompts/refactor.md',
     snippets: [
-      '6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.',
+      '6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/doc-index.md` is missing while `docs/` exists, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.',
     ],
   },
   {
     path: 'lib/cli/compiler.mjs',
     snippets: [
       'Universal SOP hard block policy:',
+      'docs/doc-index.md whenever docs/ exists',
       'README.md must exist and read as a public and developer entrypoint',
       'Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
       'Documentation-first policy:',