From b157cc432b1fd30b68d1c3daf6ced085e3a83531 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Thu, 26 Mar 2026 15:56:10 +0000
Subject: [PATCH] =?UTF-8?q?fix:=20Track=20addressables=20and=20observables?=
 =?UTF-8?q?=20in=20root=20AGENTS.md=20=E2=80=94=20gardener=20maintains=20l?=
 =?UTF-8?q?ifecycle=20(#744)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add mandatory Addressables and Observables sections to AGENTS.md so all
agents have a concrete inventory of what the factory has produced.

- AGENTS.md: add Addressables table (website, repo, skill, GitHub org)
  and empty Observables section
- run-gardener.toml: add portfolio lifecycle duties (add, promote,
  remove, flag) to the grooming step
- run-planner.toml: reference portfolio as planning input
- run-predictor.toml: reference portfolio for weakness detection
---
 AGENTS.md                   | 22 ++++++++++++++++++++++
 formulas/run-gardener.toml  | 16 ++++++++++++++++
 formulas/run-planner.toml   |  4 ++++
 formulas/run-predictor.toml |  3 +++
 4 files changed, 45 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 2b361cc..31b794d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -119,6 +119,28 @@ prevents merge conflicts between concurrent changes.
 
 ---
 
+## Addressables
+
+Concrete artifacts the factory has produced or is building. The gardener
+maintains this table during grooming — see `formulas/run-gardener.toml`.
+
+| Artifact | Location | Observable? |
+|----------|----------|-------------|
+| Website  | disinto.ai | No |
+| Repo     | codeberg.org/johba/disinto | Partial |
+| Skill    | ClawHub (in progress) | No |
+| GitHub org | github.com/Disinto | No |
+
+## Observables
+
+Addressables with measurement wired — the factory can read structured
+feedback from these. The gardener promotes addressables here once an
+evidence process is connected.
+
+None yet.
+
+---
+
 ## Architecture Decisions
 
 Humans write these. Agents read and enforce them.
diff --git a/formulas/run-gardener.toml b/formulas/run-gardener.toml
index b794b61..d39d9db 100644
--- a/formulas/run-gardener.toml
+++ b/formulas/run-gardener.toml
@@ -181,12 +181,28 @@ Sibling dependency rule (CRITICAL):
    Well-structured issues (both sections present) are left untouched —
    they are ready for dev-agent pickup.
 
+9. Portfolio lifecycle — maintain ## Addressables and ## Observables in AGENTS.md:
+   Read the current Addressables and Observables tables from AGENTS.md.
+
+   a. ADD: if a recently closed issue shipped a new deployment, listing,
+      package, or external presence not yet in the table, add a row.
+   b. PROMOTE: if an addressable now has measurement wired (an evidence
+      process reads from it), move it to the Observables section.
+   c. REMOVE: if an addressable was decommissioned (vision change
+      invalidated it, service shut down), remove the row and log why.
+   d. FLAG: if an addressable has been live > 2 weeks with Observable? = No
+      and no evidence process is planned, add a comment to the result file:
+        echo "ACTION: flagged addressable '<name>' — live >2 weeks, no observation path" >> "$RESULT_FILE"
+
+   Stage AGENTS.md if changed — the commit-and-pr step handles the actual commit.
+
 Processing order:
   1. Handle PRIORITY_blockers_starving_factory first — promote or resolve
   2. AD alignment check — close backlog issues that violate architecture decisions
   3. Quality gate — strip backlog from issues missing acceptance criteria or affected files
   4. Process tech-debt issues by score (impact/effort)
   5. Classify remaining items as dust or route to vault
+  6. Portfolio lifecycle — update addressables/observables tables
 
 Do NOT bundle dust yourself — the dust-bundling step handles accumulation,
 dedup, TTL expiry, and bundling into backlog issues.
diff --git a/formulas/run-planner.toml b/formulas/run-planner.toml
index cd89128..fbebb7b 100644
--- a/formulas/run-planner.toml
+++ b/formulas/run-planner.toml
@@ -107,6 +107,10 @@ and file-at-constraints steps.
 Read these inputs:
   - VISION.md, RESOURCES.md, planner memory (from preflight)
   - Graph report: orphans, cycles, thin_objectives, bottlenecks, disconnected
+  - Portfolio: ## Addressables and ## Observables tables in AGENTS.md —
+    use these as the concrete inventory of what the factory has produced.
+    Plan toward making addressables observable (measurement wired).
+    Vision changes (#733) should trigger a review of these tables.
   - Open issues (from Part A or fresh fetch)
   - Recently closed issues:
       curl -sf -H "Authorization: token $FORGE_TOKEN" \
diff --git a/formulas/run-predictor.toml b/formulas/run-predictor.toml
index c4da028..e427382 100644
--- a/formulas/run-predictor.toml
+++ b/formulas/run-predictor.toml
@@ -84,6 +84,9 @@ Look at EVERYTHING available to you:
 - The prerequisite tree — what does the planner claim is DONE? How much
   evidence backs that claim? A DONE item with 2 data points is weak.
 - Evidence directories — which are empty? Which are stale?
+- Portfolio — ## Addressables and ## Observables in AGENTS.md. Challenge
+  addressables that have no observation path. Are there addressables the
+  planner ignores? Observables with stale or missing evidence?
 - VISION.md — what does "launched" require? Is the project on track?
 - RESOURCES.md — what capabilities exist? What's missing?
 - Open issues — are things stuck? Bouncing? Starved?