@delorenj/pjangler 1.4.5 → 1.4.6

package/README.md

@@ -275,7 +275,7 @@ the same envelope, including `baseline` and `exitCode`.
 | --- | --- | --- |
 | `registry` | the agent row itself: well-formedness, identity conflicts, correlation to a project record | `hermes.registry-parity` (**host-scoped** → `data.host`, unfiltered runs only†) |
 | `project_binding` | the row's board binding and whether the repository's `.project.json` agrees | the notebook and `sot.project-json` rules |
-| `template_scaffold` | the tracked template's gitlink, remote and cleanliness (fleet-wide); `scaffold.template_ref` is `unsupported` — a deployed role scaffold records none | every tracked-asset parity rule |
+| `template_scaffold` | the tracked template's gitlink, remote and cleanliness (fleet-wide), and **every managed role directory compared asset by asset against the template at the committed gitlink** — eight group observations per agent, typed per-asset `items`, `data.scaffold` and `agents[].scaffold` summaries (see *Scaffold parity* below) | every tracked-asset parity rule, plus a `scaffold-rule-disagreement` finding where `hermes.pm-scaffold` and the observer disagree |
 | `profile` | the generated profile directory, `lstat`ed and never followed; a symlink is a `fail`, because the contract declares `symlink_allowed: false` | `hermes.runtime-singleton`; `hermes.profile-wiring` (**host-scoped**) |
 | `runtime` | the role-local runtime directory derived from `role_dir` | `hermes.untracked-runtimes` |
 | `systemd` | `unsupported` — no systemd observer exists in this release; the unit names are the contract's expectations, carried as evidence | `systemd.sentinel` (**host-scoped**, unfiltered runs only†), never promoted to an agent |
@@ -304,6 +304,82 @@ Story 1.8 owns the systemd observer, 1.9 the live-process observer, and 1.10
 Bloodbank routing readiness. Until then those domains say so, by name, rather
 than disappearing.
 
+### Scaffold parity
+
+`template_scaffold` compares every managed role directory against the tracked
+template **at the gitlink this repository has committed** for
+`templates/hermes-agent` — git objects, never the submodule worktree, never a
+sibling clone, never a branch tip. The contract's `scaffold_manifest` block
+(schema 3) is the policy that says how to read that tree: which subdirectory
+holds the rendered files, how a rendered file is named, which registry fields
+feed each simple `{{ name }}` placeholder (`render_inputs`), which `scaffold.*`
+writable leaf owns each role-relative path (`groups`), which assets are
+compared for presence only and why (`presence_only`: `role.yaml`, `SOUL.md`),
+what may never appear in a template tree (`excluded_patterns`), and which
+role-local directory is ignored runtime nobody owns (`runtime_dir`).
+
+Each agent gets **eight observations, one per declared leaf** — `scaffold.role.yaml`,
+`scaffold.SOUL.md`, `scaffold.hermes`, `scaffold.momo`, `scaffold.sentinel.prompt.md`,
+`scaffold.gitignore`, `scaffold.scripts`, `scaffold.runtime-scaffold` — each
+`pass`, `fail` or `error`, with `observed: "<matching>/<owned> assets match"`
+and, on anything but a clean pass, a typed `items[]` list (capped at 100 per
+observation, the clip recorded in `truncated`). Every item carries a
+**role-relative path**, a kind, and a `desired`/`observed` pair that is a 12-hex
+git blob-id prefix or a type/mode word — never a file body, never an absolute
+path:
+
+| kind | meaning |
+| --- | --- |
+| `missing` | the template renders it; the role does not have it |
+| `stale-content` | different bytes, and the observed blob exists in the template's lineage — an older release |
+| `locally-modified` | different bytes, and no template version ever shipped them — somebody edited it |
+| `wrong-mode` | same bytes, executable bit differs |
+| `wrong-type` | a directory or symlink where a file was rendered, or the reverse |
+| `unsafe-symlink` | a symlink whose target is absolute or leaves the repository |
+| `unexpected-owned` | a tracked file inside an owned group the template did not render (a committed `.done-*`, an unrendered `.jinja`) — named, never proposed for deletion |
+| `incomplete` | this build could not decide: a render input is missing (`input-missing: display_name`), the template needs control flow (`render-unsupported`), or the bytes were unreadable |
+
+`stale-content` versus `locally-modified` is **lineage, not commit state**: a
+verbatim asset is stale when its observed blob exists in the template's object
+database, a rendered asset when it equals the render of one of the last twelve
+versions of its Jinja source. An uncommitted edit is the orthogonal `wip: true`
+flag on the item, and a drifted path that also carries one appears in
+`agents[].scaffold.wip_overlap`. Ignored runtime bytes, git-ignored entries and
+tracked files outside every owned group are **counted, never named**
+(`ignored_entries`, `wip_preserved`, `foreign_tracked`).
+
+**Source integrity is a host finding.** `scaffold.source` in `data.host` reads
+`pass` when the committed gitlink is stable (`ls-tree HEAD` and the index
+agree), its object exists, the submodule worktree is at it with no modified
+tracked file, the tree carries no excluded pattern, and every rendered path
+resolves to one declared group. Any other reading — `gitlink-missing`,
+`gitlink-unstable`, `source-uninitialized`, `source-missing-object`,
+`source-mismatched`, `source-dirty`, `source-contaminated`, `source-empty`,
+`manifest-uncovered:<path>` — is `error`, every selected agent's eight groups
+are `error`, and **desired bytes are never taken from the worktree as a
+fallback**. The same code is carried in `data.scaffold.source.integrity`.
+
+`data.scaffold.agents` counts every selected agent before any cap
+(`total_registered`, `selected`, `applicable`, `passing`, `drifted`,
+`incomplete`, `exception_authorized`, `unobserved`), and
+`data.scaffold.rule_agreement` says, under `--live`, how the observer and the
+`hermes.pm-scaffold` rule agreed over the subset both compare — a disagreement
+is a `scaffold-rule-disagreement` finding and both readings stand. An operator
+ruling on one agent's scaffold drift lives in
+`health_policy.agent_exceptions[]` (`domain`, `agent_id`, `reason`, `owner`):
+the drifted groups keep their `fail`, carry `justification.kind: "exception"`
+with that entry's own path, and the agent is counted `exception` rather than
+`unhealthy` — `health.healthy` is unaffected, exactly as for a permitted
+identity conflict. A contract with no `scaffold_manifest` still loads; the
+domain then reads `unsupported` under capability `scaffold.manifest`.
+
+`--domain template_scaffold` is the surface. A run scoped to any other domain
+spawns zero scaffold probes; `--agent <id>` reads only that agent's role
+directory while `data.scaffold.agents` keeps the fleet-wide totals. The role
+directory is the registry row's `role_dir`, defaulting to
+`<project_path>/agents/hermes/<role>` only when the row is silent
+(`agents[].scaffold.role_dir_source`), and must sit inside `project_path`.
+
 ### Seven states, one precedence
 
 | state | meaning |

package/contracts/fleet-contract.yaml

@@ -12,7 +12,11 @@
 #   agents.*      Hermes agent registry, per-agent rows
 #   gateways.*    Hermes agent registry, fleet-shared gateway block
 #   profiles.*    generated Hermes profile tree
-#   scaffold.*    tracked per-agent role scaffold
+#   scaffold.*    tracked per-agent role scaffold. Each leaf is mapped to the
+#                 role-relative path it owns by `scaffold_manifest.groups`, so
+#                 `scaffold.gitignore` means `.gitignore` and
+#                 `scaffold.sentinel.prompt.md` means `.scripts/sentinel.prompt.md`
+#                 -- the leaves name owned asset GROUPS, not store keys.
 #   units.*       systemd user units
 #   processes.*   observed Hermes processes (read-only)
 #
@@ -24,12 +28,12 @@
 # rather than be rejected as an unknown key, because rejecting it would hide the
 # very drift this contract exists to name.
 
-schema_version: 2
-contract_version: 1.1.0
+schema_version: 3
+contract_version: 1.2.0
 
 compatibility:
   min_schema_version: 1
-  max_schema_version: 2
+  max_schema_version: 3
 
 x-delonet/provenance:
   assessment: fleet-convergence-live-assessment-2026-08-31
@@ -393,13 +397,6 @@ health_policy:
         can dispatch to it is not. Routing readiness is a separate authority
         from the record and must never be inferred from it.
       owner_story: "1.10"
-    - domain: template_scaffold
-      capability: scaffold.template_ref
-      reason: >-
-        A deployed role scaffold records no template ref, so there is no
-        recorded value on this host to compare against the pinned gitlink and
-        none may be invented.
-      owner_story: "1.6"
     - domain: release_provenance
       capability: profile.render_generation
       reason: >-
@@ -459,6 +456,80 @@ health_policy:
       max_age_days: 365
       applies_to: registry
 
+  # An operator's ruling on ONE agent's drift in ONE domain. The drifted
+  # observation is still reported and still `fail`; what changes is that the
+  # agent is counted `exception` rather than `unhealthy`, exactly as a permitted
+  # identity conflict is. Ships empty on purpose: a ruling is written here when
+  # it is made, never inferred.
+  agent_exceptions: []
+
+# What a deployed role directory SHOULD contain, as POLICY about the tracked
+# template rather than a copy of it.
+#
+# The bytes come from git at the gitlink the parent repository has COMMITTED for
+# `template_submodule` -- never from the submodule worktree, never from a
+# sibling clone, never from a branch tip. This block says how to read that
+# tree: which subdirectory holds the rendered files, how a rendered file is
+# named, which registry fields feed each simple `{{ name }}` placeholder, which
+# `scaffold.*` writable leaf owns each role-relative path, which assets are
+# compared for presence only (and why), what must never appear in the tree,
+# and which role-local directory is ignored runtime state nobody owns.
+scaffold_manifest:
+  template_submodule: templates/hermes-agent
+  template_subdirectory: template
+  render_suffix: .jinja
+  # Placeholder name -> the field that feeds it. Only simple substitution is
+  # rendered; a template that needs control flow or a filter in a
+  # content-compared asset is `incomplete`, never rendered "as best it can".
+  render_inputs:
+    agent_id: agents.{agent_id}
+    role: agents.{agent_id}.role
+    target_repo: agents.{agent_id}.repo
+    display_name: agents.{agent_id}.display_name
+    ticket_provider: projects.{slug}.ticket_provider.type
+  # Declared leaf -> the role-relative path it owns. A trailing `/` owns a
+  # directory; longest prefix wins, so the rendered sentinel prompt inside the
+  # verbatim `.scripts/` tree has its own leaf. Every key is a writable field of
+  # `authorities.tracked_role_scaffold`, which is what makes those eight leaves
+  # real paths rather than invented ones.
+  groups:
+    scaffold.role.yaml: role.yaml
+    scaffold.SOUL.md: SOUL.md
+    scaffold.hermes: hermes
+    scaffold.momo: momo
+    scaffold.sentinel.prompt.md: .scripts/sentinel.prompt.md
+    scaffold.gitignore: .gitignore
+    scaffold.scripts: .scripts/
+    scaffold.runtime-scaffold: .runtime-scaffold/
+  # Compared for type and mode only. Policy, with a reason each, never a
+  # shortcut: any OTHER control-flow template is reported incomplete.
+  presence_only:
+    - path: role.yaml
+      reason: >-
+        Rendered with strftime and rewritten by deployment state (verified
+        channel identities, operator choices); Copier itself skips it when it
+        exists.
+    - path: SOUL.md
+      reason: >-
+        The operator's persona for the agent. The fanout writes it only when
+        absent, so its content is the operator's, not the template's.
+  # Never allowed in the tree at the gitlink. Matching a tracked file in a role
+  # directory makes it `unexpected-owned`; matching a template path makes the
+  # source `source-contaminated`.
+  excluded_patterns:
+    - "__pycache__/"
+    - "*.pyc"
+    - "*.pyo"
+    - "*.log"
+    - ".done-*"
+    - ".last-run"
+    - ".provision.log"
+    - ".plane-project-id"
+    - ".DS_Store"
+  # Ignored role-local runtime. Never compared, never named, never proposed
+  # for deletion; owned by nobody.
+  runtime_dir: runtime
+
 activation:
   states:
     - discovered