npm - code-anchored-context - Versions diffs - 0.2.0 → 0.2.2 - Mend

code-anchored-context 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/.agents/skills/code-anchored-context/SKILL.md +5 -5
package/AGENTS.md +12 -11
package/README.md +7 -7
package/bin/code-anchored-context.js +11 -10
package/context/AGENTS.md +2 -2
package/context/README.md +5 -9
package/context/_templates/initiative/README.md +2 -2
package/context/_templates/initiative/release-doc-notes.md +5 -6
package/context/_templates/planned-initiative/README.md +1 -1
package/context/_templates/planned-initiative/release-doc-notes.md +4 -5
package/context/terminology.md +2 -2
package/package.json +5 -9
package/product-docs/README.md +61 -0
package/{docs → product-docs}/_authoring/README.md +6 -6
package/{docs → product-docs}/_authoring/areas/README.md +2 -2
package/{docs → product-docs}/_authoring/areas/_template.md +5 -5
package/{docs → product-docs}/_authoring/terminology.md +1 -1
package/{docs → product-docs}/_authoring/workflow.md +36 -35
package/{docs → product-docs}/releases/index.md +2 -2
package/context/code-anchored-context-structure.md +0 -133
package/context/code-anchored-context-why.md +0 -80
package/context/code-anchored-context.html +0 -830
package/context/giving-ai-agents-context-around-code.md +0 -496
package/docs/.order +0 -2
package/docs/Welcome.md +0 -48
/package/{docs → product-docs}/_templates/area/README.md +0 -0
/package/{docs → product-docs}/_templates/area/features/feature-template.md +0 -0

package/context/code-anchored-context.html DELETED Viewed

@@ -1,830 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Code-Anchored Context</title>
-  <style>
-    :root {
-      color-scheme: light;
-      --ink: #17212b;
-      --muted: #52616f;
-      --line: #d6dde5;
-      --soft: #f5f7fa;
-      --panel: #ffffff;
-      --blue: #155e75;
-      --green: #2f6f4e;
-      --gold: #8a5a12;
-      --red: #9f3a38;
-      --violet: #6750a4;
-      --cyan-soft: #e8f5f8;
-      --green-soft: #ebf6ef;
-      --gold-soft: #fff4dc;
-      --red-soft: #fff0ef;
-      --violet-soft: #f2effb;
-      --shadow: 0 10px 25px rgba(23, 33, 43, 0.08);
-    }
-    * {
-      box-sizing: border-box;
-    }
-    html {
-      scroll-behavior: smooth;
-    }
-    body {
-      margin: 0;
-      font-family: "Segoe UI", Arial, sans-serif;
-      font-size: 16px;
-      line-height: 1.55;
-      color: var(--ink);
-      background: #ffffff;
-    }
-    a {
-      color: var(--blue);
-      text-decoration-thickness: 1px;
-      text-underline-offset: 3px;
-    }
-    code {
-      padding: 0.12rem 0.28rem;
-      border-radius: 4px;
-      background: #edf1f5;
-      font-family: Consolas, "Courier New", monospace;
-      font-size: 0.92em;
-    }
-    header {
-      border-bottom: 1px solid var(--line);
-      background:
-        linear-gradient(135deg, rgba(21, 94, 117, 0.08), rgba(47, 111, 78, 0.08)),
-        #ffffff;
-    }
-    .wrap {
-      width: min(1120px, calc(100% - 32px));
-      margin: 0 auto;
-    }
-    .hero {
-      display: grid;
-      grid-template-columns: minmax(0, 1fr) minmax(280px, 420px);
-      gap: 32px;
-      align-items: center;
-      padding: 48px 0 36px;
-    }
-    .eyebrow {
-      margin: 0 0 8px;
-      color: var(--blue);
-      font-weight: 700;
-      text-transform: uppercase;
-      font-size: 0.78rem;
-    }
-    h1 {
-      margin: 0;
-      font-size: 2.35rem;
-      line-height: 1.12;
-      font-weight: 760;
-    }
-    .lead {
-      margin: 18px 0 0;
-      max-width: 720px;
-      color: var(--muted);
-      font-size: 1.08rem;
-    }
-    .quick-links {
-      display: flex;
-      flex-wrap: wrap;
-      gap: 10px;
-      margin-top: 24px;
-    }
-    .quick-links a {
-      display: inline-flex;
-      align-items: center;
-      min-height: 36px;
-      padding: 6px 12px;
-      border: 1px solid var(--line);
-      border-radius: 6px;
-      background: #ffffff;
-      color: var(--ink);
-      text-decoration: none;
-      font-weight: 600;
-    }
-    .quick-links a:hover {
-      border-color: var(--blue);
-      color: var(--blue);
-    }
-    .map {
-      border: 1px solid var(--line);
-      border-radius: 8px;
-      background: var(--panel);
-      box-shadow: var(--shadow);
-      padding: 16px;
-    }
-    .map-title {
-      margin: 0 0 12px;
-      font-weight: 720;
-    }
-    .stack {
-      display: grid;
-      gap: 10px;
-    }
-    .node {
-      border: 1px solid var(--line);
-      border-left-width: 5px;
-      border-radius: 6px;
-      padding: 10px 12px;
-      background: #ffffff;
-    }
-    .node strong {
-      display: block;
-      margin-bottom: 2px;
-    }
-    .node span {
-      display: block;
-      color: var(--muted);
-      font-size: 0.9rem;
-    }
-    .node.program {
-      border-left-color: var(--violet);
-      background: var(--violet-soft);
-    }
-    .node.planned {
-      border-left-color: var(--gold);
-      background: var(--gold-soft);
-    }
-    .node.release {
-      border-left-color: var(--green);
-      background: var(--green-soft);
-    }
-    .node.backlog {
-      border-left-color: var(--red);
-      background: var(--red-soft);
-    }
-    .connector {
-      text-align: center;
-      color: var(--muted);
-      font-weight: 700;
-      line-height: 1;
-    }
-    nav {
-      position: sticky;
-      top: 0;
-      z-index: 10;
-      border-bottom: 1px solid var(--line);
-      background: rgba(255, 255, 255, 0.95);
-      backdrop-filter: blur(8px);
-    }
-    nav .wrap {
-      display: flex;
-      gap: 8px;
-      overflow-x: auto;
-      padding: 10px 0;
-    }
-    nav a {
-      flex: 0 0 auto;
-      padding: 6px 10px;
-      border-radius: 5px;
-      color: var(--muted);
-      text-decoration: none;
-      font-weight: 650;
-      font-size: 0.92rem;
-    }
-    nav a:hover {
-      background: var(--soft);
-      color: var(--ink);
-    }
-    main {
-      padding: 28px 0 64px;
-    }
-    section {
-      padding: 32px 0;
-      border-bottom: 1px solid var(--line);
-    }
-    section:last-child {
-      border-bottom: 0;
-    }
-    h2 {
-      margin: 0 0 12px;
-      font-size: 1.55rem;
-      line-height: 1.2;
-    }
-    h3 {
-      margin: 0 0 8px;
-      font-size: 1.05rem;
-    }
-    .section-intro {
-      max-width: 820px;
-      margin: 0 0 20px;
-      color: var(--muted);
-    }
-    .grid {
-      display: grid;
-      gap: 16px;
-    }
-    .grid.two {
-      grid-template-columns: repeat(2, minmax(0, 1fr));
-    }
-    .grid.three {
-      grid-template-columns: repeat(3, minmax(0, 1fr));
-    }
-    .grid.four {
-      grid-template-columns: repeat(4, minmax(0, 1fr));
-    }
-    .tile {
-      min-height: 100%;
-      border: 1px solid var(--line);
-      border-radius: 8px;
-      background: var(--panel);
-      padding: 16px;
-    }
-    .tile p {
-      margin: 0;
-      color: var(--muted);
-    }
-    .tile .path {
-      display: block;
-      margin-top: 12px;
-      color: var(--ink);
-      overflow-wrap: anywhere;
-    }
-    .accent-program {
-      border-top: 4px solid var(--violet);
-    }
-    .accent-planned {
-      border-top: 4px solid var(--gold);
-    }
-    .accent-release {
-      border-top: 4px solid var(--green);
-    }
-    .accent-backlog {
-      border-top: 4px solid var(--red);
-    }
-    .decision {
-      display: grid;
-      grid-template-columns: 220px minmax(0, 1fr) 240px;
-      border: 1px solid var(--line);
-      border-radius: 8px;
-      overflow: hidden;
-      background: #ffffff;
-    }
-    .decision + .decision {
-      margin-top: 10px;
-    }
-    .decision div {
-      padding: 12px 14px;
-      border-right: 1px solid var(--line);
-      min-width: 0;
-    }
-    .decision div:last-child {
-      border-right: 0;
-    }
-    .decision .question {
-      font-weight: 720;
-      background: var(--soft);
-    }
-    .decision .answer {
-      color: var(--muted);
-    }
-    .decision .target {
-      color: var(--ink);
-      overflow-wrap: anywhere;
-    }
-    .timeline {
-      display: grid;
-      grid-template-columns: repeat(5, minmax(0, 1fr));
-      gap: 10px;
-      align-items: stretch;
-    }
-    .step {
-      position: relative;
-      border: 1px solid var(--line);
-      border-radius: 8px;
-      padding: 14px;
-      background: #ffffff;
-      min-height: 150px;
-    }
-    .step-number {
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      width: 28px;
-      height: 28px;
-      margin-bottom: 10px;
-      border-radius: 50%;
-      background: var(--blue);
-      color: #ffffff;
-      font-weight: 750;
-      font-size: 0.88rem;
-    }
-    .step p {
-      margin: 0;
-      color: var(--muted);
-    }
-    .matrix {
-      width: 100%;
-      border-collapse: collapse;
-      border: 1px solid var(--line);
-      background: #ffffff;
-    }
-    .matrix th,
-    .matrix td {
-      padding: 12px;
-      border: 1px solid var(--line);
-      text-align: left;
-      vertical-align: top;
-    }
-    .matrix th {
-      background: var(--soft);
-    }
-    .note {
-      border-left: 5px solid var(--blue);
-      background: var(--cyan-soft);
-      padding: 14px 16px;
-      border-radius: 6px;
-      color: var(--ink);
-    }
-    .note p {
-      margin: 0;
-    }
-    footer {
-      padding: 28px 0 40px;
-      color: var(--muted);
-      background: var(--soft);
-    }
-    @media (max-width: 920px) {
-      .hero,
-      .grid.two,
-      .grid.three,
-      .grid.four,
-      .timeline {
-        grid-template-columns: 1fr;
-      }
-      .decision {
-        grid-template-columns: 1fr;
-      }
-      .decision div {
-        border-right: 0;
-        border-bottom: 1px solid var(--line);
-      }
-      .decision div:last-child {
-        border-bottom: 0;
-      }
-    }
-    @media print {
-      nav {
-        position: static;
-      }
-      .quick-links {
-        display: none;
-      }
-      body {
-        background: #ffffff;
-      }
-      section {
-        break-inside: avoid;
-      }
-    }
-  </style>
-</head>
-<body>
-  <header>
-    <div class="wrap hero">
-      <div>
-        <p class="eyebrow">Code-Anchored Context</p>
-        <h1>How humans and agents keep planning context useful over time</h1>
-        <p class="lead">
-          This brief explains where active work, future phases, durable program
-          context, deferred scope, delivery-surface context, and release
-          documentation notes belong.
-        </p>
-        <div class="quick-links" aria-label="Primary links">
-          <a href="README.md">Context README</a>
-          <a href="terminology.md">Terminology</a>
-          <a href="current.md">Current Release</a>
-          <a href="_templates/release-transition.md">Release Transition</a>
-        </div>
-      </div>
-      <aside class="map" aria-label="Context map">
-        <p class="map-title">Container model</p>
-        <div class="stack">
-          <div class="node program">
-            <strong>Program</strong>
-            <span>Cross-release parent effort</span>
-          </div>
-          <div class="connector">down</div>
-          <div class="node planned">
-            <strong>Planned initiative</strong>
-            <span>Scoped future child of a program</span>
-          </div>
-          <div class="connector">promotes to</div>
-          <div class="node release">
-            <strong>Release initiative</strong>
-            <span>Active or historical delivery slice</span>
-          </div>
-          <div class="connector">or defer to</div>
-          <div class="node backlog">
-            <strong>Context backlog item</strong>
-            <span>Isolated cut scope saved for later</span>
-          </div>
-        </div>
-      </aside>
-    </div>
-  </header>
-  <nav aria-label="Page sections">
-    <div class="wrap">
-      <a href="#why">Why</a>
-      <a href="#containers">Containers</a>
-      <a href="#decision-guide">Decision Guide</a>
-      <a href="#lifecycle">Lifecycle</a>
-      <a href="#delivery-surface">Delivery Surface</a>
-      <a href="#files">Files</a>
-      <a href="#release-transition">Release Transition</a>
-      <a href="#navigation">Navigation</a>
-    </div>
-  </nav>
-  <main class="wrap">
-    <section id="why">
-      <h2>Why This Exists</h2>
-      <p class="section-intro">
-        <code>docs/</code> is released product truth.
-        <code>context/</code> is working development truth. Code-Anchored
-        Context keeps agent context, planning, and decisions visible without
-        mixing in-progress thinking into released product documentation.
-      </p>
-      <div class="grid two">
-        <div class="tile accent-release">
-          <h3>Use <code>context/</code> while work is forming</h3>
-          <p>
-            Put plans, specs, ADRs, backlog, implementation context, future
-            phases, and release-doc notes here during normal development.
-          </p>
-        </div>
-        <div class="tile accent-program">
-          <h3>Use <code>docs/</code> only for shipped product docs</h3>
-          <p>
-            Product documentation remains release anchored. Working context
-            can feed it later through <code>release-doc-notes.md</code>.
-          </p>
-        </div>
-      </div>
-    </section>
-    <section id="containers">
-      <h2>The Four Work Containers</h2>
-      <p class="section-intro">
-        The core rule is simple: put knowledge where its lifetime matches the
-        work. Do not duplicate active plans into area-local folders.
-      </p>
-      <div class="grid four">
-        <div class="tile accent-program">
-          <h3>Program</h3>
-          <p>Cross-release parent effort with durable context, roadmap, phase history, and program-level ADRs.</p>
-          <code class="path">context/programs/&lt;program&gt;/</code>
-        </div>
-        <div class="tile accent-planned">
-          <h3>Planned initiative</h3>
-          <p>Scoped future delivery slice that belongs to a program but is not active yet.</p>
-          <code class="path">programs/&lt;program&gt;/planned-initiatives/&lt;initiative&gt;/</code>
-        </div>
-        <div class="tile accent-release">
-          <h3>Release initiative</h3>
-          <p>Active or historical delivery slice for a specific release.</p>
-          <code class="path">releases/&lt;version&gt;/initiatives/&lt;initiative&gt;/</code>
-        </div>
-        <div class="tile accent-backlog">
-          <h3>Backlog item</h3>
-          <p>Isolated work cut from scope and kept for possible later pickup.</p>
-          <code class="path">backlog/items/&lt;origin&gt;--&lt;item&gt;.md</code>
-        </div>
-      </div>
-    </section>
-    <section id="decision-guide">
-      <h2>Decision Guide</h2>
-      <p class="section-intro">
-        Use this when deciding where new context belongs.
-      </p>
-      <div class="decision">
-        <div class="question">Is this active in the current release?</div>
-        <div class="answer">Use a release initiative. It is the delivery surface for the current release.</div>
-        <div class="target"><code>context/releases/&lt;current&gt;/initiatives/</code></div>
-      </div>
-      <div class="decision">
-        <div class="question">Does this span releases or phases?</div>
-        <div class="answer">Use a program for durable context, roadmap, and program-level decisions.</div>
-        <div class="target"><code>context/programs/</code></div>
-      </div>
-      <div class="decision">
-        <div class="question">Is a future phase already clear?</div>
-        <div class="answer">Use a planned initiative so detail is preserved before the release becomes current.</div>
-        <div class="target"><code>programs/&lt;program&gt;/planned-initiatives/</code></div>
-      </div>
-      <div class="decision">
-        <div class="question">Was isolated work cut from scope?</div>
-        <div class="answer">Use a context backlog item. Link it back to the originating initiative.</div>
-        <div class="target"><code>context/backlog/items/</code></div>
-      </div>
-    </section>
-    <section id="lifecycle">
-      <h2>Lifecycle</h2>
-      <p class="section-intro">
-        The same work can move through several containers as it becomes more
-        concrete. Promotion is explicit and traceable.
-      </p>
-      <div class="timeline" aria-label="Context lifecycle">
-        <div class="step">
-          <span class="step-number">1</span>
-          <h3>Plan the arc</h3>
-          <p>Create or update a program when the effort spans releases.</p>
-        </div>
-        <div class="step">
-          <span class="step-number">2</span>
-          <h3>Scope future work</h3>
-          <p>Capture clear future phases as planned initiatives.</p>
-        </div>
-        <div class="step">
-          <span class="step-number">3</span>
-          <h3>Set current release</h3>
-          <p>Run the release transition checklist and promote matching planned initiatives.</p>
-        </div>
-        <div class="step">
-          <span class="step-number">4</span>
-          <h3>Deliver the slice</h3>
-          <p>Work in the release initiative and keep stable files current.</p>
-        </div>
-        <div class="step">
-          <span class="step-number">5</span>
-          <h3>Carry forward</h3>
-          <p>Move durable context to programs and isolated cut scope to backlog items.</p>
-        </div>
-      </div>
-    </section>
-    <section id="delivery-surface">
-      <h2>Delivery Surface</h2>
-      <p class="section-intro">
-        Working context describes the whole delivery system, not only the
-        product code. The structure follows delivery concerns, not specific
-        technologies or vendors.
-      </p>
-      <div class="grid three">
-        <div class="tile accent-release">
-          <h3><code>testing.md</code></h3>
-          <p>
-            Verification strategy, automated and manual coverage, test data,
-            regression risk, and release gates.
-          </p>
-        </div>
-        <div class="tile accent-program">
-          <h3><code>delivery.md</code></h3>
-          <p>
-            CI/CD behavior, build gates, deployment flow, environment
-            promotion, release toggles, and delivery automation.
-          </p>
-        </div>
-        <div class="tile accent-planned">
-          <h3><code>infrastructure.md</code></h3>
-          <p>
-            Environment shape, IaC, resources, networking, identity, storage,
-            secrets, and environment dependencies.
-          </p>
-        </div>
-      </div>
-      <div class="note" style="margin-top: 16px;">
-        <p>
-          <code>operations.md</code> is optional. Use it only for actionable
-          runtime, support, observability, rollback, or repair context.
-        </p>
-      </div>
-      <div class="note" style="margin-top: 16px;">
-        <p>
-          Mermaid diagrams are encouraged for flows and dependencies because
-          they remain readable Markdown for agents and render as visible
-          diagrams for humans.
-        </p>
-      </div>
-    </section>
-    <section id="files">
-      <h2>Initiative Files</h2>
-      <p class="section-intro">
-        <code>plan.md</code> is the working surface. The other files are where
-        stable conclusions belong.
-      </p>
-      <table class="matrix">
-        <thead>
-          <tr>
-            <th>File</th>
-            <th>Purpose</th>
-            <th>Stability</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <td><code>README.md</code></td>
-            <td>Entry point, status, scope, touched areas, and links.</td>
-            <td>Stable summary</td>
-          </tr>
-          <tr>
-            <td><code>plan.md</code></td>
-            <td>Live alignment, questions, options, and notes to promote.</td>
-            <td>Messy by design</td>
-          </tr>
-          <tr>
-            <td><code>spec.md</code></td>
-            <td>What the system should do.</td>
-            <td>Stable behavior</td>
-          </tr>
-          <tr>
-            <td><code>interface.md</code></td>
-            <td>How humans, clients, APIs, config, reports, or tools interact.</td>
-            <td>Stable surface</td>
-          </tr>
-          <tr>
-            <td><code>architecture.md</code></td>
-            <td>Internal shape, boundaries, flows, contracts, and data.</td>
-            <td>Stable design</td>
-          </tr>
-          <tr>
-            <td><code>testing.md</code></td>
-            <td>Verification strategy, coverage, test data, and release gates.</td>
-            <td>Stable verification</td>
-          </tr>
-          <tr>
-            <td><code>delivery.md</code></td>
-            <td>CI/CD, build behavior, deployment flow, promotion, and toggles.</td>
-            <td>Stable delivery</td>
-          </tr>
-          <tr>
-            <td><code>infrastructure.md</code></td>
-            <td>Environment shape, IaC, resources, identity, storage, and secrets.</td>
-            <td>Stable environment</td>
-          </tr>
-          <tr>
-            <td><code>operations.md</code></td>
-            <td>Actionable runtime support: observability, failure modes, rollback, and repair.</td>
-            <td>Optional operations</td>
-          </tr>
-          <tr>
-            <td><code>release-doc-notes.md</code></td>
-            <td>Product documentation impact for later release-doc refresh.</td>
-            <td>Bridge to docs</td>
-          </tr>
-        </tbody>
-      </table>
-      <div class="note" style="margin-top: 16px;">
-        <p>
-          Key rule: <code>plan.md</code> can be messy, but settled truth must
-          move into the stable files.
-        </p>
-      </div>
-    </section>
-    <section id="release-transition">
-      <h2>Release Transition</h2>
-      <p class="section-intro">
-        Changing <code>context/current.md</code> is a workflow. The agent
-        should materialize planned work for the new current release.
-      </p>
-      <table class="matrix">
-        <thead>
-          <tr>
-            <th>Step</th>
-            <th>What happens</th>
-            <th>Source</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <td>1</td>
-            <td>Update <code>current.md</code> and create the release folder if needed.</td>
-            <td><code>_templates/release-context/</code></td>
-          </tr>
-          <tr>
-            <td>2</td>
-            <td>Scan programs for planned initiatives targeting the new release.</td>
-            <td><code>programs/*/planned-initiatives/*/README.md</code></td>
-          </tr>
-          <tr>
-            <td>3</td>
-            <td>Promote matching planned initiatives into the release.</td>
-            <td><code>releases/&lt;version&gt;/initiatives/</code></td>
-          </tr>
-          <tr>
-            <td>4</td>
-            <td>Update links both ways and leave the planned initiative as history.</td>
-            <td><code>Status: Promoted</code></td>
-          </tr>
-        </tbody>
-      </table>
-    </section>
-    <section id="navigation">
-      <h2>Start Here</h2>
-      <p class="section-intro">
-        These are the first files a human or agent should open.
-      </p>
-      <div class="grid two">
-        <div class="tile">
-          <h3>For vocabulary</h3>
-          <p><a href="terminology.md">context/terminology.md</a></p>
-        </div>
-        <div class="tile">
-          <h3>For active release context</h3>
-          <p><a href="current.md">context/current.md</a></p>
-        </div>
-        <div class="tile">
-          <h3>For release transitions</h3>
-          <p><a href="_templates/release-transition.md">context/_templates/release-transition.md</a></p>
-        </div>
-        <div class="tile">
-          <h3>For agent behavior</h3>
-          <p><a href="../.agents/skills/code-anchored-context/SKILL.md">code-anchored-context skill</a></p>
-        </div>
-      </div>
-    </section>
-  </main>
-  <footer>
-    <div class="wrap">
-      Static brief for the repository <code>context/</code> context model.
-      Product documentation still lives under <code>docs/</code> and
-      follows its own release refresh rules.
-    </div>
-  </footer>
-</body>
-</html>