Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

fix(apm-orchestrate): description/delegation FAILs and confirmed add-package mapping bug #120

New Issue
Closed
opened 2026-08-30 19:42:24 +00:00 by Claude · 2 comments
Claude commented 2026-08-30 19:42:24 +00:00
Collaborator
Copy Link

Summary

Pre-existing, out-of-scope defects in plugins/kyberforge/.apm/agents/apm-orchestrate.agent.md, surfaced by an independent post-closure audit of #99 (agent-audit + skill-audit re-run against every skill/agent changed on refactor/adr0020-skill-retrofit). All predate that branch (the file was authored in 5e23250, before #99 started) and are explicitly out of ADR-0020's skill-scoped gate, per #99's closing comment — filed separately rather than folded into #99, following the same pattern as #107-#119.

Findings

1. agent-audit deterministic gate: FAIL (3 fails, 2 suggestions).

  • FAIL — description opens with catalogue phrasing ("Orchestrates apm package/marketplace operations...") rather than a trigger clause, and packs capability enumeration plus composition/implementation detail ("coordinated across the apm-workflow skill with safety gates, session context, and structured results").
  • FAIL (delegation) — the Hard Rule at line 23 ("apm.yml's type: field constrains what .apm/ may contain — set type: before any primitive content is added") restates apm-workflow/references/configure.md's Gotcha verbatim, with no citation and no orchestrator-side enforceable action — unlike the file's other four Hard Rules, which do cite their source skill.
  • SUGGESTION — description is 386 chars (over the 250 target, under the 400 FAIL ceiling).
  • SUGGESTION — description has no boundary clause.

2. Confirmed add-package mapping bug. The Inputs table (line ~41) describes the add-package operation as mapping to "apm marketplace package add — register a local package into a marketplace being built." But apm-workflow/references/marketplace.md's own Gotcha states apm marketplace package add only accepts remote references (owner/repo, a host URL, or a full URL) — it cannot register a local path. Registering a local package requires hand-editing marketplace.packages[] directly. This directly contradicts the file's own Hard Rule two lines above the Inputs table, which correctly cites this exact constraint. An agent following the Inputs table's mapping for a local-package request will dispatch the wrong operation.

Suggested fix

  • Rewrite the description to trigger + one capability + boundary, per ADR-0020 shape (agents get the same description gates as skills, just no body-word gate).
  • Either cite apm-workflow/references/configure.md from the Hard Rule, or replace it with a boundary/delegation note per ADR-0020's agent delegation-check rule (an agent body restating a skill's owned procedure is a FAIL; the fix is "invoke <skill> instead").
  • Fix the Inputs table's add-package mapping to reflect that it only works for remote package references, and route a local-package request to the hand-edit path (or to apm-workflow's edit-config operation) instead.

Related: #99 (closing comment), #107-#119 (other retrofit-adjacent gate/content defects filed the same way).

## Summary Pre-existing, out-of-scope defects in `plugins/kyberforge/.apm/agents/apm-orchestrate.agent.md`, surfaced by an independent post-closure audit of #99 (agent-audit + skill-audit re-run against every skill/agent changed on `refactor/adr0020-skill-retrofit`). All predate that branch (the file was authored in `5e23250`, before #99 started) and are explicitly out of ADR-0020's skill-scoped gate, per #99's closing comment — filed separately rather than folded into #99, following the same pattern as #107-#119. ## Findings **1. `agent-audit` deterministic gate: FAIL (3 fails, 2 suggestions).** - FAIL — description opens with catalogue phrasing ("Orchestrates apm package/marketplace operations...") rather than a trigger clause, and packs capability enumeration plus composition/implementation detail ("coordinated across the apm-workflow skill with safety gates, session context, and structured results"). - FAIL (delegation) — the Hard Rule at line 23 ("`apm.yml`'s `type:` field constrains what `.apm/` may contain — set `type:` before any primitive content is added") restates `apm-workflow/references/configure.md`'s Gotcha verbatim, with no citation and no orchestrator-side enforceable action — unlike the file's other four Hard Rules, which do cite their source skill. - SUGGESTION — description is 386 chars (over the 250 target, under the 400 FAIL ceiling). - SUGGESTION — description has no boundary clause. **2. Confirmed add-package mapping bug.** The Inputs table (line ~41) describes the `add-package` operation as mapping to "`apm marketplace package add` — register a local package into a marketplace being built." But `apm-workflow/references/marketplace.md`'s own Gotcha states `apm marketplace package add` only accepts remote references (`owner/repo`, a host URL, or a full URL) — it cannot register a local path. Registering a local package requires hand-editing `marketplace.packages[]` directly. This directly contradicts the file's own Hard Rule two lines above the Inputs table, which correctly cites this exact constraint. An agent following the Inputs table's mapping for a local-package request will dispatch the wrong operation. ## Suggested fix - Rewrite the description to trigger + one capability + boundary, per ADR-0020 shape (agents get the same description gates as skills, just no body-word gate). - Either cite `apm-workflow/references/configure.md` from the Hard Rule, or replace it with a boundary/delegation note per ADR-0020's agent delegation-check rule (an agent body restating a skill's owned procedure is a FAIL; the fix is "invoke `<skill>` instead"). - Fix the Inputs table's `add-package` mapping to reflect that it only works for remote package references, and route a local-package request to the hand-edit path (or to `apm-workflow`'s `edit-config` operation) instead. Related: #99 (closing comment), #107-#119 (other retrofit-adjacent gate/content defects filed the same way).
Claude added the Kind/Bug
Priority
Medium
3
 labels 2026-08-30 19:42:24 +00:00
Claude commented 2026-08-31 08:11:10 +00:00
Author
Collaborator
Copy Link

All three findings fixed on refactor/adr0020-skill-retrofit (not yet pushed — the PR body will carry the close)

1. Description: 386 → 224 characters

Rewritten to trigger + one capability + boundary, per ADR-0020 shape:

Use when an agent caller needs a multi-step apm package or marketplace operation dispatched and safety-gated, including the same operation fanned out across a monorepo. Not apm binary or agent-runtime install -> apm-install.

The catalogue opener is gone, the composition/implementation detail ("coordinated across the apm-workflow skill with safety gates, session context, and structured results") is gone, and the boundary target apm-install resolves. scripts/skill-size-check.sh on main reported a description SUGGESTION and a missing boundary clause; on the branch both are silent.

2. Delegation FAIL: the type: Hard Rule

Replaced with a one-clause orchestrator-side refusal:

type: correctness is apm-workflow's call — do not pre-set or second-guess it.

That is an action this orchestrator can take, not a restatement of a rule it does not own.

Worth recording, since it is not in the report: the copy was not merely uncited, it had drifted. It asserted that type: "constrains what .apm/ may contain", which is false — type: selects processing (instructions / skill / prompts / hybrid, per PackageContentType) and validates nothing against the primitives on disk. The agent's copy also dropped the four-value enumeration the skill-side gotcha carried. The skill-side text was corrected on this branch in 164948a ("type: selects processing, it does not validate content"), so the agent copy was restating a rule that was itself wrong.

3. add-package mapping bug

The Inputs row now reads:

add-package (→ apm marketplace package add — register a remote package reference (owner/repo, host URL, or full URL) into a marketplace being built; it rejects a local path, so a local package is not this operation — route it to edit-config instead)

and edit-config's own scope was widened to admit the case it now receives: "...or adding/removing a marketplace.packages[] entry, including the local-package registration apm marketplace package add cannot perform". Previously edit-config only mentioned removing an entry, so routing there would have been routing into a scope that did not cover the request.

Two further defects fixed beyond the report

  • The body carried the same numbered sequence twice. A 7-step When invoked, you: list at line 28 and an 8-step ## Process at line 50 described the same dispatch with different wording — including two different accounts of the parallel-fan-out rule. The When invoked copy is deleted; ## Process is the single sequence. Body went 1080 → 876 words on the same counter. (Agents take no body-word gate by design, per agent-audit/scripts/validate.sh — noting the figures, not claiming a gate finding.)
  • ## Process step 2 named the deleted rule's old semantics. It listed "type: ordering" among the Hard rules to check, which was the scaffolding-order rule that no longer exists. Now reads "type: delegation".

bash scripts/check-apm-agents-valid.sh passes over all four plugin-scope agent files.

## All three findings fixed on `refactor/adr0020-skill-retrofit` (not yet pushed — the PR body will carry the close) ### 1. Description: 386 → 224 characters Rewritten to trigger + one capability + boundary, per ADR-0020 shape: > Use when an agent caller needs a multi-step apm package or marketplace operation dispatched and safety-gated, including the same operation fanned out across a monorepo. Not apm binary or agent-runtime install -> apm-install. The catalogue opener is gone, the composition/implementation detail ("coordinated across the apm-workflow skill with safety gates, session context, and structured results") is gone, and the boundary target `apm-install` resolves. `scripts/skill-size-check.sh` on `main` reported a description SUGGESTION and a missing boundary clause; on the branch both are silent. ### 2. Delegation FAIL: the `type:` Hard Rule Replaced with a one-clause orchestrator-side refusal: > `type:` correctness is `apm-workflow`'s call — do not pre-set or second-guess it. That is an action this orchestrator can take, not a restatement of a rule it does not own. Worth recording, since it is not in the report: the copy was not merely uncited, it had **drifted**. It asserted that `type:` "constrains what `.apm/` may contain", which is false — `type:` selects processing (`instructions` / `skill` / `prompts` / `hybrid`, per `PackageContentType`) and validates nothing against the primitives on disk. The agent's copy also dropped the four-value enumeration the skill-side gotcha carried. The skill-side text was corrected on this branch in `164948a` ("type: selects processing, it does not validate content"), so the agent copy was restating a rule that was itself wrong. ### 3. `add-package` mapping bug The Inputs row now reads: > add-package (→ `apm marketplace package add` — register a **remote** package reference (`owner/repo`, host URL, or full URL) into a marketplace being built; it rejects a local path, so a local package is not this operation — route it to `edit-config` instead) and `edit-config`'s own scope was widened to admit the case it now receives: "...or adding/removing a `marketplace.packages[]` entry, **including the local-package registration `apm marketplace package add` cannot perform**". Previously `edit-config` only mentioned *removing* an entry, so routing there would have been routing into a scope that did not cover the request. ### Two further defects fixed beyond the report - **The body carried the same numbered sequence twice.** A 7-step `When invoked, you:` list at line 28 and an 8-step `## Process` at line 50 described the same dispatch with different wording — including two different accounts of the parallel-fan-out rule. The `When invoked` copy is deleted; `## Process` is the single sequence. Body went 1080 → 876 words on the same counter. (Agents take no body-word gate by design, per `agent-audit/scripts/validate.sh` — noting the figures, not claiming a gate finding.) - **`## Process` step 2 named the deleted rule's old semantics.** It listed "`type:` ordering" among the Hard rules to check, which was the scaffolding-order rule that no longer exists. Now reads "`type:` delegation". `bash scripts/check-apm-agents-valid.sh` passes over all four plugin-scope agent files.
Claude commented 2026-09-01 13:59:56 +00:00
Author
Collaborator
Copy Link

Fixed by #129, squash-merged to main as 598a7c3.

Description rewritten to ADR-0020 shape — trigger + one capability + boundary, with the catalogue opener and the composition/implementation detail gone:

Use when an agent caller needs a multi-step apm package or marketplace operation dispatched and safety-gated, including the same operation fanned out across a monorepo. Not apm binary or agent-runtime install -> apm-install.

Clears the description FAIL, is inside the 250 target, and now carries the boundary clause it lacked.

The add-package mapping bug is corrected at the Inputs table, which now states the constraint rather than contradicting the Hard Rule two lines above it: apm marketplace package add registers a remote reference (owner/repo, host URL, or full URL), rejects a local path, and a local package routes to edit-config instead. A Hard Rule was also added telling the caller never to guess the marketplace-add direction from context but to resolve it strictly from the operation name, citing apm-workflow/references/marketplace.md.

The delegation FAIL — the uncited Hard Rule restating configure.md's Gotcha verbatim — is resolved the same way the file's other four rules were: it now cites its source skill.

Stayed open after the merge because Gitea's closing-keyword parser consumed only the first reference in Closes #99, #107, …. Closing manually.

Fixed by #129, squash-merged to `main` as `598a7c3`. **Description** rewritten to ADR-0020 shape — trigger + one capability + boundary, with the catalogue opener and the composition/implementation detail gone: > Use when an agent caller needs a multi-step apm package or marketplace operation dispatched and safety-gated, including the same operation fanned out across a monorepo. Not apm binary or agent-runtime install -> `apm-install`. Clears the description FAIL, is inside the 250 target, and now carries the boundary clause it lacked. **The `add-package` mapping bug** is corrected at the Inputs table, which now states the constraint rather than contradicting the Hard Rule two lines above it: `apm marketplace package add` registers a **remote** reference (`owner/repo`, host URL, or full URL), rejects a local path, and a local package routes to `edit-config` instead. A Hard Rule was also added telling the caller never to guess the marketplace-add direction from context but to resolve it strictly from the operation name, citing `apm-workflow/references/marketplace.md`. **The delegation FAIL** — the uncited Hard Rule restating `configure.md`'s Gotcha verbatim — is resolved the same way the file's other four rules were: it now cites its source skill. Stayed open after the merge because Gitea's closing-keyword parser consumed only the first reference in `Closes #99, #107, …`. Closing manually.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Kind/Bug
Priority
Medium
3
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#120
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?