code-anchored-context 0.2.0 → 0.2.2

package/{docs → product-docs}/_authoring/workflow.md

@@ -1,13 +1,13 @@
-# Docs Workflow
+# Product Docs Workflow
 
 This file defines how documentation is versioned, refreshed, and structured
 across the repo. It applies to all documented areas; area-specific guidance
 lives in [`areas/`](areas/).
 
-## When Docs Get Edited
+## When Product Docs Get Edited
 
 Doc refresh is an explicit, on-request activity, not a side effect of code
-work. Humans or agents touch `docs/` only when:
+work. Humans or agents touch `product-docs/` only when:
 
 - A human explicitly asks for a release-time refresh, typically after the
   release tag is cut and QA has signed off.
@@ -18,8 +18,8 @@ work. Humans or agents touch `docs/` only when:
 - A human asks to fix a demonstrable error in an existing page, such as a
   broken link or factual inaccuracy.
 
-Do not update docs as part of a feature PR, bug fix, refactor, or dependency
-bump. Mid-stream commits are partial work; "feature complete" is only
+Do not update product docs as part of a feature PR, bug fix, refactor, or
+dependency bump. Mid-stream commits are partial work; "feature complete" is only
 well-defined once the release is accepted.
 
 Agents: if you are working on a code change and notice a doc that looks
@@ -27,11 +27,11 @@ outdated, leave it alone. Flag the staleness in your summary or add it to the
 initiative's `release-doc-notes.md`, but do not edit the doc as part of the
 current change unless explicitly asked.
 
-## Docs Modes
+## Product Docs Modes
 
-There are two valid ways to introduce or maintain `docs/`.
+There are two valid ways to introduce or maintain `product-docs/`.
 
-### Baseline Docs
+### Baseline Product Docs
 
 Use this mode only when a human explicitly asks to document the current system
 as a starting point. This is common when adopting the template in an existing
@@ -42,54 +42,55 @@ When creating a baseline:
 1. Confirm the scope: whole repo, one product area, one feature family, or one
    operational surface.
 2. Create or update the matching area guide under
-   `docs/_authoring/areas/` before writing product-facing pages.
+   `product-docs/_authoring/areas/` before writing product-facing pages.
 3. Document stable, currently accepted behavior from the current branch,
    current tag, or explicit reference point named by the human.
 4. Prefer broad, accurate coverage over exhaustive implementation detail.
-5. Record the baseline reference in `docs/releases/index.md`. If
+5. Record the baseline reference in `product-docs/releases/index.md`. If
    there is no release tag yet, use the commit, branch, date, or human-named
    baseline label that was used as the source.
-6. Leave uncertain or future behavior out of `docs/`. Capture open
+6. Leave uncertain or future behavior out of `product-docs/`. Capture open
    questions in `context/` or in the area authoring guide.
 
-Baseline docs are a snapshot of the system as adopted; they are not a promise
-that every undocumented behavior is unimportant.
+Baseline product docs are a snapshot of the system as adopted; they are not a
+promise that every undocumented behavior is unimportant.
 
-### Release-Forward Docs
+### Release-Forward Product Docs
 
 Use this mode when the team chooses not to create a full baseline. In this
-mode, `docs/` may start sparse. Agents capture documentation impact
+mode, `product-docs/` may start sparse. Agents capture documentation impact
 in initiative `release-doc-notes.md` during development, then update product
-docs only at explicit release-refresh time.
+product docs only at explicit release-refresh time.
 
 This is valid when a full baseline would be too expensive. The documentation
 becomes complete incrementally around behavior the team changes and releases.
 
 ## Cadence And Versioning
 
-Docs live under `docs/`. After any explicit baseline pass, they are
-refreshed once per release, at git-tag time, after release acceptance. Release
-docs are anchored to the release tag; the docs at tag `release/v1_2_3`
-describe the behavior of that release.
+Product docs live under `product-docs/`. After any explicit baseline pass,
+they are refreshed once per release, at git-tag time, after release acceptance.
+Product docs are anchored to the release tag; product docs at tag
+`release/v1_2_3` describe the behavior of that release.
 
 Default tag names follow the convention `release/vMAJOR_MINOR_PATCH` and match
 the release branch name. If a project uses a different release convention,
 document it here before the first refresh. If the first documentation pass is
 a baseline without a tag, record the baseline reference in
-`docs/releases/index.md`.
+`product-docs/releases/index.md`.
 
 ## Audience
 
-Docs are written for non-developer technical readers by default: QA, product
-owners, solution owners, support engineers, customer engineers, or operators.
-Adjust this only when the project explicitly defines a different audience.
+Product docs are written for non-developer technical readers by default: QA,
+product owners, solution owners, support engineers, customer engineers, or
+operators. Adjust this only when the project explicitly defines a different
+audience.
 
 - Describe behavior, inputs, outputs, permissions, error conditions, and
   business rules in domain language.
 - Avoid code snippets, private type names, SQL, and framework jargon unless
   the concept has no plain-language equivalent.
-- For readers who need more depth than the docs provide, link to the source
-  rather than replicating the implementation in prose.
+- For readers who need more depth than the product docs provide, link to the
+  source rather than replicating the implementation in prose.
 
 ## Writing Focus
 
@@ -100,10 +101,10 @@ or business process can observe. Add technical detail only when it affects
 released behavior, configuration, permissions, data, integrations, errors,
 support, operations, or auditability.
 
-Docs should be product-readable first and technically anchored
-second. They can feed release notes, but they are more durable than release notes:
-release notes summarize what changed, while `docs/` describes what
-the accepted system does as of a release or baseline.
+Product docs should be product-readable first and technically anchored
+second. They can feed release notes, but they are more durable than release
+notes: release notes summarize what changed, while `product-docs/` describes
+what the accepted system does as of a release or baseline.
 
 Use progressive depth:
 
@@ -127,7 +128,7 @@ Every documented area has two layers:
 Standard per-area layout:
 
 ```text
-docs/<Area>/
+product-docs/<Area>/
   README.md
   features/
     <feature>.md
@@ -169,18 +170,18 @@ user-facing or operator-facing entry point. Cross-link from the other areas.
 
 ## Release-Time Doc Refresh
 
-When invoked to refresh docs for a release:
+When invoked to refresh product docs for a release:
 
 1. Work from the diff `<previous-release-tag>..HEAD`, scoped to one area at a
    time.
-2. Read the matching area guide in `docs/_authoring/areas/`.
+2. Read the matching area guide in `product-docs/_authoring/areas/`.
 3. Read relevant initiative `release-doc-notes.md` files under
    `context/releases/<release>/initiatives/`.
 4. Update the area's `README.md` if the high-level picture changed.
 5. Update feature pages for behavior that changed.
 6. Ignore pure refactors, internal renames, test-only changes, formatting,
    lint fixes, and dependency bumps with no behavior change.
-7. Append one row to `docs/releases/index.md`.
+7. Append one row to `product-docs/releases/index.md`.
 
 ## Source Order
 
@@ -189,7 +190,7 @@ source inspection:
 
 1. Previous release tag to current release diff.
 2. Relevant initiative `release-doc-notes.md` files.
-3. Matching area guide under `docs/_authoring/areas/`.
+3. Matching area guide under `product-docs/_authoring/areas/`.
 4. Existing product documentation.
 5. Source code, tests, config, CI/CD, infrastructure, and generated artifacts
    only as needed to verify shipped behavior.

package/{docs → product-docs}/releases/index.md

@@ -1,9 +1,9 @@
-# Release Docs Index
+# Product Docs Release Index
 
 One row per tagged release. Tag names default to `release/vMAJOR_MINOR_PATCH`
 unless the project documents a different convention.
 
-Docs at a given tag describe the behavior of that release.
+Product docs at a given tag describe the behavior of that release.
 
 | Tag | Date | Areas refreshed | Owner | Summary |
 | --- | --- | --- | --- | --- |

package/context/code-anchored-context-structure.md

@@ -1,133 +0,0 @@
-# Code-Anchored Context: The Structure
-
-This is the companion to the
-[reasoning article](code-anchored-context-why.md). It covers how working
-context is laid out so both humans and agents can navigate it.
-
-## Denormalize Navigation, Not Knowledge
-
-Agents and IDEs do not always open from the repo root. They may start in
-product code, CI/CD config, infrastructure code, generated artifacts, or a
-nested app. If all guidance lives at the top, it gets missed. If each area
-keeps its own plans, cross-project work fragments.
-
-> Denormalize navigation, not knowledge.
-
-Local `AGENTS.md` files point agents toward the right place. But plans, specs,
-ADRs, release context, testing strategy, delivery notes, and infrastructure
-context live centrally under `context/`.
-
-## The Core Model
-
-Vocabulary is captured in `context/terminology.md`. The main containers:
-
-```text
-Program                  Long-lived multi-release effort.
-Planned initiative       A scoped future slice inside a program.
-Release initiative       Active or historical work for a specific release.
-Context backlog item     Isolated work cut from scope but worth preserving.
-Program release slice    What a release contributes to a program.
-```
-
-Each kind of context gets a home:
-
-```text
-context/
-  terminology.md
-  current.md
-  programs/
-  backlog/
-  releases/
-  _templates/
-```
-
-Structure follows delivery concerns, not technologies. Name a file for the
-knowledge it preserves, not the tool that produced it.
-
-## Release Initiatives
-
-The main unit of active delivery:
-
-```text
-context/releases/<version>/initiatives/<initiative>/
-  README.md   plan.md   spec.md   interface.md   architecture.md
-  testing.md  delivery.md  infrastructure.md  operations.md
-  backlog.md  decisions/  release-doc-notes.md
-```
-
-The most important file is `plan.md` — the working alignment space. It can be
-messy with notes, options, and tradeoffs, with one rule:
-
-> `plan.md` may be messy, but it must not be the only place settled truth lives.
-
-Once something stabilizes, it moves to a durable file:
-
-```text
-spec.md              What the system should do.
-interface.md         How clients, APIs, config, or tools interact with it.
-architecture.md      Internal shape, boundaries, data flow, tradeoffs.
-testing.md           Verification strategy, coverage, gates, known gaps.
-delivery.md          CI/CD, build, deployment, promotion, release toggles.
-infrastructure.md    Environments, IaC, networking, identity, storage, secrets.
-operations.md        Runtime/support: observability, failure modes, rollback.
-backlog.md           Trackable work items and progress.
-decisions/           Durable decisions and consequences (ADRs).
-release-doc-notes.md What should become product documentation later.
-```
-
-Not every initiative needs every file. The point is to give stable knowledge a
-place to land — testing, delivery, and infrastructure are first-class context,
-not afterthoughts buried in pipeline files or PRs.
-
-## Programs And Planned Initiatives
-
-Some work is bigger than one release. A program holds durable multi-release
-context:
-
-```text
-context/programs/<program>/
-  README.md  context.md  roadmap.md  backlog.md
-  decisions/  planned-initiatives/  releases/
-```
-
-Future work that is clear enough to plan — but whose target release is not
-current yet — becomes a planned initiative:
-
-```text
-context/programs/<program>/planned-initiatives/<initiative>/
-```
-
-When the target release becomes current, it is promoted into
-`context/releases/<version>/initiatives/<initiative>/`. Promotion is
-explicit; the original planned initiative stays as historical context.
-
-## Context Backlog
-
-Work cut from scope but worth preserving — when it doesn't justify a program or
-planned initiative — lives in:
-
-```text
-context/backlog/items/<originating-initiative>--<item>.md
-```
-
-Each item records where it came from, why it was deferred, future value, and
-re-entry criteria. If picked up later, it is marked promoted and linked — never
-silently rewritten.
-
-## Release Transitions
-
-Changing the current release is more than editing a pointer. When
-`context/current.md` moves to a new release, agents should scan program
-planned initiatives, promote items targeting the new release into the release
-folder, update links both ways, and preserve the originals as history.
-
-```mermaid
-flowchart TD
-  Start["Set a new current release"]
-  Scan["Scan program planned initiatives"]
-  Promote["Promote into releases/<version>/initiatives/"]
-  Link["Update links both ways"]
-  Preserve["Preserve original as history"]
-
-  Start --> Scan --> Promote --> Link --> Preserve
-```

package/context/code-anchored-context-why.md

@@ -1,80 +0,0 @@
-# Code-Anchored Context: Giving AI Agents The Context Around The Code
-
-AI agents are good at reading repositories, editing files, and following
-instructions. But in large codebases, code is not the whole story.
-
-The hard part is not whether an agent can change a file. It is whether it
-understands the intent behind the change, the current release scope, the
-decisions already made, the work deliberately deferred, how the change should
-be verified, how it ships, and what infrastructure or operational risks
-surround it.
-
-That context usually exists — in chats, tickets, pull request comments,
-planning notes, and people's heads — but agents need it in a structured,
-discoverable form.
-
-## Docs vs Working Context
-
-This is why I separate **released product documentation** from **working
-context**:
-
-```text
-docs/   What shipped.
-context/      What we are planning, building, deciding, testing,
-                  shipping, hosting, deferring, and learning.
-```
-
-Product documentation stays stable and release-accurate: it describes a known
-release, not an unfinished branch. Working context is allowed to evolve —
-it is where humans and agents work through ambiguity.
-
-## The Principle
-
-I think of this as **Code-Anchored Context**. Not a methodology — a rule of
-thumb:
-
-> Keep truth as close to code as possible, and keep the surrounding context
-> structured enough that both humans and agents can find it.
-
-It is opinionated on purpose: prefer repository-local context, explicit
-lifetimes, and navigable structure over scattered notes that only make sense
-to the people who were in the room. Repository-local context scales beyond one
-person.
-
-## Why It Travels
-
-When context is materialized in the repository, it stops being tied to one
-chat transcript, IDE, agent, or session. A team can switch tools without
-losing the trail of why the system is shaped the way it is. The next human or
-agent opens the repo and continues from the same accumulated understanding
-instead of reconstructing it from memory.
-
-```mermaid
-flowchart LR
-  Code["Codebase<br/>What exists"]
-  Dev["context/<br/>What is being planned, built, decided, tested, shipped, deferred"]
-  Docs["docs/<br/>What shipped in a known release"]
-  Agents["Agents and humans"]
-
-  Agents --> Code
-  Agents --> Dev
-  Dev -->|"release-doc-notes.md captures future docs impact"| Docs
-  Docs -->|"stable release truth"| Agents
-```
-
-## Why It Matters
-
-Code-Anchored Context is context continuity. It helps agents and humans answer:
-
-- What is active now, and what belongs to a future phase?
-- What was cut from scope, and why was a decision made?
-- How should this be tested, and what gates must pass before release?
-- How will it ship, and what infrastructure does it depend on?
-- What should become product documentation later?
-- What reasoning needs to survive a change of IDE, agent, or session?
-
-Code tells an agent *what exists*. Working context tells it *why* it
-exists, where it is going, what has been decided, and what was left for later.
-
-For the concrete folder layout, see the companion article,
-[Code-Anchored Context: The Structure](code-anchored-context-structure.md).