durable-context 1.0.0 → 1.1.1

package/README.md

@@ -8,17 +8,33 @@ Install into a project:
 npx durable-context init --project-name "My App"
 ```
 
-Adds `context/`, `decisions/`, and skills `plan-with-context` and `dive-into-plan`.
+Adds `context/`, `decisions/`, and invocation-only skills:
+
+- `project-profile-baseline`
+- `project-profile-refresh`
+- `plan-with-context`
+- `devils-advocate`
+- `dive-into-plan`
 
 ## Use
 
 ```text
 Plan with durable context: <what you want to build>
+Devil's advocate.
 Dive into the plan.
 ```
 
 Skills are invocation-only — they do not run automatically.
+Use `project-profile-baseline` once to populate repo-wide commands and
+operating facts; use `project-profile-refresh` when those stable facts change.
+
+Update managed agent assets without replacing project work:
+
+```bash
+npx durable-context@latest update
+```
 
-Options: `--target`, `--dry-run`, `--force`, `status`.
+Commands/options: `update`, `status`, `--target`, `--dry-run`, and `--force`
+for `init`.
 
 For release-anchored documentation, see the `reference-docs` package.

package/bin/durable-context.js

@@ -14,11 +14,26 @@ const agentsStart = '<!-- durable-context:start -->';
 const agentsEnd = '<!-- durable-context:end -->';
 
 const skills = [
+  {
+    name: 'project-profile-baseline',
+    readmeEntry:
+      '- `project-profile-baseline` - invoke explicitly to populate `context/project-profile.md` from source-backed repo facts.'
+  },
+  {
+    name: 'project-profile-refresh',
+    readmeEntry:
+      '- `project-profile-refresh` - invoke explicitly to refresh stable repo-wide facts in `context/project-profile.md`.'
+  },
   {
     name: 'plan-with-context',
     readmeEntry:
       '- `plan-with-context` - invoke explicitly to draft a durable plan in an initiative `plan.md`.'
   },
+  {
+    name: 'devils-advocate',
+    readmeEntry:
+      '- `devils-advocate` - invoke explicitly to challenge a draft plan before distribution.'
+  },
   {
     name: 'dive-into-plan',
     readmeEntry:
@@ -35,7 +50,10 @@ Initiatives under [\`context/initiatives/\`](context/initiatives/) are disposabl
 
 Invocation-only skills — ask by name:
 
+- [\`.agents/skills/project-profile-baseline/SKILL.md\`](.agents/skills/project-profile-baseline/SKILL.md) — populate \`context/project-profile.md\`.
+- [\`.agents/skills/project-profile-refresh/SKILL.md\`](.agents/skills/project-profile-refresh/SKILL.md) — refresh stable repo-wide profile facts.
 - [\`.agents/skills/plan-with-context/SKILL.md\`](.agents/skills/plan-with-context/SKILL.md) — draft a plan in \`plan.md\`.
+- [\`.agents/skills/devils-advocate/SKILL.md\`](.agents/skills/devils-advocate/SKILL.md) — critique a draft plan before distribution.
 - [\`.agents/skills/dive-into-plan/SKILL.md\`](.agents/skills/dive-into-plan/SKILL.md) — interrogate gaps, distribute into per-concern docs, promote to [\`decisions/\`](decisions/).
 
 [\`context/project-profile.md\`](context/project-profile.md) — repo-wide stack, commands, and test facts when populated.
@@ -55,6 +73,7 @@ const config = {
     render: renderAgentSection
   },
   nextSteps: [
+    'Optional: invoke .agents/skills/project-profile-baseline/SKILL.md to populate context/project-profile.md.',
     'Then: invoke .agents/skills/plan-with-context/SKILL.md when you start planning an initiative.'
   ]
 };

package/lib/installer.js

@@ -36,12 +36,12 @@ export async function runCli(config, argv) {
     return;
   }
 
-  if (args.command !== 'init') {
+  if (args.command !== 'init' && args.command !== 'update') {
     throw new Error(`Unknown command "${args.command}". Run "${config.cliName} --help".`);
   }
 
   const targetRoot = path.resolve(args.target);
-  const projectName = args.projectName ?? (await inferProjectName(targetRoot));
+  const projectName = await resolveProjectName(config, args, targetRoot);
   const installer = new Installer({
     config,
     targetRoot,
@@ -50,7 +50,12 @@ export async function runCli(config, argv) {
     dryRun: args.dryRun
   });
 
-  await installer.init();
+  if (args.command === 'init') {
+    await installer.init();
+    return;
+  }
+
+  await installer.update();
 }
 
 function parseArgs(argv, config) {
@@ -143,21 +148,24 @@ function printHelp(config) {
 
 Usage:
   ${config.cliName} init [options]
+  ${config.cliName} update [options]
   ${config.cliName} status [options]
 
 Options:
   --target <path>          Project root to install into. Defaults to cwd.
   --project-name <name>    Name used to replace PROJECT_NAME placeholders.
-  --force                  Replace existing generated directories.
+  --force                  Replace existing generated directories during init.
   --dry-run                Show planned changes without writing files.
   -h, --help               Show help.
   -v, --version            Show package version.
 
 Examples:
   npx ${config.packageJson.name} init --project-name "My App"
+  npx ${config.packageJson.name}@latest update
   npx ${config.packageJson.name}@${config.packageJson.version} init --project-name "My App"
   npx ${config.packageJson.name} status --target ../existing-project
 
+The update command refreshes managed agent assets without replacing project work.
 The status command reads ${config.metadataPath} from an initialized project.
 `);
 }
@@ -176,6 +184,22 @@ async function inferProjectName(targetRoot) {
   return path.basename(targetRoot);
 }
 
+async function resolveProjectName(config, args, targetRoot) {
+  if (args.projectName) {
+    return args.projectName;
+  }
+
+  if (args.command === 'update') {
+    const metadata = await readOptionalJson(path.join(targetRoot, config.metadataPath));
+
+    if (typeof metadata?.projectName === 'string' && metadata.projectName.trim()) {
+      return metadata.projectName;
+    }
+  }
+
+  return inferProjectName(targetRoot);
+}
+
 class Installer {
   constructor({ config, targetRoot, projectName, force, dryRun }) {
     this.config = config;
@@ -199,6 +223,16 @@ class Installer {
     this.printSummary();
   }
 
+  async update() {
+    await this.ensureDirectory(this.targetRoot);
+
+    await this.installAgentsFile();
+    await this.updateSkills();
+    await this.writeMetadata();
+
+    this.printSummary();
+  }
+
   async installPayloadRoots() {
     const entries = await readdir(this.templateDir, { withFileTypes: true });
 
@@ -290,6 +324,22 @@ class Installer {
       );
     }
 
+    await this.upsertSkillsReadme();
+  }
+
+  async updateSkills() {
+    for (const skill of this.config.skills) {
+      await this.copyTemplatePath(
+        `${agentsSkillsRelative}/${skill.name}`,
+        `${agentsSkillsRelative}/${skill.name}`,
+        { replaceExisting: true }
+      );
+    }
+
+    await this.upsertSkillsReadme();
+  }
+
+  async upsertSkillsReadme() {
     const readmeTarget = await this.findExistingTargetPath(`${agentsSkillsRelative}/README.md`);
     const readmePath = readmeTarget.exists
       ? readmeTarget.path
@@ -302,29 +352,55 @@ class Installer {
     }
 
     const current = await readFile(readmePath, 'utf8');
-    const missingSkills = this.config.skills.filter((skill) => !current.includes(skill.name));
+    const section = this.renderSkillsReadmeSection();
+    const { start, end } = this.skillsReadmeMarkers();
+
+    if (current.includes(start) && current.includes(end)) {
+      const updated = current.replace(
+        new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`),
+        section
+      );
 
-    if (missingSkills.length === 0) {
-      this.note(`${readmeDisplay} already lists the ${this.config.summaryLabel} skills`);
+      if (updated === current) {
+        this.note(`${readmeDisplay} already has the ${this.config.summaryLabel} skills section`);
+        return;
+      }
+
+      await this.writeFile(readmePath, updated, `update ${readmeDisplay} ${this.config.summaryLabel} skills section`);
       return;
     }
 
-    const entry = [
-      '',
-      `## ${this.config.summaryLabel} Skills`,
-      '',
-      ...missingSkills.map((skill) => skill.readmeEntry),
-      ''
-    ].join('\n');
+    const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n';
 
     await this.writeFile(
       readmePath,
-      `${current.trimEnd()}\n${entry}`,
+      `${current}${separator}${section}\n`,
       `append ${this.config.summaryLabel} skills to ${readmeDisplay}`
     );
   }
 
-  async copyTemplatePath(sourceRelative, targetRelative) {
+  skillsReadmeMarkers() {
+    const name = this.config.packageJson.name;
+
+    return {
+      start: `<!-- ${name}:skills:start -->`,
+      end: `<!-- ${name}:skills:end -->`
+    };
+  }
+
+  renderSkillsReadmeSection() {
+    const { start, end } = this.skillsReadmeMarkers();
+
+    return [
+      start,
+      `## ${this.config.summaryLabel} Skills`,
+      '',
+      ...this.config.skills.map((skill) => skill.readmeEntry),
+      end
+    ].join('\n');
+  }
+
+  async copyTemplatePath(sourceRelative, targetRelative, { replaceExisting = this.force } = {}) {
     const sourcePath = path.join(this.templateDir, sourceRelative);
     const targetInfo = await this.findExistingTargetPath(targetRelative);
 
@@ -337,7 +413,7 @@ class Installer {
     if (targetInfo.exists) {
       const variantNote = targetInfo.caseVariant ? ` at ${targetInfo.display}` : '';
 
-      if (!this.force) {
+      if (!replaceExisting) {
         this.note(`skip ${targetRelative} (already exists${variantNote}; use --force to replace)`);
         return false;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "durable-context",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Invocation-only skills and scaffold for durable planning: initiatives in context/, decisions in an append-only log.",
   "license": "MIT",
   "type": "module",

package/template/.agents/skills/README.md

@@ -1,6 +1,13 @@
 # Project Skills
 
-Invocation-only — ask by name.
+Invocation-only - ask by name.
 
-- `plan-with-context` — draft a durable plan in an initiative `plan.md`.
-- `dive-into-plan` — interrogate a settled plan, distribute into initiative docs, promote to `decisions/`.
+<!-- durable-context:skills:start -->
+## Durable Context Skills
+
+- `project-profile-baseline` - invoke explicitly to populate `context/project-profile.md` from source-backed repo facts.
+- `project-profile-refresh` - invoke explicitly to refresh stable repo-wide facts in `context/project-profile.md`.
+- `plan-with-context` - invoke explicitly to draft a durable plan in an initiative `plan.md`.
+- `devils-advocate` - invoke explicitly to challenge a draft plan before distribution.
+- `dive-into-plan` - invoke explicitly to interrogate a settled plan, distribute it into initiative docs, and promote decisions.
+<!-- durable-context:skills:end -->

package/template/.agents/skills/devils-advocate/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: devils-advocate
+description: Critique-only adversarial review of plan-with-context plans. Use ONLY when the human explicitly asks for "devil's advocate", "challenge the plan", "red-team the plan", or adversarial planning review before dive-into-plan; rerun after dive-into-plan only when a materially new decision appears.
+---
+
+# Devil's Advocate
+
+Invocation-only. Challenge a draft plan before it hardens. Do not edit files
+unless the human explicitly asks for changes.
+
+## Workflow
+
+1. Read the initiative `README.md`, `plan.md`, nearest `AGENTS.md`, and `context/project-profile.md` when useful.
+2. Identify the commitment being challenged: recommendation, approach, or decision.
+3. If there is no meaningful decision, or the current plan is the best clear alternative, say so briefly and stop.
+4. Otherwise give a concise adversarial pass:
+   - strongest objection
+   - hidden assumption
+   - non-obvious failure mode
+   - cheaper, simpler, or more reversible alternative
+   - required plan adjustment, open question, or explicit accept-risk decision
+
+## Output
+
+```markdown
+## Decision
+[What commitment is being challenged.]
+
+## Challenge
+- **Strongest objection:** ...
+- **Hidden assumption:** ...
+- **Non-obvious failure mode:** ...
+- **Alternative:** ...
+- **Plan impact:** ...
+```
+
+When there is no material challenge, use:
+
+```markdown
+## Decision
+[What was reviewed.]
+
+## Challenge
+No material challenge. The current plan appears to be the best available option because ...
+```

package/template/.agents/skills/dive-into-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dive-into-plan
-description: Interrogate a settled initiative plan for gaps, distribute into per-concern docs, and promote accepted decisions into decisions/. Use ONLY when the human explicitly invokes it ("dive into the plan", "distribute the plan"). Do not trigger automatically.
+description: Interrogate a settled initiative plan for gaps, distribute into per-concern docs, create local ADRs for active work, and promote approved implemented ADRs into decisions/. Use ONLY when the human explicitly invokes it ("dive into the plan", "distribute the plan"). Do not trigger automatically.
 ---
 
 # Dive Into Plan
@@ -9,19 +9,25 @@ Second half of durable planning, after `plan-with-context`. Requires a settled `
 
 ## Workflow
 
-1. Read initiative `README.md`, `plan.md`, and `context/project-profile.md` when it exists.
-2. **Interrogate** — ask pointed questions for surfaces the plan skipped (tests, e2e, IaC, CI/CD, config, ops, security, migration, reference impact). Record answers in `plan.md`; note deferred surfaces with reason.
+1. Read initiative `README.md`, `plan.md`, nearest `AGENTS.md`, `context/project-profile.md` when present, root `decisions/README.md` and relevant `decisions/indexes/` when present, and relevant local `context/**/decisions/`.
+2. **Interrogate** — ask pointed questions for surfaces the plan skipped (behavior, interface, architecture, tests, e2e, IaC, CI/CD, config, ops, rollback, security, data, ADRs, project profile impact, reference impact). Record answers in `plan.md`; note deferred surfaces with reason.
 3. **Distribute** — move settled truth from `plan.md` into initiative files (see templates under `context/_templates/initiative/` for each file's role):
    `spec.md`, `interface.md`, `architecture.md`, `testing.md`, `delivery.md`, `infrastructure.md`, `operations.md` (only when actionable), `backlog.md`, `release-doc-notes.md`. Mark N/A files explicitly.
-4. **Promote decisions** — for each accepted architecture/design choice: next `NNNN` in `decisions/` from `0000-template.md`, status Accepted, index row in `decisions/README.md`, origin link to initiative. Mark superseded decisions; never delete history.
-5. Update initiative `README.md` (status, decisions, implementation state).
+4. **Record ADRs** — create ADRs only for architecturally significant decisions: choices that cross team boundaries, have multiple credible options, or are costly to reverse. Keep proposed, recommended, planned, or in-progress ADRs under the relevant initiative `decisions/` folder.
+5. **Promote decisions** — move ADRs to root `decisions/` only when approved and implemented/accepted, or when the human explicitly says they are ready for root history. Assign the next `NNNN`, preserve or complete metadata (`Area`, `Scope`, `Tags`, `Supersedes`, `Superseded by`), update `decisions/README.md` and relevant `decisions/indexes/*.md`, and link back from the initiative.
+6. Update initiative `README.md` (status, decisions, implementation state).
 
 ## Boundary
 
+Use this after the agent's native planning is settled; it does not replace the
+agent's planning capability, but interrogates, distributes, and records durable
+artifacts from that plan.
 Do not edit `reference/`. Capture future reference impact in `release-doc-notes.md` only.
+Do not create ADRs for routine daily technical choices.
 
 ## Done when
 
 - Applicable surfaces grilled; answers in `plan.md`.
 - Settled truth not living only in `plan.md`.
-- Accepted decisions in repo-wide `decisions/` log.
+- ADR candidates were recorded locally, promoted to root `decisions/`, or left as normal initiative notes.
+- Promoted ADRs have complete metadata and current indexes.

package/template/.agents/skills/plan-with-context/SKILL.md

@@ -7,6 +7,13 @@ description: Draft a durable plan in an initiative plan.md covering the full cha
 
 Invocation-only. Produces `plan.md` for a later `dive-into-plan` pass.
 
+## Boundary
+
+Use the coding agent's native planning mode or planning capabilities to reason
+through the work. This skill does not replace that planning behavior; it
+extends it by grounding the plan in repository context and materializing the
+result in `context/initiatives/<slug>/plan.md`.
+
 ## Workflow
 
 1. Read nearest `AGENTS.md` and `context/project-profile.md` when it exists.
@@ -14,14 +21,23 @@ Invocation-only. Produces `plan.md` for a later `dive-into-plan` pass.
 3. Draft in `plan.md`: alignment, options, open questions. For each applicable surface, plan the work or mark N/A with reason:
    - Application code · unit/integration tests · e2e · IaC · CI/CD · config/secrets (names only) · observability/rollback · security/data · reference impact
 4. Ground items in real repo tooling (profile or direct inspection). Do not guess.
-5. Iterate with the human until direction is settled. Do not distribute yet.
+5. For architectural decisions, consult `decisions/README.md`, relevant `decisions/indexes/`, and local `context/**/decisions/` when present. Use metadata such as Area, Scope, Tags, and supersession links to avoid loading every ADR.
+6. Iterate with the human until direction is settled. Do not distribute yet.
+
+## ADR Guidance
+
+Consider an ADR only when a decision is architecturally significant: it crosses
+team boundaries, has multiple credible options, or is costly to reverse.
+Routine technical choices belong in `plan.md`, specs, or notes.
 
 ## Handoff
 
-When settled, invoke `dive-into-plan`.
+When a recommendation is ready, invoke `devils-advocate` if the human wants a
+challenge pass. When settled, invoke `dive-into-plan`.
 
 ## Done when
 
 - Initiative exists (or reason given why not).
 - `plan.md` covers every applicable surface.
+- Existing accepted and local ADRs were consulted where relevant.
 - Open questions visible; settled truth not frozen in `plan.md` alone.

package/template/.agents/skills/project-profile-baseline/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: project-profile-baseline
+description: Populate context/project-profile.md from source-backed repository facts. Use ONLY when the human explicitly asks to run the project profile, create a project profile, or establish a repository operating baseline.
+---
+
+# Project Profile Baseline
+
+Invocation-only. Populate `context/project-profile.md` with stable repo-wide
+operating facts.
+
+## Workflow
+
+1. Read nearest `AGENTS.md`, `context/README.md`, and existing `context/project-profile.md`.
+2. Inspect source-backed facts: manifests, lockfiles, runtime files, package scripts, test config, CI/CD, deploy scripts, IaC, observability config, generated-artifact owners, and documentation boundaries.
+3. Record repository shape, stack/runtime, commands, verification, delivery, infrastructure/configuration, operations, generated artifacts, docs boundaries, and known unknowns.
+4. Cite source paths where useful. Mark unknowns explicitly. Do not invent hidden commands or external pipeline behavior.
+5. Keep initiative-specific details out of the profile.
+
+## Done When
+
+- `context/project-profile.md` is populated from source-backed facts.
+- Unknowns and external assumptions are explicit.
+- Future agents can choose default commands and verification layers without rediscovering the repo.

package/template/.agents/skills/project-profile-refresh/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: project-profile-refresh
+description: Refresh context/project-profile.md from source-backed repository changes. Use ONLY when the human explicitly asks to update the project profile, refresh the repository baseline, or when a release documentation refresh such as reference-from-tags needs profile-relevant changes checked.
+---
+
+# Project Profile Refresh
+
+Invocation-only except as a pre-check during release documentation refreshes.
+Update `context/project-profile.md` only for stable repo-wide operating facts.
+
+## Workflow
+
+1. Read nearest `AGENTS.md`, existing `context/project-profile.md`, and `context/current.md` when present.
+2. If release tags are known, inspect profile-relevant changes:
+
+```bash
+git diff --name-status <base>..<target> -- <profile-relevant-paths>
+```
+
+3. Check manifests, lockfiles, runtime files, package scripts, test config, CI/CD, deploy scripts, IaC, observability config, generated artifacts, and documentation boundaries.
+4. Update only stable facts that changed. Preserve useful existing context.
+5. Do not update the profile for initiative-specific details, transient scaffolding, or unverified guesses.
+6. Mark unknowns explicitly and cite source paths where useful.
+
+## Done When
+
+- Stable repo-wide operating facts are current.
+- Initiative-specific and speculative details remain out of the profile.
+- Documentation refreshes can rely on the profile for source roots, commands, delivery, infrastructure, and generated artifacts.

package/template/AGENTS.md

@@ -10,7 +10,10 @@ Initiatives under [`context/initiatives/`](context/initiatives/) are disposable;
 
 Invocation-only skills — ask by name:
 
+- [`project-profile-baseline`](.agents/skills/project-profile-baseline/SKILL.md) — populate [`context/project-profile.md`](context/project-profile.md).
+- [`project-profile-refresh`](.agents/skills/project-profile-refresh/SKILL.md) — refresh stable repo-wide profile facts.
 - [`plan-with-context`](.agents/skills/plan-with-context/SKILL.md) — draft a plan in `plan.md`.
+- [`devils-advocate`](.agents/skills/devils-advocate/SKILL.md) — critique a draft plan before distribution.
 - [`dive-into-plan`](.agents/skills/dive-into-plan/SKILL.md) — interrogate gaps, distribute into per-concern docs, promote to [`decisions/`](decisions/).
 
 [`context/project-profile.md`](context/project-profile.md) — repo-wide stack, commands, and test facts when populated.

package/template/context/README.md

@@ -13,12 +13,16 @@ Persists elsewhere: [`../decisions/`](../decisions/) (durable log); `reference/`
 ## Flow
 
 ```text
-plan-with-context  ->  initiatives/<slug>/plan.md
-dive-into-plan     ->  per-concern docs + ../decisions/
+project-profile-baseline/refresh -> project-profile.md
+plan-with-context                -> initiatives/<slug>/plan.md
+devils-advocate                  -> critique before distribution
+dive-into-plan                   -> per-concern docs + ../decisions/
 ```
 
 1. Copy `_templates/initiative/` to `initiatives/<slug>/`.
-2. Invoke `plan-with-context` to draft `plan.md`.
-3. When settled, invoke `dive-into-plan` to distribute and promote decisions.
+2. Invoke `project-profile-baseline` when repo-wide commands and operating facts are not yet populated.
+3. Invoke `plan-with-context` to draft `plan.md`.
+4. Optionally invoke `devils-advocate` to challenge a meaningful recommendation.
+5. When settled, invoke `dive-into-plan` to distribute and promote decisions.
 
 Settled truth must not live only in `plan.md`. Do not edit `reference/` from here — use `release-doc-notes.md` for future reference impact.

package/template/context/_templates/initiative/README.md

@@ -14,7 +14,8 @@ Started: YYYY-MM-DD
 
 ## Decisions
 
-Promote accepted decisions to repo-wide [`decisions/`](../../../decisions/).
+Keep active ADR drafts in `decisions/`. Promote only approved, implemented or
+accepted architectural decisions to repo-wide [`decisions/`](../../../decisions/).
 
 - None yet.
 

package/template/context/_templates/initiative/decisions/ADR-0000-template.md

@@ -2,6 +2,11 @@
 
 Status: Proposed
 Date: YYYY-MM-DD
+Area: TBD
+Scope: TBD
+Tags: TBD
+Supersedes: None
+Superseded by: None
 
 ## Context
 
@@ -31,4 +36,3 @@ Negative or tradeoffs:
 ## Links
 
 - Related specs, PRs, tickets, discussions, or code paths.
-

package/template/decisions/0000-template.md

@@ -1,7 +1,12 @@
 # NNNN: Decision Title
 
-Status: Proposed
+Status: Accepted
 Date: YYYY-MM-DD
+Area: TBD
+Scope: TBD
+Tags: TBD
+Supersedes: None
+Superseded by: None
 
 ## Context
 

package/template/decisions/README.md

@@ -10,29 +10,55 @@ accepted decisions are promoted here where they stay findable.
 
 - One file per decision: `NNNN-short-title.md`, numbered in order.
 - Decisions are append-only. Do not rewrite history. When a decision changes,
-  add a new decision and mark the old one `Superseded by NNNN`.
-- Each decision records its status, date, context, the decision, consequences,
-  alternatives, and backlinks to where it was made.
+  add a new decision and link both directions with `Supersedes` and `Superseded by`.
+- Each decision records status, date, area, scope, tags, supersession, context,
+  decision, consequences, alternatives, origin, and links.
 - Copy [`0000-template.md`](0000-template.md) to start a new entry.
 
+## When To Write An ADR
+
+Write an ADR only for architecturally significant decisions: choices that cross
+team boundaries, have multiple credible options, or are costly to reverse.
+Routine implementation choices belong in initiative notes, specs, plans, or
+code review.
+
+## Metadata
+
+- `Area` is the most specific stable repo path or bounded product area.
+- `Scope` is the functional boundary affected by the decision.
+- `Tags` are lowercase retrieval terms.
+- `Supersedes` and `Superseded by` are explicit links or `None`.
+
 ## Statuses
 
-- `Proposed` - drafted, not yet accepted.
 - `Accepted` - in force.
 - `Superseded` - replaced by a later decision; kept for history.
 - `Deprecated` - no longer applies, with no direct replacement.
 
-To see what is currently in force, read the entries with status `Accepted`.
+Use `Proposed` or `Recommended` only in local `context/**/decisions/` folders
+while work is active or planned. To see what is currently in force, read root
+entries with status `Accepted`.
 
 ## Promotion From Initiatives
 
 The `dive-into-plan` skill promotes accepted decisions out of an
 initiative's scratch `context/initiatives/<slug>/decisions/` folder into this
-log, assigns the next number, and links back to the originating initiative and
-to the release tag, PR, or commit where the decision was made.
+log when the decision is accepted and implemented, or when a human explicitly
+says it is ready for root history. On promotion, assign the next number,
+preserve or complete metadata, update indexes, and link back to the origin.
+
+## Secondary Indexes
+
+Secondary indexes are navigation aids. They do not replace ADR files or this
+root index.
+
+- [Index guidance](indexes/README.md)
+- [By area](indexes/by-area.md)
+- [By status](indexes/by-status.md)
+- [By origin](indexes/by-origin.md)
 
 ## Index
 
-| Number | Title | Status | Date |
-| --- | --- | --- | --- |
-| 0000 | (template) | - | - |
+| Number | Title | Status | Date | Area | Scope | Origin |
+| --- | --- | --- | --- | --- | --- | --- |
+| 0000 | (template) | - | - | - | - | - |

package/template/decisions/indexes/README.md

@@ -0,0 +1,8 @@
+# Decision Indexes
+
+Secondary indexes help navigate a growing decision log. Keep them derived from
+root ADR metadata; the ADR files remain the source of truth.
+
+- [By area](by-area.md)
+- [By status](by-status.md)
+- [By origin](by-origin.md)

package/template/decisions/indexes/by-area.md

@@ -0,0 +1,5 @@
+# Decisions By Area
+
+| Area | Decisions |
+| --- | --- |
+| TBD | TBD |

package/template/decisions/indexes/by-origin.md

@@ -0,0 +1,5 @@
+# Decisions By Origin
+
+| Origin | Decisions |
+| --- | --- |
+| TBD | TBD |

package/template/decisions/indexes/by-status.md

@@ -0,0 +1,7 @@
+# Decisions By Status
+
+| Status | Decisions |
+| --- | --- |
+| Accepted | TBD |
+| Superseded | TBD |
+| Deprecated | TBD |