agentme 0.36.0 → 0.37.0

package/.xdrs/agentme/edrs/principles/skills/resolve-pr-comments/SKILL.test.md

@@ -0,0 +1,165 @@
+---
+skill: resolve-pr-comments
+skill-version: "4.0.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: End-to-end GitHub PR review, happy path with guided mode and a Phase 6 edit
+
+**Trigger / Input**
+
+"Let's review this PR: https://github.com/acme/widgets/pull/482" (run from a clean, up to
+date local clone of `acme/widgets`, which has 2 open comments).
+
+**Expected Behaviour**
+
+The skill: (1) parses the URL host as `github.com` and activates `github-connector`; (2)
+Phase 1 fetches PR #482 metadata and every comment, then confirms the local repo matches
+`acme/widgets` and offers to check out the PR branch; (3) Phase 2 calls `init` to write
+`.tmp/review-pr-482.md`'s header before analysing anything, then computes each comment's
+fields and calls `append-section` to write its section immediately, one comment at a time --
+rendering each section's `source` field as a clickable markdown link to the matching file in
+the local checkout (never a provider URL), `source-lines` with the commented line(s) plus
+padding, `diff-hunk-raw`/`author-raw`/`comment-url` verbatim from the connector,
+`possible-user-intention` (an under-20-word, silently generated read of the author's likely
+concern), and `possible-follow-ups` (2-4 candidate next actions); (4) Phase 3 renders the
+2-row summary table and asks the literal numbered 4-way automation-level question -- the
+human picks option 3 (guide all), so both comments use the guided flow; (5) Phase 4 walks
+each comment one at a time, rendering its full focus card before asking the human to choose
+an action, then drafts the reply/fix text, persists it as `pending-reply: drafted`, and shows
+one FYI outcome line -- no confirmation question, nothing sent yet; (6) Phase 6 gathers both
+now-drafted comments, renders a numbered consolidated preview table (`#`, `id`, title,
+action, resolve-on-apply) followed by each row's exact draft text, and the human uses a
+free-text instruction naming comment 2's `#` to change its reply text before applying both
+together in a single apply-all batch confirmation -- resolving comment 1's thread as
+requested -- then reports the final summary by action taken and send status.
+
+**Simulated Human Responses**
+1. "Yes, check out the PR branch."
+2. (Phase 3) "3. I want to guide all comments solutions."
+3. "For comment 1: confirm criticality, action = reply. Yes, resolve the thread once
+   applied." (accepts the drafted text unedited)
+4. "For comment 2: confirm criticality, action = fix." (drafted text left as-is at Phase 4)
+5. (Phase 6) "For comment 2, reply with 'Renamed per your suggestion, thanks!' instead, then
+   apply all now."
+
+**Assertions**
+
+- [ ] Skill activates `github-connector` because the URL host is `github.com`.
+- [ ] Skill calls `init` to write the tracking file's header before analysing any comment,
+      then calls `append-section` once per comment, immediately, one at a time -- never
+      accumulating every section in memory until the end.
+- [ ] Skill renders each section's `source` field as a markdown link to the matching local
+      file, relative to the tracking file's own location -- never a link to the provider's
+      website.
+- [ ] Skill's Phase 3 renders a summary table (`#`, title, author, automation-suggestion,
+      criticality) and asks the literal numbered 4-way automation-level question before
+      Phase 4 asks anything else.
+- [ ] Skill asks about exactly one comment at a time in Phase 4, posting each comment's full
+      focus card as its own chat message before the action question.
+- [ ] Skill shows no confirmation question in Phase 4 -- only a one-line FYI outcome after
+      each draft is persisted, for both comments.
+- [ ] Skill's Phase 6 renders a numbered consolidated preview table (`#`, `id`, title,
+      action, resolve-on-apply) followed by each row's exact draft text below the table.
+- [ ] Skill accepts a Phase 6 free-text instruction naming comment 2's preview `#` to change
+      its reply text before applying, persisting the change immediately.
+- [ ] Skill applies both comments' drafts together in a single apply-all batch confirmation
+      in Phase 6, resolving comment 1's thread as requested.
+- [ ] Skill suffixes both comment 1's reply (accepted as drafted) and comment 2's reply
+      (changed at Phase 6) with the identical `(resolve-pr-comments - guided)` literal --
+      no distinction between the two cases.
+- [ ] Skill records the section's original comment text under `comment-raw` and any existing
+      thread replies under `replies-raw`.
+- [ ] Skill populates `possible-user-intention` with an under-20-word inference silently,
+      with no dedicated confirmation prompt of its own.
+
+### Scenario 2: Phase 3's "something else" free text drives a mixed fully-auto/guided run
+
+**Trigger / Input**
+
+Phase 2 populates 3 open comments: comment A (a simple, repetitive rename request with a
+clean `suggested-fix`, classified `automation-suggestion: fully-auto`), comment B (a vague
+architectural question, classified `automation-suggestion: guided`), and comment C (a minor
+style nitpick, classified `automation-suggestion: fully-auto`, not mentioned in the human's
+free text below). At Phase 3, the human answers option 4 with "automate everything, but
+guide comment B".
+
+**Expected Behaviour**
+
+Phase 4 reaches comment A and, matching the free text's "automate everything", skips its
+focus card and action question entirely: before starting, it shows one starting banner line
+(`Starting comment A of 3 (fix): "<short title>".`), then auto-chooses `fix`, applies the
+`suggested-fix` verbatim, defaults `resolve-on-apply` from `can_resolve` with no ask, drafts
+and persists `pending-reply: drafted` immediately, and shows one brief outcome line
+(`Auto-handled comment A (fix): ...`). The drafted text carries the
+`(resolve-pr-comments - fully-auto)` suffix unconditionally. Comment B, explicitly named for
+guidance, still gets its full focus card and action question exactly as documented, with the
+human choosing `reply` and editing the drafted text, earning the
+`(resolve-pr-comments - guided)` suffix. Comment C, not explicitly addressed by the free
+text, follows its own `automation-suggestion` (`fully-auto`) and is handled the same
+no-question way as comment A, each with its own starting banner and outcome line. Phase 6
+later gathers all three comments together and requires the same explicit apply confirmation
+for all of them -- no comment's fully-auto origin grants it a bypass of that gate.
+
+**Simulated Human Responses**
+1. (Phase 3) "4. Automate everything, but guide comment B."
+2. "For comment B: action = reply. Use this reply text instead: 'We considered that
+   approach; here's why we didn't take it...'" (replaces the drafted text with free text)
+3. (Phase 6) "Apply all now."
+
+**Assertions**
+
+- [ ] Skill's Phase 3 renders the summary table and asks the literal numbered 4-way
+      automation-level question before Phase 4 begins.
+- [ ] Skill interprets the free-text option-4 answer against the numbered table, applying the
+      no-question path to comments A and C and the guided path to comment B by name.
+- [ ] Skill never shows comment A's or comment C's focus card or an action question for
+      either, auto-choosing and applying each one's action with no human confirmation.
+- [ ] Skill shows one starting banner line before each of comment A's and comment C's work
+      begins, and one brief outcome line after, suffixing both with
+      `(resolve-pr-comments - fully-auto)` unconditionally.
+- [ ] Skill shows comment B's full focus card and action question, unaffected by comments A
+      and C's no-question handling.
+- [ ] Skill suffixes comment B's reply -- replaced with human-supplied free text -- with
+      `(resolve-pr-comments - guided)`.
+- [ ] Skill's Phase 6 requires the same explicit apply confirmation for all three comments --
+      being drafted via the no-question path grants no bypass of Phase 6's gate.
+
+### Scenario 3: Phase 2 writes the tracking file incrementally, surviving a mid-run interruption
+
+**Trigger / Input**
+
+A PR has 6 open comments. The session runs Phase 2 against a brand-new tracking file, then is
+interrupted (e.g. context compaction or a cancelled session) immediately after the 4th
+comment's section has been written, before the 5th comment's fields are computed.
+
+**Expected Behaviour**
+
+Phase 2 first calls `init` to durably write `.tmp/review-pr-<N>.md`'s header (PR link, raw
+summary, auto-generated summary) before analysing any single comment. It then computes
+comment 1's fields and calls `append-section` to write its section immediately, repeating
+this one-comment-at-a-time for comments 2, 3, and 4 -- never holding more than one comment's
+computed-but-unwritten section in memory at a time. When the interruption happens right
+after comment 4's `append-section` call returns, comments 1-4 are already durably present on
+disk. A fresh invocation re-reads the existing file, finds comments 1-4 already recorded (and
+does not recompute or rewrite them), and resumes by computing and appending comments 5 and 6
+the same incremental way.
+
+**Simulated Human Responses**
+(none -- Phase 2 asks nothing; the interruption and resume are session-level events, not
+human decisions)
+
+**Assertions**
+
+- [ ] Skill calls `init` once, before computing any comment's fields, to write the tracking
+      file's header (PR link, raw summary, auto-generated summary).
+- [ ] Skill calls `append-section` once per comment, immediately after that comment's fields
+      are computed, rather than batching multiple comments' sections into one write.
+- [ ] Skill's on-disk tracking file already contains comments 1 through 4's full sections at
+      the moment of interruption, before comment 5 is ever analysed.
+- [ ] Skill's fresh invocation after the interruption re-reads the existing file and does not
+      recompute or rewrite comments 1-4's already-written sections.
+- [ ] Skill's fresh invocation computes and appends comments 5 and 6 the same
+      one-comment-at-a-time way, completing the file.
+

package/.xdrs/agentme/edrs/principles/skills/{400-pr-owner-assistant → resolve-pr-comments}/scripts/post-replies-azure-devops.js

@@ -2,14 +2,14 @@
 'use strict';
 
 /**
- * Applies pr-owner-assistant tracking-file drafts to a live Azure DevOps PR, using the
- * `az rest` commands documented in 251-azure-devops-connector's "Writing data" section.
+ * Applies resolve-pr-comments tracking-file drafts to a live Azure DevOps PR, using the
+ * `az rest` commands documented in azure-devops-connector's "Writing data" section.
  * Delegates every tracking-file read/write to the sibling `update-section.js` script so
  * there is exactly one place that understands the file format.
  *
  * Every write is verified by an independent read-back before the tracking file is ever
  * marked `pending-reply: applied` -- a zero exit code from `az rest` alone is never treated
- * as proof a write persisted (see 251-azure-devops-connector's Known Issues: a POST/PATCH
+ * as proof a write persisted (see azure-devops-connector's Known Issues: a POST/PATCH
  * can exit 0 without the change actually landing on the server).
  *
  * Usage:

package/.xdrs/agentme/edrs/principles/skills/{400-pr-owner-assistant → resolve-pr-comments}/scripts/post-replies-azure-devops.test.js

@@ -75,8 +75,8 @@ resolve-on-apply: false
 pending-reply: drafted
 reply-draft: |
   Agreed -- good catch. Renamed the parameter to a dedicated codeowners-app service
-  connection. Leaving this thread open until it is created. (pr-owner-assistant - with user
-  guidance)
+  connection. Leaving this thread open until it is created. (resolve-pr-comments -
+  guided)
 
 ### Split run() into smaller functions
 id: thread-comment/200.1
@@ -90,8 +90,8 @@ action: fix
 resolve-on-apply: true
 pending-reply: drafted
 reply-draft: |
-  Fixed -- split run() into named single-purpose functions. (pr-owner-assistant - with
-  defaults)
+  Fixed -- split run() into named single-purpose functions. (resolve-pr-comments -
+  guided)
 
 ### Already handled comment, should never be touched
 id: thread-comment/300.1
@@ -208,7 +208,7 @@ test('REGRESSION: does not mark status resolved when PATCH exits 0 but status ne
 
 test('skips re-posting when the exact reply is already present on the live thread, but still marks applied', () => {
   const alreadyPostedText =
-    'Agreed -- good catch. Renamed the parameter to a dedicated codeowners-app service connection. Leaving this thread open until it is created. (pr-owner-assistant - with user guidance)';
+    'Agreed -- good catch. Renamed the parameter to a dedicated codeowners-app service connection. Leaving this thread open until it is created. (resolve-pr-comments - guided)';
   const { file, env } = setup({
     threads: {
       100: {

package/.xdrs/agentme/edrs/principles/skills/{400-pr-owner-assistant → resolve-pr-comments}/scripts/post-replies-github.js

@@ -2,15 +2,15 @@
 'use strict';
 
 /**
- * Applies pr-owner-assistant tracking-file drafts to a live GitHub PR, using the `gh`
- * commands documented in 250-github-connector's "Writing data" section. Delegates every
+ * Applies resolve-pr-comments tracking-file drafts to a live GitHub PR, using the `gh`
+ * commands documented in github-connector's "Writing data" section. Delegates every
  * tracking-file read/write to the sibling `update-section.js` script so there is exactly
  * one place that understands the file format. Mirrors post-replies-azure-devops.js's
  * interface and verify-after-write discipline for parity across both connectors.
  *
  * Every write is confirmed by an independent read-back before the tracking file is ever
  * marked `pending-reply: applied` -- not because `gh` is known to exit 0 without persisting
- * (unlike `az rest`, see 251-azure-devops-connector's Known Issues), but so both scripts
+ * (unlike `az rest`, see azure-devops-connector's Known Issues), but so both scripts
  * make the same guarantee and a GraphQL mutation's rarer partial-failure shape is still
  * caught.
  *

package/.xdrs/agentme/edrs/principles/skills/{400-pr-owner-assistant → resolve-pr-comments}/scripts/post-replies-github.test.js

@@ -115,7 +115,7 @@ action: fix
 resolve-on-apply: true
 pending-reply: drafted
 reply-draft: |
-  Fixed -- renamed per your suggestion, thanks! (pr-owner-assistant skill - using defaults)
+  Fixed -- renamed per your suggestion, thanks! (resolve-pr-comments - guided)
 
 ### General question about the release plan
 id: issue-comment/555
@@ -129,8 +129,8 @@ action: reply
 resolve-on-apply: false
 pending-reply: drafted
 reply-draft: |
-  Targeting the next minor release once CI is green. (pr-owner-assistant skill - using
-  defaults)
+  Targeting the next minor release once CI is green. (resolve-pr-comments -
+  guided)
 
 ### Already handled comment, should never be touched
 id: review-comment/77777
@@ -235,7 +235,7 @@ test('REGRESSION: does not mark status resolved when the mutation exits 0 but is
 test('skips re-posting when the exact reply is already present, but still marks applied', () => {
   const { file, env } = setup({
     issueComments: [],
-    reviewComments: [{ id: 1, body: 'Fixed -- renamed per your suggestion, thanks! (pr-owner-assistant skill - using defaults)', in_reply_to_id: 91234 }],
+    reviewComments: [{ id: 1, body: 'Fixed -- renamed per your suggestion, thanks! (resolve-pr-comments - guided)', in_reply_to_id: 91234 }],
     threads: { 91234: { nodeId: 'PRT_1', isResolved: false } },
     // If the script incorrectly tries to POST again, this makes it fail loudly.
     failPost: ['91234'],

package/.xdrs/agentme/edrs/principles/skills/{400-pr-owner-assistant → resolve-pr-comments}/scripts/update-section.js

@@ -2,11 +2,13 @@
 'use strict';
 
 /**
- * Safe read/update helper for a pr-owner-assistant tracking file
+ * Safe read/update helper for a resolve-pr-comments tracking file
  * (.tmp/review-pr-<N>.md), keyed by each section's stable `id:` value
  * instead of its title text. See SKILL.md's "Editing the tracking file" note.
  *
  * Usage:
+ *   update-section.js init <file> <pr-number> <pr-link> <auto-summary...>  (raw PR summary from stdin)
+ *   update-section.js append-section <file>                               (full "### ..." section from stdin)
  *   update-section.js list <file>
  *   update-section.js get <file> <id> <field>
  *   update-section.js set <file> <id> <field> <value...>
@@ -28,17 +30,20 @@ const SCALAR_FIELDS = [
   'possible-user-intention',
   'suggested-fix-assessment',
   'criticality',
+  'automation-suggestion',
   'action',
   'resolve-on-apply',
   'pending-reply',
 ];
 const BLOCK_FIELDS = ['source-lines', 'diff-hunk-raw', 'suggested-fix', 'comment-raw', 'reply-draft'];
-const LIST_FIELDS = ['replies-raw', 'possible-follow-ups'];
+const LIST_FIELDS = ['replies-raw', 'possible-follow-ups', 'similar-to'];
 const ALL_FIELDS = [...SCALAR_FIELDS, ...BLOCK_FIELDS, ...LIST_FIELDS];
 const NEXT_FIELD_RE = new RegExp(`^(?:${ALL_FIELDS.join('|')}):`);
 
 function usage() {
   return `Usage:
+  update-section.js init <file> <pr-number> <pr-link> <auto-summary...>  (raw PR summary from stdin)
+  update-section.js append-section <file>                               (full "### ..." section from stdin)
   update-section.js list <file>
   update-section.js get <file> <id> <field>
   update-section.js set <file> <id> <field> <value...>
@@ -142,6 +147,59 @@ function main(argv) {
     return;
   }
 
+  if (cmd === 'init') {
+    const [prNumber, prLink, ...summaryParts] = rest;
+    if (!prNumber || !prLink || summaryParts.length === 0) {
+      console.error(usage());
+      process.exit(1);
+      return;
+    }
+    if (fs.existsSync(file)) {
+      throw new Error(`refusing to overwrite existing file: ${file}`);
+    }
+    const rawSummary = readStdin().replace(/\n$/, '');
+    const autoSummary = summaryParts.join(' ');
+    fs.writeFileSync(
+      file,
+      `# PR #${prNumber}\n\n${prLink}\n\n${rawSummary}\n\n**Summary**: ${autoSummary}\n`,
+    );
+    console.log('OK');
+    return;
+  }
+
+  if (cmd === 'append-section') {
+    if (!fs.existsSync(file)) {
+      throw new Error(`file does not exist: ${file}`);
+    }
+    const stdin = readStdin().replace(/\n$/, '');
+    if (!stdin.startsWith('### ')) {
+      throw new Error('stdin must be a full section starting with "### "');
+    }
+    const stdinLines = stdin.split('\n');
+    const idLine = stdinLines.find((l) => /^id:\s*/.test(l));
+    if (!idLine) {
+      throw new Error('stdin section is missing an "id:" line');
+    }
+    const newId = idLine.replace(/^id:\s*/, '').trim();
+    const original = fs.readFileSync(file, 'utf8');
+    const hadTrailingNewline = original.endsWith('\n');
+    const lines = original.split('\n');
+    let duplicate = true;
+    try {
+      findSectionById(lines, newId);
+    } catch (err) {
+      if (!/^no section found/.test(err.message)) throw err;
+      duplicate = false;
+    }
+    if (duplicate) {
+      throw new Error(`a section with id "${newId}" already exists in ${file}`);
+    }
+    const separator = lines[lines.length - 1] === '' ? [] : [''];
+    writeBack(file, [...lines, ...separator, ...stdinLines], hadTrailingNewline);
+    console.log('OK');
+    return;
+  }
+
   const original = fs.readFileSync(file, 'utf8');
   const hadTrailingNewline = original.endsWith('\n');
   const lines = original.split('\n');
@@ -151,7 +209,16 @@ function main(argv) {
     for (let s = 0; s < idx.length; s++) {
       const start = idx[s];
       const end = s + 1 < idx.length ? idx[s + 1] : lines.length;
-      const row = { id: '', status: '', action: '', 'pending-reply': '', 'resolve-on-apply': '' };
+      const row = {
+        id: '',
+        'author-raw': '',
+        status: '',
+        criticality: '',
+        'automation-suggestion': '',
+        action: '',
+        'pending-reply': '',
+        'resolve-on-apply': '',
+      };
       for (const key of Object.keys(row)) {
         try {
           const f = findField(lines, start, end, key);
@@ -160,13 +227,27 @@ function main(argv) {
           // field absent in a malformed section -- leave blank, never fail `list`
         }
       }
+      let similarTo = '';
+      try {
+        const f = findField(lines, start, end, 'similar-to');
+        similarTo = lines
+          .slice(f.contentStart, f.contentEnd)
+          .map((l) => l.replace(/^ {2}- /, ''))
+          .join(', ');
+      } catch {
+        // field absent in a malformed section -- leave blank, never fail `list`
+      }
       // Bullets avoid relying on column/tab alignment, which breaks once field values vary in width.
       console.log(`- id: ${row.id}`);
       console.log(`  title: ${lines[start].slice(4).trim()}`);
+      console.log(`  author-raw: ${row['author-raw']}`);
       console.log(`  status: ${row.status}`);
+      console.log(`  criticality: ${row.criticality}`);
+      console.log(`  automation-suggestion: ${row['automation-suggestion']}`);
       console.log(`  action: ${row.action}`);
       console.log(`  pending-reply: ${row['pending-reply']}`);
       console.log(`  resolve-on-apply: ${row['resolve-on-apply']}`);
+      console.log(`  similar-to: ${similarTo}`);
     }
     return;
   }

package/.xdrs/agentme/edrs/principles/skills/{400-pr-owner-assistant → resolve-pr-comments}/scripts/update-section.test.js

@@ -33,20 +33,25 @@ reply-draft: |
 id: review-comment/222
 status: open
 source: [lib/src/foo.ts:10-10](../lib/src/foo.ts#L10-L10)
+author-raw: octocat
 suggested-fix: |
   const value = compute();
 suggested-fix-assessment: accept-as-is
+criticality: medium
+automation-suggestion: fully-auto
 comment-raw: |
   Shall we rename this?
 replies-raw:
 possible-follow-ups:
   - "fix: rename for consistency"
   - "mark won't-fix: keep current naming"
+similar-to:
+  - review-comment/333
 action: fix
 resolve-on-apply: true
 pending-reply: drafted
 reply-draft: |
-  Renamed as suggested. (pr-owner-assistant skill - using defaults)
+  Renamed as suggested. (resolve-pr-comments - guided)
 `;
 
 function writeFixture(content = FIXTURE) {
@@ -55,6 +60,10 @@ function writeFixture(content = FIXTURE) {
   return file;
 }
 
+function tmpFilePath(name = 'review-pr-999.md') {
+  return path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'update-section-test-')), name);
+}
+
 function run(args, input) {
   try {
     const stdout = execFileSync('node', [SCRIPT, ...args], { input, encoding: 'utf8' });
@@ -73,8 +82,12 @@ test('list renders one bullet block per section, not tab-aligned columns', () =>
   assert.match(stdout, /^ {2}title: Contributor offers to help$/m);
   assert.match(stdout, /^ {2}status: open$/m);
   assert.match(stdout, /- id: review-comment\/222/);
+  assert.match(stdout, /^ {2}author-raw: octocat$/m);
+  assert.match(stdout, /^ {2}criticality: medium$/m);
+  assert.match(stdout, /^ {2}automation-suggestion: fully-auto$/m);
   assert.match(stdout, /^ {2}action: fix$/m);
   assert.match(stdout, /^ {2}pending-reply: drafted$/m);
+  assert.match(stdout, /^ {2}similar-to: review-comment\/333$/m);
 });
 
 test('get returns a scalar field value', () => {
@@ -197,3 +210,97 @@ test('set-block on a scalar-only field fails and points to set', () => {
   assert.notEqual(status, 0);
   assert.match(stderr, /use set \(scalar\)/);
 });
+
+test('get/set support the automation-suggestion scalar field', () => {
+  const file = writeFixture();
+  const { stdout: before } = run(['get', file, 'review-comment/222', 'automation-suggestion']);
+  assert.equal(before.trim(), 'fully-auto');
+  const { status } = run(['set', file, 'review-comment/222', 'automation-suggestion', 'guided']);
+  assert.equal(status, 0);
+  const { stdout: after } = run(['get', file, 'review-comment/222', 'automation-suggestion']);
+  assert.equal(after.trim(), 'guided');
+});
+
+test('get/set-list support the similar-to list field', () => {
+  const file = writeFixture();
+  const { stdout: before } = run(['get', file, 'review-comment/222', 'similar-to']);
+  assert.equal(before, 'review-comment/333\n');
+  const { status } = run(
+    ['set-list', file, 'review-comment/222', 'similar-to'],
+    'review-comment/333\nreview-comment/444\n',
+  );
+  assert.equal(status, 0);
+  const { stdout: after } = run(['get', file, 'review-comment/222', 'similar-to']);
+  assert.equal(after, 'review-comment/333\nreview-comment/444\n');
+});
+
+test('init creates a new tracking file with the PR header and raw summary', () => {
+  const file = tmpFilePath();
+  const { status, stdout } = run(
+    ['init', file, '999', 'https://github.com/acme/widget/pull/999', 'Adds', 'retry', 'logic'],
+    'Raw PR body text.\n\nSecond paragraph.\n',
+  );
+  assert.equal(status, 0);
+  assert.equal(stdout.trim(), 'OK');
+  const content = fs.readFileSync(file, 'utf8');
+  assert.equal(
+    content,
+    '# PR #999\n\nhttps://github.com/acme/widget/pull/999\n\nRaw PR body text.\n\nSecond paragraph.\n\n**Summary**: Adds retry logic\n',
+  );
+});
+
+test('init refuses to overwrite an existing file', () => {
+  const file = writeFixture();
+  const { status, stderr } = run(
+    ['init', file, '999', 'https://example.com/pr/999', 'Some', 'summary'],
+    'Raw body.\n',
+  );
+  assert.notEqual(status, 0);
+  assert.match(stderr, /refusing to overwrite existing file/);
+});
+
+test('append-section adds a new section after the last one, separated by exactly one blank line', () => {
+  const file = writeFixture();
+  const newSection =
+    '### New finding\nid: issue-comment/777\nstatus: open\nsource: (PR conversation)\ncomment-raw: |\n  A brand new comment.\nreplies-raw:\npossible-follow-ups:\naction:\nresolve-on-apply: false\npending-reply: none\nreply-draft: |\n';
+  const { status } = run(['append-section', file], newSection);
+  assert.equal(status, 0);
+  const content = fs.readFileSync(file, 'utf8');
+  assert.match(
+    content,
+    /\(resolve-pr-comments - guided\)\n\n### New finding\nid: issue-comment\/777/,
+  );
+  const { stdout } = run(['list', file]);
+  assert.match(stdout, /- id: issue-comment\/777/);
+});
+
+test('append-section fails when the id already exists', () => {
+  const file = writeFixture();
+  const { status, stderr } = run(
+    ['append-section', file],
+    '### Duplicate\nid: issue-comment/111\nstatus: open\n',
+  );
+  assert.notEqual(status, 0);
+  assert.match(stderr, /a section with id "issue-comment\/111" already exists/);
+});
+
+test('append-section fails when the file does not exist', () => {
+  const file = tmpFilePath();
+  const { status, stderr } = run(['append-section', file], '### X\nid: a/1\n');
+  assert.notEqual(status, 0);
+  assert.match(stderr, /file does not exist/);
+});
+
+test('append-section fails when stdin is not a full section', () => {
+  const file = writeFixture();
+  const { status, stderr } = run(['append-section', file], 'not a section\nid: a/1\n');
+  assert.notEqual(status, 0);
+  assert.match(stderr, /must be a full section/);
+});
+
+test('append-section fails when stdin has no id: line', () => {
+  const file = writeFixture();
+  const { status, stderr } = run(['append-section', file], '### No id here\nstatus: open\n');
+  assert.notEqual(status, 0);
+  assert.match(stderr, /missing an "id:" line/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.39.0"
@@ -18,6 +18,6 @@
     "url": "https://github.com/flaviostutz/agentme.git"
   },
   "devDependencies": {
-    "xdrs-core": "^0.47.0"
+    "xdrs-core": "^0.49.0"
   }
 }