merge: integrate architecture runtime ownership and Agent guidance

Author: Ancienttwo

.ai/harness/failures/task-sync-recovery-pre-fix.log

@@ -0,0 +1,25 @@
+bun test v1.4.2 (744846f84)
+
+tests/check-task-sync.test.ts:
+29 |   });
+30 | }
+31 | 
+32 | function reportedDigest(output: string): string {
+33 |   const match = output.match(/sha256:[0-9a-f]{64}/u);
+34 |   expect(match).not.toBeNull();
+                         ^
+error: expect(received).not.toBeNull()
+
+Received: null
+
+      at reportedDigest (/Users/kito/Projects/repo-harness-wt-architecture-agent-guidance/tests/check-task-sync.test.ts:34:21)
+      at <anonymous> (/Users/kito/Projects/repo-harness-wt-architecture-agent-guidance/tests/check-task-sync.test.ts:77:22)
+(fail) check-task-sync helper > a blocked resolver exposes exact evidence binding and the next run recovers without ignoring its exit code [939.05ms]
+
+ 0 pass
+ 33 filtered out
+ 1 fail
+ 9 expect() calls
+Ran 1 test across 1 file. [969.00ms]
+
+PRE_FIX_EXIT=1

assets/reference-configs/external-tooling.md

@@ -960,6 +960,19 @@ candidate verification may explicitly select the candidate package root.
 Missing or mismatching runtime dependencies still fail closed with no target-repo
 fallback. Project model, ownership and snapshot checks remain repository-local.
 
+SessionStart also gives the Agent read-only model coverage guidance under this
+global provider setting; no per-repo execution toggle is needed. It observes empty
+capability models, missing declared module documents, and tracked package roots
+with no capability match or a shared ancestor capability. These are bounded
+inspection prompts, not inferred semantic nodes. The Agent uses the
+`repo-harness-architecture` skill to inspect source evidence and decide boundaries
+within the authorized task, then creates nodes through archctx ChangeSets and
+runs the existing projection. An intentional umbrella is valid. Hooks do not
+write model YAML, and unrelated coverage findings remain advice. The manifest
+inventory is limited to Git-tracked `package.json` paths; this is not a complete
+semantic coverage audit for every language or untracked source tree. Inspection
+errors become SessionStart provider diagnostics instead of invented model facts.
+
 When enabled, Stop observes the Git changed set and coalesces eligible paths
 into one durable projection job, excludes
 ArchContext-owned `docs/architecture/**` and declared agent-context targets,

assets/skill-commands/repo-harness-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: repo-harness-architecture
-description: Resolves repo-harness architecture drift requests and updates architecture docs or diagrams without running full init, migrate, or upgrade.
-when_to_use: "repo-harness-architecture, architecture drift, architecture doc, architecture diagram, update architecture index, resolve architecture request"
+description: Handles architecture coverage guidance, capability registration and drift requests through the existing model and projection authorities.
+when_to_use: "repo-harness-architecture, architecture drift, architecture doc, architecture diagram, architecture model guidance, register capability, update architecture index, resolve architecture request"
 ---
 
 # repo-harness-architecture
@@ -12,7 +12,7 @@ architecture documentation, drift-request, or diagram pass.
 ## Protocol
 
 1. Confirm the target repo path and architecture scope.
-2. Inspect `docs/architecture/index.md` and pending files under `docs/architecture/requests/`.
+2. Inspect `docs/architecture/index.md`, `.archcontext/model/nodes/`, and pending files under `docs/architecture/requests/`. For architecture model guidance or a registration scope, follow the coverage procedure below even when no drift request exists.
 3. When the scope maps to repo code or config, resolve the capability with:
    - `repo-harness run capability-resolver match --repo <repo> --path <path> --format json`
 4. Update the smallest relevant architecture artifact:
@@ -28,9 +28,58 @@ architecture documentation, drift-request, or diagram pass.
    - `repo-harness run capability-resolver validate --repo <repo> --format text`
    - `repo-harness run check-task-workflow --strict` when repo workflow surfaces changed
 
+## Coverage and Agent-owned registration
+
+SessionStart automatically supplies read-only coverage observations when the global
+architecture provider is enabled and the repo selects `capability_source: archcontext`.
+An empty model, missing module docs, unmatched tracked package roots, or multiple
+packages sharing an ancestor capability are reasons to inspect, not proof that a new
+capability is required. Hooks do not decide responsibilities or write nodes.
+
+1. Read the existing semantic architecture docs and trace the relevant entrypoints,
+   dependencies, ownership and verification in source. Use CodeGraph when indexed.
+   Compare `repo-harness run capability-resolver list --format json` and
+   `repo-harness run capability-resolver match --path <source-path> --format json`.
+   Package layout is inventory evidence; it does not establish semantic boundaries.
+2. Give a concrete recommendation: retain an intentional umbrella, create a justified
+   capability, or restore a missing projection. Include source evidence, responsibility,
+   proposed prefixes, overlap with existing nodes, contract paths and verification.
+   Within already authorized architecture work, the Agent may decide and execute;
+   do not ask for the same approval again. During unrelated work, keep this as advice.
+3. For a new capability, author a complete `archcontext.node/v2` body with an
+   `id` of `capability.<domain>.<name>`, `kind: capability`, `status: active`, `name`,
+   `summary`, `responsibilities`, `source.include`, and `extensions` containing
+   `contractFiles.agents`, `contractFiles.claude`, `lspProfile`, and `verification`.
+   Use the current model schema and source evidence; do not copy an example's semantics.
+4. Resolve the owned archctx executable from
+   `repo-harness architecture-projection status --json` (`projectionProvider.binaryPath`).
+   Require ready status and use that binary with its supported Node runtime in the
+   target repo. Do not install a repo-local archctx or select an unrelated PATH copy.
+   The following `archctx` notation means that resolved executable:
+
+   ```text
+   archctx plan --id <unique-changeset-id> --path .archcontext/model/nodes/capability.<domain>.<name>.yaml --expected-hash missing --body <complete-YAML-as-one-argument> --format json
+   archctx apply --id <same-changeset-id> --approved --expected-worktree-digest <data.draft.base.worktreeDigest-from-plan> --format json
+   ```
+
+   Inspect the plan's full draft and preview before applying. Keep the same daemon
+   and ChangeSet ID; pass body via a structured process argument, not shell interpolation.
+   `--approved` records the authorized Agent decision; it does not grant extra scope.
+   If the worktree changed, re-plan and re-inspect. In archctx 0.5.10 this public `plan`
+   route creates one entity only. It is not an update route: when an existing node must
+   change, report the required update and use a supported typed ChangeSet authoring
+   surface if available; do not overwrite YAML or disguise an update as creation.
+5. Run `archctx validate --format json`, verify source matching with capability-resolver,
+   then `repo-harness architecture-projection plan --json --changed-path <node-path>`
+   and `repo-harness architecture-projection apply --json --changed-path <node-path>`.
+   Verify the expected module document exists and run the protocol's architecture checks.
+   Missing docs for an unchanged node need projection, not a duplicate node. Generated
+   module regions belong to archctx; preserve human-owned prose. Resolve any resulting
+   drift request through the normal request protocol.
+
 ## Failure Modes
 
-- If no pending architecture request exists, report `no-change` and do not invent one.
+- If no pending architecture request exists, do not invent one. Coverage and registration work can proceed independently; report `no-change` only after inspecting the requested coverage scope.
 - If capability resolution is ambiguous, stop at the matching paths and ask for a narrower scope.
 - If `check-architecture-sync.sh` blocks in strict mode, resolve or archive the pending request card for the touched capability before finishing the worktree.
 - If diagram validation fails, fix the Mermaid Markdown source or report the validation failure; do not substitute HTML.

assets/templates/helpers/check-task-sync.sh

@@ -356,6 +356,11 @@ for file in "${changed_files[@]}"; do
 done
 if ! workflow_profile="$("${repo_harness_cli[@]}" state resolve --json --field workflow_profile --target-path "${profile_paths[@]}")"; then
   echo "[task-sync] Workflow profile resolution failed; no lite exemption admitted." >&2
+  # Failed verification can itself block state resolution. Keep the failure,
+  # but expose the exact binding consumed above so recovery needs no cache reset
+  # or trust in a blocked resolver's profile field.
+  echo "[task-sync] To satisfy task-sync, record the current diff in a changed canonical workflow artifact with this exact line:" >&2
+  printf '> **Substantive Change SHA256**: `%s`\n' "$substantive_digest" >&2
   exit 1
 fi
 case "$workflow_profile" in

docs/architecture/.projection-manifest.json

@@ -5,12 +5,12 @@
   "sourceDigest": "sha256:b859983f97115344cb2d922ace1e8499d648eeca197ec66cf58b3775378e135d",
   "provenance": {
     "schemaVersion": "archcontext.architecture-docs-projection-provenance/v1",
-    "baseHeadSha": "3f286554da41d162b31bbab7f6074a9445f3a413",
-    "worktreeDigest": "sha256:c3280beaa6f2da5be639946261c624479085d0868b5e6dce8949ff5f0b590cc4",
-    "sourceTreeDigest": "sha256:f817fb2ad55621758fd2061c83b60bda6b9981919d5985a631853c222873c3de",
+    "baseHeadSha": "cd9ad5c64278f756bdad572b4f9616f2094d9047",
+    "worktreeDigest": "sha256:f4074cd24184ffe906e2d6e334c170018511bd8b703bfe0dd34ed7b8f6070b79",
+    "sourceTreeDigest": "sha256:dcee551d83782e235acfe1e58e90d13e3feb0fdddad8a41355f2dd3a46a8ede5",
     "modelDigest": "sha256:a11afbf16edf9e822bf02222d331beb8c050ef0b659ae605c23183193b10bbd5",
-    "codeGraphDigest": "sha256:3155b860fd48cb6dcfdbac8e30a39ababbd5a276826b2e8f19650d1b5bca2a3f",
-    "indexedWorktreeDigest": "sha256:0619e7e3883ff0f14586453364d7b9ffba18e6b10b2bb6b051c5894aab0b9314",
+    "codeGraphDigest": "sha256:c9f5e7b631032475667f7e1bb5bbd39b9df762147b31122c2e72586ca9b349ee",
+    "indexedWorktreeDigest": "sha256:931de978f90c7273324b8605bd9573fcca65cce57f1dd71a429a79f2197d4721",
     "rendererVersion": "archcontext.docs-renderer/v4",
     "layoutVersion": "archcontext.docs-layout/v1",
     "generatedFrom": {
@@ -19,9 +19,9 @@
       "codeGraphBinaryDigest": "sha256:e4be48573fdf16196ca0d2867be2790aa161534e9973dcb89bc70465100ea537",
       "codeGraphStatus": "ready"
     },
-    "projectionInputDigest": "sha256:1beecfcbb376bc7a0cd26847e34c0959430ec87a530b53115adc3557030e7b0d"
+    "projectionInputDigest": "sha256:80d51f9593ae0a6e6971398564582a39e977d13d2ab34bbc2f629b79b9552d72"
   },
-  "projectionDigest": "sha256:cbb69b9b78ea604e0f3414dd0ec4d77a35c2ebaea0de07c419047c2510ec24b9",
+  "projectionDigest": "sha256:83064d9423135d1a683185a2e696913fddf04cb2970654cfeea3ae4054413d3f",
   "semanticBaseline": {
     "semanticState": {
       "schemaVersion": "archcontext.architecture-semantic-state/v1",
@@ -709,12 +709,12 @@
     },
     "digests": {
       "modelDigest": "sha256:a11afbf16edf9e822bf02222d331beb8c050ef0b659ae605c23183193b10bbd5",
-      "sourceTreeDigest": "sha256:f817fb2ad55621758fd2061c83b60bda6b9981919d5985a631853c222873c3de",
+      "sourceTreeDigest": "sha256:dcee551d83782e235acfe1e58e90d13e3feb0fdddad8a41355f2dd3a46a8ede5",
       "flowProofDigest": "sha256:938dadfc988b732b6a67413ece104c062bb257ffd9f67caaf7db04dbc957b983",
-      "projectionDigest": "sha256:cbb69b9b78ea604e0f3414dd0ec4d77a35c2ebaea0de07c419047c2510ec24b9"
+      "projectionDigest": "sha256:83064d9423135d1a683185a2e696913fddf04cb2970654cfeea3ae4054413d3f"
     }
   },
-  "receiptDigest": "sha256:a8751028a6de02ab9a1184e43b0cada9d5830bdbbd7395c31efc7db7f9bc2fa5",
+  "receiptDigest": "sha256:2be80270e9a584aaea849cbf692196a1871dfbcd5e994016e8a6209ad8015924",
   "refreshSignalIds": [],
   "targetCount": 33,
   "fileCount": 33,

docs/reference-configs/external-tooling.md

@@ -960,6 +960,19 @@ candidate verification may explicitly select the candidate package root.
 Missing or mismatching runtime dependencies still fail closed with no target-repo
 fallback. Project model, ownership and snapshot checks remain repository-local.
 
+SessionStart also gives the Agent read-only model coverage guidance under this
+global provider setting; no per-repo execution toggle is needed. It observes empty
+capability models, missing declared module documents, and tracked package roots
+with no capability match or a shared ancestor capability. These are bounded
+inspection prompts, not inferred semantic nodes. The Agent uses the
+`repo-harness-architecture` skill to inspect source evidence and decide boundaries
+within the authorized task, then creates nodes through archctx ChangeSets and
+runs the existing projection. An intentional umbrella is valid. Hooks do not
+write model YAML, and unrelated coverage findings remain advice. The manifest
+inventory is limited to Git-tracked `package.json` paths; this is not a complete
+semantic coverage audit for every language or untracked source tree. Inspection
+errors become SessionStart provider diagnostics instead of invented model facts.
+
 When enabled, Stop observes the Git changed set and coalesces eligible paths
 into one durable projection job, excludes
 ArchContext-owned `docs/architecture/**` and declared agent-context targets,