File package submission as a governed effect, fenced behind the fit review

[George-RD]

Part of #182

Question

File an issue capturing: package submission is a governed effect — attenuation-only minting, owner approval; manifests machine-authorable, machine-checkable, renderable for review (the in-force part of the Delegating owner story, STORIES.md). Fenced behind the fit review: label it so no agent grabs it before the fence lifts (not ready-for-agent).

Resolved when the issue exists and is linked from this ticket.

[George-RD]

Resolution. Filed: #196 (fenced, deliberately not ready-for-agent). Attenuation-only minting + owner approval; machine-authorable/checkable/renderable manifests are in force now.

[coderabbitai]

Coding Plan

Summary

File a single GitHub issue with the gh CLI that captures package submission as a governed effect with attenuation-only minting, owner approval, and machine-authorable, machine-checkable, renderable manifests.

Ground each ticket term in the repository's established vocabulary: the artifact.propose lifecycle, attenuation, minting, and digest-bound approval.

Fence the issue behind the fit review by omitting ready-for-agent, adding needs-triage, and stating the fence in prose, with a native blocked_by edge when a fit-review issue exists.

Link the issue to map #182 with Part of #182`` and the wayfinder sub-issue convention, and confirm the back-link to satisfy the resolution condition.

Design Choices

Design Choice 1: Which vocabulary should the issue use, given the ticket terms are not in the repository glossary?

Options Considered:

1. Use the ticket terms verbatim and quote the source story where possible.
2. Replace the ticket terms with the repository's existing glossary terms.
3. Use the ticket terms as headings, and map each to the existing glossary terms in the body.

Chosen Option: 3

Rationale: The issue must remain faithful to the parent framing in #182 while grounding each term in the established artifact.propose, attenuation, minting, and digest-bound approval vocabulary, so a future agent can implement without inventing language. The terms "governed effect", "attenuation-only minting", "fit review", "Delegating owner story", and STORIES.md do not exist in this repository. The closest established, precise terms are attenuation (caveat-chain narrowing), minting (creating a grant/token), owner review / digest-bound approval, and the artifact.propose lifecycle.

Design Choice 2: How should the "fence" behind the fit review be represented in the issue?

Options Considered:

1. Omit ready-for-agent only, and state the fence in prose in the body.
2. Omit ready-for-agent, add needs-triage, and state the fence in prose.
3. Omit ready-for-agent, add a native GitHub blocked_by dependency edge to the fit-review issue, and state the fence in prose.

Chosen Option: 2

Rationale: Option 2 is chosen when no fit-review issue number is available, and Option 3 is chosen when a fit-review issue number is available. The absence of ready-for-agent is the primary fence. needs-triage keeps the issue away from AFK agents. A native blocked_by edge is preferred when the fit-review gate exists as an issue, because it is the canonical, UI-visible representation per docs/agents/issue-tracker.md. The repository has no blocked, fenced, or pending-fit-review label. The five triage labels do not include a fence label. ready-for-agent is the only "go" signal.

Design Choice 3: Where does the `STORIES.md` "Delegating owner story" content come from?

Options Considered:

1. Treat STORIES.md as an external source referenced by #182 and cite it by name.
2. Block the task until STORIES.md is added to the repository.

Chosen Option: 1

Rationale: The ticket only requires filing and linking the issue, not creating STORIES.md. The issue body must cite STORIES.md and the "Delegating owner" story by name, and note that the file is not yet present in the repository so the maintainer can confirm the source. STORIES.md, CONTEXT.md, and DIRECTION.md do not exist in this repository. Issue #182 references STORIES.md as the source of failure modes.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Draft the issue content

This phase produces the exact text of the new issue. The text must be precise. The text must use the mapped vocabulary. The text must state the fence. No gh command runs in this phase.

Task 1: Draft the problem statement and scope

Capture the core requirement in clear prose that a future agent can implement.

• State that package submission is a governed effect. Map "governed effect" to the existing artifact.propose → evaluate → owner-approve → activate pipeline in openspec/specs/artifact-lifecycle/spec.md.
• State that minting is attenuation-only. Map this to the attenuation and minting invariants: a child grant must never expand effective actions, and evaluation alone must never grant or activate authority.
• State that owner approval is required. Map this to the digest-bound approval mechanism, where the approval binds the exact reviewed bytes and {kind, id, version}.
• State that manifests must be machine-authorable, machine-checkable, and renderable for review. Note that artifacts/lyra/package.yaml is human-only metadata today and that no Package/PackageManifest schema exists, so this is net-new.
• Reference the "Delegating owner" story in STORIES.md as the in-force source. Note that STORIES.md is not present in the repository yet, so the maintainer can confirm the source.

Task 2: Draft acceptance criteria and out-of-scope

Give the future agent a fully specified target that fails closed on drift.

• List acceptance criteria that mirror the artifact-lifecycle invariants: one proposable kind with a deny_unknown_fields schema, lifecycle_state starting at proposed only, monotonic versioning across live and pending proposals, an eval gate that runs before any persisted side effect, atomic transactional commit of the lifecycle transition and audit before publication, and a digest-bound owner approval.
• Mark out of scope: the package store and installer, which are tracked separately in issue #117.
• Reference related context issues: #182 (parent map), #123 (progressive delegation), #117 (package installer), and #133 (proposal-specific, evidence-backed evaluation).

Task 3: Draft the linking and fence lines

Prepare the body lines that link the issue to the map and record the fence.

• Add Part of Wayfinder map: the deepening route — from the 2026-08-20 review to designed specs #182`` as the first line of the body, per the wayfinder child-ticket fallback convention in docs/agents/issue-tracker.md.
• Add a prose statement that the issue is fenced behind the fit review and must not be picked up by an agent until the fence lifts.
• If a fit-review gate issue number exists, add a Blocked by: #<n> line at the top of the body as the fallback blocking convention. If native dependencies are enabled, prefer the native edge in Phase 2 instead.

🤖 Prompt for AI agents

Draft the exact text content of the new GitHub issue. Do not run any `gh`
command in this phase.

1. Draft the problem statement and scope:
- State that package submission is a governed effect, and map this term to the
existing `artifact.propose` → evaluate → owner-approve → activate pipeline in
`openspec/specs/artifact-lifecycle/spec.md`.
- State that minting is attenuation-only, and map this to the `attenuation` and
`minting` invariants: a child grant must never expand effective actions, and
evaluation alone must never grant or activate authority.
- State that owner approval is required, and map this to the `digest-bound
approval` mechanism, where the approval binds the exact reviewed bytes and
`{kind, id, version}`.
- State that manifests must be machine-authorable, machine-checkable, and
renderable for review. Note that `artifacts/lyra/package.yaml` is human-only
metadata today, and note that no `Package`/`PackageManifest` schema exists, so
this is net-new work.
- Reference the "Delegating owner" story in `STORIES.md` as the in-force source,
and note that `STORIES.md` is not present in the repository yet, so the
maintainer can confirm the source.

2. Draft acceptance criteria and out-of-scope sections:
- List acceptance criteria that mirror the artifact-lifecycle invariants: one
proposable kind with a `deny_unknown_fields` schema, `lifecycle_state` starting
at `proposed` only, monotonic versioning across live and pending proposals, an
eval gate that runs before any persisted side effect, atomic transactional
commit of the lifecycle transition and audit before publication, and a
digest-bound owner approval.
- Mark the package store and installer as out of scope, and note they are
tracked separately in issue `#117`.
- Reference related context issues: `#182` (parent map), `#123` (progressive
delegation), `#117` (package installer), and `#133` (proposal-specific,
evidence-backed evaluation).

3. Draft the linking and fence lines:
- Add `Part of `#182`` as the first line of the body, per the wayfinder
child-ticket fallback convention in `docs/agents/issue-tracker.md`.
- Add a prose statement that the issue is fenced behind the fit review, and
state that the issue must not be picked up by an agent until the fence lifts.
- If a fit-review gate issue number exists, add a `Blocked by: #<n>` line at the
top of the body as the fallback blocking convention. If native dependencies are
enabled, prefer the native edge instead, and apply it in Phase 2.

Phase 2: Create, label, and link the issue

This phase runs the gh operations that file the issue, apply the fence, and link it from the map.

Task 1: Create the issue

File the drafted content as a new GitHub issue.

• Run gh issue create --title "File package submission as a governed effect, fenced behind the fit review" --body "<drafted body>" with a heredoc for the multi-line body from Phase 1.
• Record the returned issue number for the linking and back-reference steps.

Task 2: Apply the fence labels

Label the issue so no AFK agent picks it up before the fence lifts.

• Do not apply ready-for-agent. The absence of ready-for-agent is the primary fence per docs/agents/triage-labels.md.
• Apply needs-triage with gh issue edit <n> --add-label "needs-triage" to keep the issue away from agents until a maintainer clears it and the fit review lifts the fence.
• If the wayfinder child-type label applies for #182's map, also apply wayfinder:task per the "Wayfinding operations" procedure.

Task 3: Link the issue to map `#182`

Attach the new issue as a child of the map and record the block if a fit-review issue exists.

• Prefer the native GitHub sub-issues API to attach the new issue as a child of #182. If sub-issues are not enabled, add the new issue to a task list in the #182 body and rely on the Part of Wayfinder map: the deepening route — from the 2026-08-20 review to designed specs #182`` body line from Task 1.3.
• If a fit-review gate issue exists, add a native blocked_by dependency with gh api --method POST repos/George-RD/openspine/issues/<n>/dependencies/blocked_by -F issue_id=<blocker-db-id>, using the blocker's numeric database id.

Task 4: Back-link the issue from the ticket

Satisfy the resolution condition.

• Confirm the new issue is referenced from #182, either as a native sub-issue or as an entry in the #182 task list.
• Add a comment on #182 with gh issue comment 182 --body "<link to new issue>" if a task-list or sub-issue link is not sufficient to record the linkage.

🤖 Prompt for AI agents

Run the `gh` CLI operations that file the drafted issue, apply the fence labels,
and link the issue to map `#182`.

1. Create the issue:
- Run `gh issue create --title "File package submission as a governed effect,
fenced behind the fit review" --body "<drafted body>"`, and use a heredoc for
the multi-line body drafted in Phase 1.
- Record the returned issue number for use in the linking and back-reference
steps.

2. Apply the fence labels:
- Do not apply the `ready-for-agent` label. The absence of `ready-for-agent` is
the primary fence, per `docs/agents/triage-labels.md`.
- Apply the `needs-triage` label with `gh issue edit <n> --add-label
"needs-triage"` to keep the issue away from agents until a maintainer clears it
and the fit review lifts the fence.
- If the wayfinder child-type label applies for `#182`'s map, also apply
`wayfinder:task`, per the "Wayfinding operations" procedure in
`docs/agents/issue-tracker.md`.

3. Link the issue to map `#182`:
- Prefer the native GitHub sub-issues API to attach the new issue as a child of
`#182`.
- If sub-issues are not enabled, add the new issue to a task list in the `#182`
body, and rely on the `Part of `#182`` body line drafted in Phase 1.
- If a fit-review gate issue exists, add a native `blocked_by` dependency with
`gh api --method POST
repos/George-RD/openspine/issues/<n>/dependencies/blocked_by -F
issue_id=<blocker-db-id>`, using the blocker's numeric database id.

4. Back-link the issue from the ticket:
- Confirm the new issue is referenced from `#182`, either as a native sub-issue or
as an entry in the `#182` task list.
- If a task-list or sub-issue link is not sufficient to record the linkage, add
a comment on `#182` with `gh issue comment 182 --body "<link to new issue>"`.

Research

Issues for this repository live as GitHub issues on George-RD/openspine. Agents manage them with the gh CLI. docs/agents/issue-tracker.md defines the operations and the "Wayfinding operations" procedure for map and child issues. docs/agents/triage-labels.md defines five triage labels. ready-for-agent means the issue is fully specified for an away-from-keyboard agent to implement. There is no issue template file. Issue #182 is the wayfinder map for this work. The related governed-effect pipeline for artifacts is specified in openspec/specs/artifact-lifecycle/spec.md and implemented in crates/openspine-kernel/src/api/artifact_propose.rs. No package artifact kind exists yet, so package submission is net-new future work.

This task creates a GitHub issue. It does not change repository source files.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Draft the exact text content of the new GitHub issue. Do not run any `gh`
command in this phase.

1. Draft the problem statement and scope:
- State that package submission is a governed effect, and map this term to the
existing `artifact.propose` → evaluate → owner-approve → activate pipeline in
`openspec/specs/artifact-lifecycle/spec.md`.
- State that minting is attenuation-only, and map this to the `attenuation` and
`minting` invariants: a child grant must never expand effective actions, and
evaluation alone must never grant or activate authority.
- State that owner approval is required, and map this to the `digest-bound
approval` mechanism, where the approval binds the exact reviewed bytes and
`{kind, id, version}`.
- State that manifests must be machine-authorable, machine-checkable, and
renderable for review. Note that `artifacts/lyra/package.yaml` is human-only
metadata today, and note that no `Package`/`PackageManifest` schema exists, so
this is net-new work.
- Reference the "Delegating owner" story in `STORIES.md` as the in-force source,
and note that `STORIES.md` is not present in the repository yet, so the
maintainer can confirm the source.

2. Draft acceptance criteria and out-of-scope sections:
- List acceptance criteria that mirror the artifact-lifecycle invariants: one
proposable kind with a `deny_unknown_fields` schema, `lifecycle_state` starting
at `proposed` only, monotonic versioning across live and pending proposals, an
eval gate that runs before any persisted side effect, atomic transactional
commit of the lifecycle transition and audit before publication, and a
digest-bound owner approval.
- Mark the package store and installer as out of scope, and note they are
tracked separately in issue `#117`.
- Reference related context issues: `#182` (parent map), `#123` (progressive
delegation), `#117` (package installer), and `#133` (proposal-specific,
evidence-backed evaluation).

3. Draft the linking and fence lines:
- Add `Part of `#182`` as the first line of the body, per the wayfinder
child-ticket fallback convention in `docs/agents/issue-tracker.md`.
- Add a prose statement that the issue is fenced behind the fit review, and
state that the issue must not be picked up by an agent until the fence lifts.
- If a fit-review gate issue number exists, add a `Blocked by: #<n>` line at the
top of the body as the fallback blocking convention. If native dependencies are
enabled, prefer the native edge instead, and apply it in Phase 2.
===============================================================================

Task: 2

Run the `gh` CLI operations that file the drafted issue, apply the fence labels,
and link the issue to map `#182`.

1. Create the issue:
- Run `gh issue create --title "File package submission as a governed effect,
fenced behind the fit review" --body "<drafted body>"`, and use a heredoc for
the multi-line body drafted in Phase 1.
- Record the returned issue number for use in the linking and back-reference
steps.

2. Apply the fence labels:
- Do not apply the `ready-for-agent` label. The absence of `ready-for-agent` is
the primary fence, per `docs/agents/triage-labels.md`.
- Apply the `needs-triage` label with `gh issue edit <n> --add-label
"needs-triage"` to keep the issue away from agents until a maintainer clears it
and the fit review lifts the fence.
- If the wayfinder child-type label applies for `#182`'s map, also apply
`wayfinder:task`, per the "Wayfinding operations" procedure in
`docs/agents/issue-tracker.md`.

3. Link the issue to map `#182`:
- Prefer the native GitHub sub-issues API to attach the new issue as a child of
`#182`.
- If sub-issues are not enabled, add the new issue to a task list in the `#182`
body, and rely on the `Part of `#182`` body line drafted in Phase 1.
- If a fit-review gate issue exists, add a native `blocked_by` dependency with
`gh api --method POST
repos/George-RD/openspine/issues/<n>/dependencies/blocked_by -F
issue_id=<blocker-db-id>`, using the blocker's numeric database id.

4. Back-link the issue from the ticket:
- Confirm the new issue is referenced from `#182`, either as a native sub-issue or
as an entry in the `#182` task list.
- If a task-list or sub-issue link is not sufficient to record the linkage, add
a comment on `#182` with `gh issue comment 182 --body "<link to new issue>"`.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!