codeassembly-guidance 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/.meta/changelog.json +185 -0
  2. package/CHANGELOG.md +45 -0
  3. package/README.md +29 -51
  4. package/content/_partials/kb-unsearched-private-stores.md +6 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
  7. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
  8. package/content/guidance/shared/AGENTS.md +1 -1
  9. package/content/scripts/check-prose.mjs +1 -1
  10. package/content/scripts/describe-change.mjs +89 -89
  11. package/content/scripts/manage-jira-ticket.mjs +113 -113
  12. package/content/scripts/select-lede-exemplars.mjs +85 -85
  13. package/content/scripts/validate-preferences.mjs +38 -38
  14. package/content/skills/_data/project-stage.md +9 -5
  15. package/content/skills/_data/spike-conventions.md +9 -6
  16. package/content/skills/_partials/implementation-order-list.md +27 -0
  17. package/content/skills/_partials/next-steps-after-plan.md +2 -2
  18. package/content/skills/_partials/plan-template.md +2 -0
  19. package/content/skills/_partials/split-launch-prompts.md +1 -1
  20. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
  21. package/content/skills/assess-code-health/SKILL.md +2 -2
  22. package/content/skills/assess-usability/SKILL.md +2 -2
  23. package/content/skills/capture-event/SKILL.md +20 -11
  24. package/content/skills/capture-event/capture-event.mjs +122 -122
  25. package/content/skills/capture-feedback/SKILL.md +2 -1
  26. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
  27. package/content/skills/create-pr/SKILL.md +11 -11
  28. package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
  29. package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
  30. package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
  31. package/content/skills/design-and-plan/SKILL.md +4 -2
  32. package/content/skills/implement-plan/SKILL.md +3 -1
  33. package/content/skills/implementation-order/implementation-order.mjs +67 -0
  34. package/content/skills/investigate-spike/SKILL.md +1 -1
  35. package/content/skills/kb-add/SKILL.md +12 -3
  36. package/content/skills/kb-add/kb-add.mjs +88 -88
  37. package/content/skills/kb-curate/kb-curate.mjs +88 -88
  38. package/content/skills/kb-edit/kb-edit.mjs +90 -90
  39. package/content/skills/kb-retrieve/SKILL.md +8 -3
  40. package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
  41. package/content/skills/kb-retrieve-events/SKILL.md +8 -3
  42. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
  43. package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
  44. package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
  45. package/content/skills/list-implementation-order/SKILL.md +23 -0
  46. package/content/skills/merge-bb-pr/SKILL.md +31 -8
  47. package/content/skills/merge-gh-pr/SKILL.md +25 -12
  48. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
  49. package/content/skills/merge-pr/SKILL.md +55 -20
  50. package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
  51. package/content/skills/plan/SKILL.md +3 -1
  52. package/content/skills/prepare-prototype-brief/SKILL.md +3 -1
  53. package/content/skills/refine-plan/SKILL.md +2 -0
  54. package/content/skills/review-branch/SKILL.md +1 -1
  55. package/content/skills/review-criteria/SKILL.md +1 -1
  56. package/content/skills/revise-prose/revise-prose.mjs +111 -111
  57. package/content/skills/save-plan/SKILL.md +2 -0
  58. package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
  59. package/content/skills/summarize-change/SKILL.md +17 -7
  60. package/content/skills/testing-conventions/SKILL.md +2 -2
  61. package/content/skills/triage-feedback/SKILL.md +4 -0
  62. package/content/skills/triage-spike-findings/SKILL.md +10 -5
  63. package/content/skills/wrap-up/SKILL.md +4 -0
  64. package/package.json +9 -9
  65. package/schemas/preferences.v1.json +74 -8
  66. package/schemas/work-types.v1.json +1 -1
@@ -1,12 +1,15 @@
1
1
  # Project stage
2
2
 
3
- A project declares its stage in its own `.agents/preferences.yaml`, under `project`, and the session-context manifest reports each value as `project_maturity`, `project_sensitivity`, and `project_audience`, `null` when the project does not declare it. The global preferences file never supplies a stage, because a stage describes one repo.
3
+ A project declares its stage in its own `.agents/preferences.yaml`, under `project`, and the session-context manifest reports each value as `project_maturity`, `project_sensitivity`, and `project_audience`, `null` when the project does not declare it. A subdirectory, such as one experiment in a repository of experiments, declares its own stage as an entry of `project.stages`: a `path` relative to the repository root and the keys that it overrides. The manifest reports the entries as `project_stages`, each with the values that it inherits from the project filled in. The global preferences file never supplies a stage, because a stage describes one repository or a part of one.
4
+
5
+ The stage that governs a piece of work is the entry whose `path` contains the work's paths, matched at a directory boundary, with the longest containing path winning; a path under no entry takes the project's stage. When the work touches paths under more than one stage, each key takes its most demanding value among them. The table below lists each key's values from the least demanding to the most.
4
6
 
5
7
  ## Values
6
8
 
7
9
  | Key | Value | Meaning |
8
10
  | ------------- | -------------- | -------------------------------------------------------------------------------- |
9
- | `maturity` | `hobby` | Built for the owner's own use or learning; breakage costs only the owner's time. |
11
+ | `maturity` | `exploration` | The output's shape is still being found, and nothing depends on it yet. |
12
+ | | `hobby` | Built for the owner's own use or learning; breakage costs only the owner's time. |
10
13
  | | `early` | In use by others, but the shape is still changing; downtime is tolerated. |
11
14
  | | `production` | Others depend on it; downtime and data loss have real costs. |
12
15
  | `sensitivity` | `low` | Nothing that would harm anyone if published. |
@@ -19,8 +22,9 @@ A project declares its stage in its own `.agents/preferences.yaml`, under `proje
19
22
  ## What each value implies
20
23
 
21
24
  - **Security.** `owner` with `low` sensitivity needs only what keeps the owner's own credentials out of the repository; access control beyond the host's own login is machinery without an asset to protect. `personal` data warrants access limited to the people that it concerns. Authentication with several factors, rate limits, and origin checks are needed for `public` users or `confidential` data.
22
- - **Availability.** `hobby` tolerates a service that runs only while the owner works, such as a local process or a database on the owner's machine. `early` tolerates downtime and manual recovery. Hosted, always-available infrastructure and backups are needed for `production`.
25
+ - **Availability.** `exploration` and `hobby` tolerate a service that runs only while the owner works, such as a local process or a database on the owner's machine. `early` tolerates downtime and manual recovery. Hosted, always-available infrastructure and backups are needed for `production`.
23
26
  - **Infrastructure.** Choose the least infrastructure on which the project runs at its declared stage: a file before a database, a local process before a hosted service, one environment before several.
27
+ - **Verification.** An output is unsettled while the governing maturity is `exploration`, or while the work is a spike, a proof of concept, a prototype, or an agent whose output the developer has not approved. While an output is unsettled, the developer judges it by reading it on real inputs, starting from the user's own example of the output when one exists. Golden references, answer keys, gated evals, and exhaustive fixtures wait until the developer approves an output as the target, and are frozen from it; any built earlier are provisional, not a contract. Unit tests of the deterministic code around the output are outside this rule.
24
28
 
25
29
  ## Rules
26
30
 
@@ -28,5 +32,5 @@ A project declares its stage in its own `.agents/preferences.yaml`, under `proje
28
32
  - **Default to the least machinery that works for the declared stage.** Read [design priorities](design-priorities.md) against the stage: Behavioral correctness covers the cases that matter at that stage.
29
33
  - **Escalate only for a named asset or need.** Add security, availability, or infrastructure beyond what the stage implies only when the design names what it protects or serves, such as "the tokens table holds the owner's API keys". State the asset or need in the ticket.
30
34
  - **Make added hardening switchable.** A safeguard added beyond the stage, such as an origin check or a rate limit, is switched by configuration, so that a preview deployment or a local run can work without it.
31
- - **Ask for an undeclared value; never infer it.** An undeclared value is a preference for which the agent holds no evidence, so it is in the gated class: Ask the developer rather than infer enterprise requirements from silence. Once the developer answers, declare the value in the project's `.agents/preferences.yaml` and run `node {harness_home_dir}/scripts/validate-preferences.mjs` on the edited file, so that the question is asked once.
32
- - **Record the premises.** State each value that decided a security, availability, or infrastructure question where the work records its decisions: in a ticket's `## Context`, one sentence per premise naming the value and the decision that it settled, and in a product's design doc.
35
+ - **Ask for an undeclared value; never infer it.** An undeclared value is a preference for which the agent holds no evidence, so it is in the gated class: Ask the developer rather than infer enterprise requirements from silence. Ask about verification only when the answer decides it: Work that is unsettled by its kind, such as a spike, does not need the maturity. Once the developer answers, declare the value in the project's `.agents/preferences.yaml`, under `project.stages` when it describes a subdirectory, and run `node {harness_home_dir}/scripts/validate-preferences.mjs` on the edited file, so that the question is asked once.
36
+ - **Record the premises.** State each value that decided a security, availability, infrastructure, or verification question where the work records its decisions: in a ticket's `## Context`, one sentence per premise naming the value and the decision that it settled, and in a product's design doc.
@@ -39,7 +39,7 @@ The concision and content-placement doctrines for feature tickets and plans appl
39
39
 
40
40
  - [ ] {A decision that the findings must make possible.}
41
41
 
42
- Deliverable: a findings & recommendation artifact, and the closing post on this ticket.
42
+ Deliverable: a findings & recommendation artifact, and the closing post on this ticket, followed by the ticket's close.
43
43
  ```
44
44
 
45
45
  `Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
@@ -81,7 +81,7 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
81
81
 
82
82
  ## Deliverable
83
83
 
84
- {The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
84
+ {The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, followed by the ticket's close, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
85
85
  ```
86
86
 
87
87
  Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior, and it names the [closing post](#closing-post); a step does not have a test or documentation criterion.
@@ -90,18 +90,21 @@ The `investigate-spike` skill carries out a spike plan.
90
90
 
91
91
  ## Closing post
92
92
 
93
- The agent that ends a spike posts its conclusion on the ticket as a comment. The post contains:
93
+ The agent that ends a spike posts its conclusion on the ticket as a comment, then closes the ticket as completed. The post contains:
94
94
 
95
95
  - The answer to each of the ticket's questions to answer.
96
96
  - The recommendation on each of the ticket's decisions to enable.
97
97
  - The counts and the proposed groupings, when the spike produced them.
98
98
  - Links to the published page, when the spike published one, and to the findings artifact, with the artifact's path written `~/`-relative, so that the post does not publish a home-directory path.
99
99
 
100
- The skill that ends the spike offers the post. When the findings leave an item without a disposition, the triage round that disposes of them on the same ticket ends the spike: `triage-spike-findings` offers the post, and the skill that produced the findings names the triage as its next step without offering the post, which could not yet answer the decisions to enable. When the findings leave nothing to triage, the skill that produced them offers it. A follow-up triage ticket for a later batch does not take a closing post, because its dispositions comment is its record; the post on the original ticket names the follow-ups.
100
+ The skill that ends the spike offers the post. When the findings leave an item without a disposition, the triage round that disposes of them on the same ticket ends the spike: `triage-spike-findings` offers the post, and the skill that produced the findings names the triage as its next step without offering the post, which could not yet answer the decisions to enable. When the findings leave nothing to triage, the skill that produced them offers it. A follow-up triage ticket for a later batch does not take a closing post, because its dispositions comment is its record: `triage-spike-findings` closes it as completed, without a post, once that comment is posted, under the confirmation that covers the round's writes. The post on the original ticket names the follow-ups.
101
101
 
102
- Offer the post as an item in the closing action-items block of that skill, show its body, and post it only on consent: It is a remote write, and the developer is the one who can tell whether a finding is fit for the ticket's tracker. When the session does not have a ticket, do not offer it.
102
+ Offer the post and the close as one item in the closing action-items block of that skill, show the post's body, and name both actions in the ask: "Post this conclusion on #420 and close it as completed?". Make both writes only on consent: They are remote writes, and the developer is the one who can tell whether a finding is fit for the ticket's tracker and whether the spike is done. Consent to the offer is the developer's call on closing the ticket. When the developer declines, post nothing and leave the ticket open. When the session does not have a ticket, do not offer it.
103
103
 
104
- Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file). Before posting, read the ticket's comments, and skip the post when a comment already opens with the post's first line, so that a rerun does not post it twice.
104
+ Before writing, read the ticket's comments and its state, and decide each write on its own, so that a rerun neither posts the conclusion twice nor fails on a closed ticket:
105
+
106
+ - Post the conclusion unless a comment already opens with the post's first line. Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file).
107
+ - Close the ticket with `gh issue close {number} --reason completed` only while its state is `OPEN`.
105
108
 
106
109
  ## Findings batches
107
110
 
@@ -0,0 +1,27 @@
1
+ ## Implementation-order list
2
+
3
+ Print open tickets in the order in which to implement them, as a tree for a narrow column. The step that links here names the tickets, in the order in which it reached them, an `--external` entry for each ticket outside GitHub, and an `--edge` for each dependency that the tracker does not record. A bundled helper reads the tickets, orders them, and writes the fixed part of every line. You shorten the titles and mark the publish gates.
4
+
5
+ 1. **Run the helper.**
6
+
7
+ ```bash
8
+ node {harness_home_dir}/skills/implementation-order/implementation-order.mjs \
9
+ --ticket {OWNER/REPO#N} --external "{KEY}={Title}" --edge "{BLOCKER}>{BLOCKED}"
10
+ ```
11
+
12
+ Write a GitHub ticket as `OWNER/REPO#N`, taking the repository from the ticket's URL. Repeat each flag once per ticket or edge. Each side of an edge is `OWNER/REPO#N` or a key that an `--external` declares, and the blocked side is a listed ticket. On a non-zero exit, report the helper's stderr and do not print the list: A list that lacks a ticket misstates the order.
13
+
14
+ The helper prints `{"tickets": [...], "omitted": [...], "cycle": [...]}`. `tickets` is in list order. `omitted` names the closed tickets, which the list leaves out.
15
+
16
+ 2. **Shorten each title** to at most the ticket's `titleBudget` characters. Cut words rather than end with an ellipsis, and keep the leading verb. Leave a title that already fits as it is.
17
+
18
+ 3. **Find the publish gates.** A gate follows a ticket when its change must be published, and the dependency upgraded in a consuming repository, before a ticket that it blocks can start. Look for one wherever a ticket blocks a ticket in another repository; `crossRepository` marks those among `otherBlockers`, and a child in the tree whose `repository` differs from its parent's is another. The tracker does not record whether the blocked repository consumes the blocking one as a published package, so judge that from the tickets and the conversation.
19
+
20
+ 4. **Print the list** as one fenced block. For each ticket, in order:
21
+ - Its line: `lead`, then the shortened title.
22
+ - Its `blockerLine`, when that is not null.
23
+ - Its gate, when step 3 found one: `gateLead`, then the package's name, then `, upgrade in `, then the prefix of each consuming repository in the list, separated by commas. Name the package rather than the repository when the two differ.
24
+
25
+ A ticket's place states its blocker: It is indented under the ticket that blocks it. `blockerLine` names the blockers that the indent does not state.
26
+
27
+ When `cycle` is not empty, add a last line inside the block: `⚠️`, then the labels of the tickets in `cycle`, then `block each other`.
@@ -65,9 +65,9 @@ Select the recommended option by checking these rules in order and stopping at t
65
65
 
66
66
  When rule 1 matches, the rendered option must name that decision on a `➕` line. Being unable to write the line means rule 1 did not match.
67
67
 
68
- 2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either.
68
+ 2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either. A plan that touches two or more repositories matches whatever its size: Each repository is a piece, per the ticketing preferences.
69
69
 
70
- A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`.
70
+ A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`. For a plan that spans repositories, the pieces are the repositories: `➕ three tasks across two repositories: the helper in williamthorsen/codeassembly (task 1), then the skill that calls it here (tasks 2–3)`.
71
71
 
72
72
  Structural properties (new module boundaries, changed interfaces, several packages) make a plan _more likely_ to be too large. They are evidence to weigh, and none of them matches rule 2 on its own.
73
73
 
@@ -52,6 +52,8 @@
52
52
 
53
53
  **Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
54
54
 
55
+ **Per-task verification guidance:** When the work's output is unsettled per [project stage](../_data/project-stage.md), each task that produces the output verifies it through a reading round rather than a golden reference, an answer key, or an eval gate: The agent runs the output on real inputs, starting from the user's own example of the output when one exists, and presents it, and the developer's judgment of it is the task's `**Residue:**`, because only the developer can approve a target. Plan a golden reference or an eval only as a task that follows the developer's approval of an output, and freeze it from that output.
56
+
55
57
  **Per-task documentation criterion:** When a task adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include updating documentation, help text, and usage examples, including removal of references to anything that no longer exists.
56
58
 
57
59
  **Per-task README guidance:** When a task writes or revises a README, consult {rulebook:readme-conventions} while planning the task. Its key decisions name the rulebook, the table row that fits the README, and what that row says the README leads with, keeps, and omits, so that the constraints are available to an implementer that cannot load the rulebook.
@@ -1,4 +1,4 @@
1
- **Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}** (ready now)` or `(after {blocker_ref} merges)`, followed by a fenced block that contains only the text to paste:
1
+ **Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. When two or more tickets keep work, print the list for them above the prompts, per [implementation-order list](#implementation-order-list), passing an `--edge` for each `--blocked-by` between pieces outside GitHub: The helper reads GitHub's native blockers, which `{skill:create-ticket}` recorded for the GitHub pieces, and not a Jira link. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}**`, followed by a fenced block that contains only the text to paste. The list states each ticket's readiness, so the heading does not repeat it:
2
2
 
3
3
  - The entry invocation, which the rule above chooses, as `{entry_skill} with plan: {plan_path}, ticket: {ticket_ref}`, adding any flag that the rule names, omitting any argument that the rule omits, and omitting the plan when the ticket does not have one.
4
4
  - The scope notes that the session needs and that the artifacts do not state, such as "only tasks 2 and 3" or "merge only after `live` contains #N".
@@ -51,7 +51,7 @@ What the skill does depends on whether a prior ticket exists, not on how the cal
51
51
 
52
52
  **Alignment, when a prior ticket exists.** `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the ticket was written. Reproduce all three verbatim from the source ticket and revise `## Acceptance criteria` alone, because the criteria alone are the contract that an implementation can falsify. A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. A section missing from the source ticket stays omitted: Alignment revises the record and adds nothing to it. The saved artifact is still a complete ticket; only its revision is partial.
53
53
 
54
- When the implementation diverges from what was proposed, report that divergence in the pull-request description, whose job is to describe the change under review. Do not raise it as a ticket edit, and do not offer it as an option. A reviewer reads the diff to learn what the code does, so an implementation outgrowing its proposal is an ordinary finding rather than a defect in the ticket.
54
+ When the implementation diverges from what was proposed, report the divergence in the pull-request description's `## Notes for reviewers` only when it changes what a reviewer checks, under the reader test that `summarize-change` states, and state it as the current fact rather than as a departure from the ticket; otherwise leave it out. Do not raise it as a ticket edit, and do not offer it as an option. A reviewer reads the diff to learn what the code does, so an implementation outgrowing its proposal is an ordinary finding rather than a defect in the ticket.
55
55
 
56
56
  The source ticket is the one that the caller names. A review names it in its `## Specification compliance` section, which records the source against which the review measured, the remote issue or the local snapshot.
57
57
 
@@ -9,7 +9,7 @@ supported-harnesses: [claude]
9
9
 
10
10
  Find the code and tests in one unit of a codebase that would be written differently if they were written afresh today, and propose one change for each. Each lens is a {subagent:code-health-assessor} that reads the unit without seeing any other lens's report. You run the sensors, write the brief that every lens reads, dispatch the lenses, check every proposal's evidence against the tree, and merge the proposals into one findings artifact.
11
11
 
12
- The skill does not grade anything: The findings artifact is the input of `triage-spike-findings`, which grades each proposal, has a challenger argue against every grade, and decides what becomes a ticket. When the findings leave nothing to triage, its one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent; otherwise the triage round makes the post.
12
+ The skill does not grade anything: The findings artifact is the input of `triage-spike-findings`, which grades each proposal, has a challenger argue against every grade, and decides what becomes a ticket. When the findings leave nothing to triage, its remote writes are the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and the ticket's close, both made on one consent from the developer; otherwise the triage round makes both.
13
13
 
14
14
  ## Inputs
15
15
 
@@ -124,6 +124,6 @@ Give the developer the findings artifact's path and one line of counts: proposal
124
124
 
125
125
  When the findings rank any proposal, name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states.
126
126
 
127
- Otherwise, offer the closing post on the ticket in the same response's action-items block. Its contents, consent, and duplicate check are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the counts, and the post names the proposals that a prior disposition or an issue already tracks.
127
+ Otherwise, offer to close the ticket with the closing post in the same response's action-items block. The post's contents, the consent, and the checks that a rerun relies on are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the counts, and the post names the proposals that a prior disposition or an issue already tracks.
128
128
 
129
129
  <!-- guidance-hook: implementation-preferences -->
@@ -9,7 +9,7 @@ supported-harnesses: [claude]
9
9
 
10
10
  Find where a product would lead its users to conclude that it is broken or unfinished. Each lens is a {subagent:usability-assessor} that walks its use cases in a browser or, for a command-line product, in a shell, without seeing any other lens's report. You prepare the targets, write the brief that every lens reads, dispatch the lenses one at a time, and merge their reports into one findings artifact.
11
11
 
12
- When the findings leave nothing to triage, the skill's one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent; otherwise the triage round makes the post. It does not create a ticket or edit an issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
12
+ When the findings leave nothing to triage, the skill's remote writes are the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and the ticket's close, both made on one consent from the developer; otherwise the triage round makes both. It does not create a ticket or edit any other issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
13
13
 
14
14
  ## Inputs
15
15
 
@@ -97,4 +97,4 @@ Give the developer the findings artifact's path, the page's URL, and one line of
97
97
 
98
98
  When the artifact has any finding or idea, name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states. Findings above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.
99
99
 
100
- Otherwise, offer the closing post on the ticket in the same response's action-items block. Its contents, consent, and duplicate check are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the use cases exercised and the page's URL.
100
+ Otherwise, offer to close the ticket with the closing post in the same response's action-items block. The post's contents, the consent, and the checks that a rerun relies on are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the use cases exercised and the page's URL.
@@ -22,16 +22,17 @@ A **skill-caused mistake**, an error that a clearer skill definition would have
22
22
 
23
23
  ## Arguments
24
24
 
25
- | Argument | Description | Required |
26
- | ----------- | ------------------------------------------------------------------------------------- | -------- |
27
- | `--summary` | A human-readable one-line summary; becomes the record's label on recall. | Yes |
28
- | `--store` | Registry name, `@default` for the `default_kb`, or `@feedback` for the `feedback_kb`. | Yes |
29
- | `--skill` | The skill to which the event relates. | No |
30
- | `--model` | The model identifier in play. | No |
31
- | `--harness` | The agent platform (`claude`, `rovo`); install-injected. Keep as-is. | Injected |
32
- | `--tags` | Comma-separated tag list. | No |
33
- | `--impact` | Impact rating: one of `low`, `medium`, `high`, `critical`. Omit to leave unrated. | No |
34
- | `--amend` | Id of an existing event to rewrite in place instead of capturing a new one. | No |
25
+ | Argument | Description | Required |
26
+ | ----------- | -------------------------------------------------------------------------------------------------------- | -------- |
27
+ | `--summary` | A human-readable one-line summary; becomes the record's label on recall. | Yes |
28
+ | `--store` | Registry name, `@default` for the `default_kb`, or `@feedback` for the `feedback_kb`. | Yes |
29
+ | `--skill` | The skill to which the event relates. | No |
30
+ | `--model` | The model identifier in play. | No |
31
+ | `--harness` | The agent platform (`claude`, `rovo`); install-injected. Keep as-is. | Injected |
32
+ | `--tags` | Comma-separated tag list. | No |
33
+ | `--impact` | Impact rating: one of `low`, `medium`, `high`, `critical`. Omit to leave unrated. | No |
34
+ | `--amend` | Id of an existing event to rewrite in place instead of capturing a new one. | No |
35
+ | `--shared` | Permit a fresh capture into a store whose `visibility` is `shared`. See [Shared stores](#shared-stores). | No |
35
36
 
36
37
  A value-bearing flag accepts both `--summary text` and `--summary=text`. The event body is read from stdin to EOF; an empty body is allowed.
37
38
 
@@ -49,6 +50,12 @@ Choose the destination deliberately. When the lesson is specific to a project, p
49
50
 
50
51
  A caller whose destination is a configured role rather than a per-lesson judgment passes that role's sentinel: `--store @feedback` sends a record to the registry's `feedback_kb`, the KB that receives feedback about agent guidance.
51
52
 
53
+ ### Shared stores
54
+
55
+ A store's `.kb/config.yaml` declares its `visibility`: `shared` for a store published to collaborators, `private` otherwise; a store that does not declare it counts as `private`. The helper refuses a fresh capture into a `shared` store unless the invocation passes `--shared`, because a record published in that store's history cannot be withdrawn.
56
+
57
+ Never pass `--shared` by habit. On a `shared-store` refusal, read the event's summary and body as a collaborator would: Retry with `--shared` only when they contain nothing unfit for that audience, such as a credential, a personal detail, or a workplace-internal fact. Otherwise, capture into a private store, or report the event uncaptured. When you cannot tell, do not pass the flag. `--amend` is exempt, because it rewrites an event already in the named store.
58
+
52
59
  ### Amending an event
53
60
 
54
61
  `--amend <id>` rewrites an existing capture in place (for example, an event that a `capture-feedback` pass got wrong). Prefer amending over capturing a near-duplicate. Amend always rewrites `summary` and the body from the invocation. It overwrites `--skill`, `--model`, `--tags`, or `--impact` only when you pass that flag; any that you omit keep their existing value, as do the provenance fields (`id`, `captured-at`, `session`, `cwd`, `repo`, `harness`) and any `addressed-by` marks. To clear a curatorial field rather than edit content, use its `kb-update-events` mutator.
@@ -79,7 +86,7 @@ cat <<'EOF' | node {harness_home_dir}/skills/capture-event/capture-event.mjs \
79
86
  --summary "<one-line summary>" \
80
87
  --store <name|@default|@feedback> \
81
88
  --harness {harness_id} \
82
- [--skill <skill>] [--model <model>] [--tags <comma,separated>] [--impact <level>]
89
+ [--skill <skill>] [--model <model>] [--tags <comma,separated>] [--impact <level>] [--shared]
83
90
  <event body, may span multiple lines and contain any characters>
84
91
  EOF
85
92
  ```
@@ -99,6 +106,8 @@ On `ok: false`, handle the `error` code as follows:
99
106
  - `missing-store`: `--store` was omitted. Re-run with `--store <name>` for the KB named by the user, or `--store @default` for an environment-level lesson; the message lists the registered stores.
100
107
  - `store-not-registered`: The named store is not in `kb.yaml`. Confirm the store name or register it.
101
108
  - `readonly-store`: The store is marked readonly; captures are refused.
109
+ - `shared-store`: The store is shared and the invocation did not pass `--shared`. Act per [Shared stores](#shared-stores).
110
+ - `invalid-config`: The store's `.kb/config.yaml` is malformed, so its visibility is unknown and the capture is refused. The message names the file; report it and have the user repair it.
102
111
  - `no-default-store`: `--store @default` was given but `kb.yaml` does not configure a `default_kb`. Name a store explicitly or configure a default with `kb set-default`.
103
112
  - `no-feedback-store`: `--store @feedback` was given but `kb.yaml` does not configure a `feedback_kb`. Set `feedback_kb` in `kb.yaml` to the KB that receives feedback about agent guidance.
104
113
  - `schema-validation`: Report the `errors`, then supply the missing field and retry.