Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Merge batch 11-06 k0840: #3291 (#3292)

0xken156a76854db3eb
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 7af70409f..63e683857 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -72,6 +72,7 @@ import { launchRefusedLine, leadArrived, LEAD_CLAIM_MS, leadEffort, leadJoined,
import { ACK_ONLY_HINT, isAcknowledgement } from './acknowledgements.js'
import { allowedDrops, approvedDropNotice, droppedLines, MAX_APPROVALS, MAX_DROPPED_LINES, refuseOverBudget, refuseRepeats, type ApprovalRow, type DroppedLine } from './ruleGuard.js'
import { appendRouting, coordinatorNameOf, routingSummary, FIRST_INSTRUCTIONS, FIRST_SUMMARY, instructionsHash, instructionsTextSchema, legacyRoleName, liveNotes, MAX_NOTES, noteTextSchema, roleNameSchema, summarySchema, type PmNote } from './instructions.js'
+import { repeatedRules } from './instructionsDiff.js'
import { INSTRUCTIONS_TEMPLATE } from './instructionsTemplate.js'
import { BUILT_IN_HEADING, tidySaved } from './pmSchedule.js'
import { contractRefusal, missingContract } from './taskContract.js'
@@ -253,7 +254,9 @@ export const commandSchema = z.discriminatedUnion('type', [
dropped: z.array(z.object({ text: z.string().trim().min(1).max(2000), kind: z.enum(['merged', 'expired', 'rule']) }).strict())
.max(MAX_DROPPED_LINES).optional(),
// The coordinator's daily tidy, done by this save (pmSchedule.ts tidyRequest).
- tidy: z.literal(true).optional() }).strict(),
+ tidy: z.literal(true).optional(),
+ // A person keeping a line that repeats one the document has, and why (ruleGuard.ts refuseRepeats; the coordinator's is ignored).
+ repeatReason: z.string().trim().min(1).max(100).regex(/^[^\r\n]*$/, 'Give the reason in one line.').optional() }).strict(),
// The project's rules record, saved on the revision the writer read (policy.ts). A person writes in their own name; the
// project's PM only with `askedIn`, the person's own chat message it passes on.
z.object({ type: z.literal('rules.set'), projectId: id, baseRevision: z.number().int().nonnegative().safe(), rules: projectRulesSchema,
@@ -490,7 +493,7 @@ const WORDS: Partial<Record<Command['type'], readonly string[]>> = {
'project.create': ['name', 'brief'],
'project.rename': ['name'],
'project.report': ['text'],
- 'instructions.save': ['text', 'summary', 'dropped[].text'],
+ 'instructions.save': ['text', 'summary', 'repeatReason', 'dropped[].text'],
'note.add': ['text'],
'project.coordinatorName': ['name'],
'rule.set': ['text'],
@@ -2066,14 +2069,18 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
const before = context.instructions?.revision === current ? context.instructions.text : onTemplate ? INSTRUCTIONS_TEMPLATE
: fail('INSTRUCTIONS_UNAVAILABLE', 'This project\'s instructions cannot be read now. Try again in a moment.', 503)
// A line the save adds that the document already has is refused with the existing line quoted (#3283).
- refuseRepeats(before, command.text)
+ // A person may keep both lines with a reason, which the History's summary records; the coordinator may not (#3568).
+ const kept = actor.kind === 'person' && command.repeatReason && repeatedRules(before, command.text).length > 0
+ refuseRepeats(before, command.text, !!kept)
+ const because = kept ? ` (kept a repeated line: ${command.repeatReason})` : ''
+ const summary = because && command.summary.length + because.length > 200 ? `${command.summary.slice(0, 199 - because.length)}…${because}` : command.summary + because
// No part grows past its size budget: core, each role section, people notes, the whole (#3392).
refuseOverBudget(before, command.text)
// A person's rule, or who gave it, is dropped only by that person or with their own message approving it (#3151).
const { told, rules } = allowedDrops(state, project, before, command.text, sender, command.approvals ?? [], context.approvals ?? [],
context.instructions?.at ?? 0, context.pullRequestMerges ?? {})
// Every line it dropped, with its kind and who gave it, kept with the revision for the History (River, 11-05).
- saveInstructions(project, current, command.text, command.summary, askedBy, droppedLines(before, command.text, command.dropped ?? [], rules))
+ saveInstructions(project, current, command.text, summary, askedBy, droppedLines(before, command.text, command.dropped ?? [], rules))
// The coordinator's save that says it is the tidy is that tidy done (pmSchedule.ts tidyRequest); a correction it saves
// meanwhile is not (review of #3112).
if (actor.kind === 'agent' && command.tidy) tidySaved(projectOf(state, project.id), current + 1)
diff --git a/backend/src/superTabs/instructions.test.ts b/backend/src/superTabs/instructions.test.ts
index fdff74ea8..013a7e0cd 100644
--- a/backend/src/superTabs/instructions.test.ts
+++ b/backend/src/superTabs/instructions.test.ts
@@ -596,6 +596,48 @@ describe('an instructions save refuses a rule that is already there', () => {
})
})
+// Task #3568 (anh Dee, 11-06, from lamp): the same rule in other words is refused too; a person may still keep both, saying why.
+describe('an instructions save refuses a rule said again in other words', () => {
+ const save = (text: string, extra: Partial<Extract<Command, { type: 'instructions.save' }>> = {}): Command =>
+ ({ type: 'instructions.save', projectId: 'lead', baseRevision: 1, text, summary: 'Added a rule', ...extra })
+ const rule = 'Every phone app task runs on Tony\'s Mac first, its Engineer and its Tester both (owner, 4 Nov).'
+ const base = ['# Project instructions', '', '## Rules', '', `- ${rule}`].join('\n')
+ const stored = { instructions: { revision: 1, text: base, at: 500 } }
+ const reworded = 'Its Engineer and its Tester both run every phone app task on Tony\'s Mac first.'
+ const caught = (run: () => unknown) => {
+ try { run() } catch (error) { return error as { code: string; status: number; message: string } }
+ throw new Error('the save went through')
+ }
+
+ it('refuses a reworded repeat, quoting the existing line', () => {
+ const f = fixture()
+ const refused = caught(() => f.run(save(`${base}\n- ${reworded}`), owner, stored))
+ expect(refused).toMatchObject({ code: 'INSTRUCTIONS_RULE_REPEATED', status: 409 })
+ expect(refused.message).toContain(`"${rule}"`)
+ expect(f.state.projects![0]).toMatchObject({ instructionsRevision: 1 })
+ })
+
+ it('saves a genuinely new rule', () => {
+ const f = fixture()
+ expect(f.run(save(`${base}\n- Release notes list every pull request merged since the last release (owner, 6 Nov).`), owner, stored).result)
+ .toMatchObject({ revision: 2 })
+ })
+
+ it('lets a person keep both by giving a reason, which the revision\'s summary records', () => {
+ const f = fixture()
+ const effects = f.run(save(`${base}\n- ${reworded}`, { repeatReason: 'this one is for the Tester role only' }), owner, stored)
+ expect(effects.result).toMatchObject({ revision: 2 })
+ expect(JSON.stringify(effects)).toContain('this one is for the Tester role only')
+ })
+
+ it('does not let the coordinator force it', () => {
+ const f = fixture()
+ const lead = f.add('lead', 'lead', true)
+ expect(caught(() => f.run(save(`${base}\n- ${reworded}`, { repeatReason: 'because', askedBy: 'owner' }), as(lead), stored)))
+ .toMatchObject({ code: 'INSTRUCTIONS_RULE_REPEATED' })
+ })
+})
+
// River, 11-05 (review of #3202): saves the server makes itself meet the repeat refusal too. The daily tidy is an
// instructions.save, checked like any; an older client's rule.set appends one Routing line and must not add a repeat either.
describe('server-made instruction saves and the repeat refusal', () => {
diff --git a/backend/src/superTabs/instructionsDiff.test.ts b/backend/src/superTabs/instructionsDiff.test.ts
index 9fbb4b6e0..e053d3e8e 100644
--- a/backend/src/superTabs/instructionsDiff.test.ts
+++ b/backend/src/superTabs/instructionsDiff.test.ts
@@ -154,6 +154,21 @@ describe('repeatedRules', () => {
expect(repeatedRules(base, base + '- Pushes its branch as it goes and opens a draft pull request.\n')).toHaveLength(1)
})
+ // Task #3568 (anh Dee, 11-06, from lamp): a rule saved again in other words is a repeat too.
+ it('finds a rule said again in other words and in another order', () => {
+ const reordered = 'Its Engineer and its Tester both run every phone app task on Tony\'s Mac first (Faye, 11-05).'
+ expect(repeats(reordered)).toEqual([{ added: reordered, existing: rule }])
+ expect(repeats('Every phone app task runs first on Tony\'s Mac: its Engineer and its Tester both.')).toHaveLength(1)
+ })
+
+ it('does not find a reworded line whose negation, limit or number changed, or another rule', () => {
+ expect(repeats('Its Engineer but not its Tester runs every phone app task on Tony\'s Mac first.')).toEqual([])
+ expect(repeats('Its Engineer and its Tester both run every phone app task on Tony\'s Mac first, unless urgent.')).toEqual([])
+ expect(repeats('Its Engineer and its Tester both run every phone app task on 2 Macs first.')).toEqual([])
+ expect(repeats('Every web app task runs on the Linux box first, its Engineer and its Tester both.')).toEqual([])
+ expect(repeats('Phone app tasks run on Macs.')).toEqual([])
+ })
+
it('finds an attributed rule repeated in another section', () => {
const base = '# Project\n\n## PM\n\n- Decides, never asks the owner to choose (Ken, 2026-11-04).\n'
const added = '- Decides, never asks the owner to choose (Faye, 11-05).'
diff --git a/backend/src/superTabs/instructionsDiff.ts b/backend/src/superTabs/instructionsDiff.ts
index fe34e8f9e..f9475dc95 100644
--- a/backend/src/superTabs/instructionsDiff.ts
+++ b/backend/src/superTabs/instructionsDiff.ts
@@ -288,6 +288,25 @@ const MIN_REPEAT_WORDS = 4
/** Repeats one refusal lists; more are cut. */
export const MAX_REPEATS = 20
+/** Fewest distinct content words of a line that can be a reworded repeat, and the share of the two lines' words they must have
+ * in common (task #3568): set high, so a line that only shares a topic with another is a new rule. */
+const MIN_REWORDED_WORDS = 6
+const REWORDED_SIMILARITY = 0.85
+/** Words whose change makes a different rule: a negation, a limit, an exception, a quantity (a number is checked apart). */
+const SUBSTANCE = new Set(['no', 'not', 'never', 'none', 'nor', 'nothing', 'without', 'but', 'except', 'unless', 'only', 'before', 'after',
+ 'until', 'least', 'most', 'more', 'less', 'fewer', 'max', 'min', 'maximum', 'minimum', 'any', 'all', 'every', 'each', 'one', 'once',
+ 'may', 'must', 'should', 'can', 'cannot', 'always', 'else', 'instead', 'also'])
+
+/** Whether [added] says the same as a line of [existing] words in other words: nearly the same set of content words, in any
+ * order, and none of the words that differ a negation, limit or number (so "but not its Tester" is a change, not a rewording). */
+function rewordedAs(added: Segment, existing: Set<string>): boolean {
+ if (added.words.size < MIN_REWORDED_WORDS || existing.size < MIN_REWORDED_WORDS) return false
+ const common = [...added.words].filter(w => existing.has(w)).length
+ if (common / (added.words.size + existing.size - common) < REWORDED_SIMILARITY) return false
+ const differ = [...added.words].filter(w => !existing.has(w)).concat([...existing].filter(w => !added.words.has(w)))
+ return !differ.some(w => SUBSTANCE.has(w) || /\d/.test(w))
+}
+
/**
* The lines [after] adds, or rewrites, that say what a line it keeps already says (task #3283, Leo 11-05, from lamp: a PM
* saved a rule the document had as if it were new, which hid that it had skipped it). Conservative: a repeat has the same
@@ -299,7 +318,7 @@ export const MAX_REPEATS = 20
export function repeatedRules(before: string, after: string): RepeatedRule[] {
const old = new Map<string, number>()
for (const item of items(before)) old.set(item.key, (old.get(item.key) ?? 0) + 1)
- const kept = new Map<string, { text: string; path: string; attributed: boolean }[]>()
+ const kept = new Map<string, { text: string; path: string; attributed: boolean; words: Set<string> }[]>()
const added: { segment: Segment; path: string }[] = []
for (const item of items(after)) {
if (item.heading) continue
@@ -309,13 +328,15 @@ export function repeatedRules(before: string, after: string): RepeatedRule[] {
if (segment.seq.length < MIN_REPEAT_WORDS) continue
if (n) {
const key = segment.seq.join(' ')
- kept.set(key, [...kept.get(key) ?? [], { text: segment.text, path: item.path, attributed: segment.people.length > 0 }])
+ kept.set(key, [...kept.get(key) ?? [], { text: segment.text, path: item.path, attributed: segment.people.length > 0, words: segment.words }])
} else added.push({ segment, path: item.path })
}
}
const repeats: RepeatedRule[] = []
+ const candidates = [...kept.values()].flat()
for (const { segment, path } of added) {
- const same = kept.get(segment.seq.join(' '))?.find(k => k.path === path || (k.attributed && segment.people.length > 0))
+ const fits = (k: { path: string; attributed: boolean }) => k.path === path || (k.attributed && segment.people.length > 0)
+ const same = kept.get(segment.seq.join(' '))?.find(fits) ?? candidates.find(k => fits(k) && rewordedAs(segment, k.words))
if (same) repeats.push({ added: segment.text, existing: same.text })
}
return repeats
diff --git a/backend/src/superTabs/ruleGuard.ts b/backend/src/superTabs/ruleGuard.ts
index ee043e449..ff12d4e20 100644
--- a/backend/src/superTabs/ruleGuard.ts
+++ b/backend/src/superTabs/ruleGuard.ts
@@ -134,16 +134,19 @@ export function allowedDrops(state: SuperTabState, project: SwarmProject, before
/**
* Refuses a save that adds a line repeating one the document keeps (task #3283, Leo 11-05, from lamp: a PM saved a rule the
- * instructions already had as if new, which hid that it had skipped it). Each repeat is listed with the existing line quoted;
- * a change meant is made on that line. Conservative: only the same words (instructionsDiff.ts repeatedRules).
+ * instructions already had as if new, which hid that it had skipped it; #3568, anh Dee 11-06: also the same rule in other
+ * words, instructionsDiff.ts repeatedRules). Each repeat is listed with the existing line quoted; a change meant is made on
+ * that line. A person may keep both by giving a reason (repeatReason, [forced]); the coordinator never does.
*/
-export function refuseRepeats(before: string, after: string): void {
+export function refuseRepeats(before: string, after: string, forced = false): void {
+ if (forced) return
const repeats = repeatedRules(before, after)
if (!repeats.length) return
const shown = repeats.slice(0, MAX_REPEATS)
fail('INSTRUCTIONS_RULE_REPEATED', [
- 'Not saved: this adds a line the instructions already have, so it would be read twice. Check that rule before adding it: '
- + 'it may be one you skipped. If you meant to change it, change that line in place instead of adding another.',
+ 'Not saved: this adds a line that says what the instructions already say, so it would be read twice. Check that rule before '
+ + 'adding it: it may be one you skipped. If you meant to change it, change that line in place instead of adding another. '
+ + 'Only a member who means to keep both lines saves them, giving a reason (repeatReason).',
...shown.map(repeat => `- Existing line: "${cut(repeat.existing)}" (added again as "${cut(repeat.added)}")`),
...(repeats.length > shown.length ? [`- And ${repeats.length - shown.length} more.`] : []),
].join('\n'), 409, { repeated: shown })
diff --git a/docs/plans/2026-11-06-instructions-near-duplicate-plan.md b/docs/plans/2026-11-06-instructions-near-duplicate-plan.md
new file mode 100644
index 000000000..7a43c9a27
--- /dev/null
+++ b/docs/plans/2026-11-06-instructions-near-duplicate-plan.md
@@ -0,0 +1,37 @@
+# Instructions save refuses a reworded repeat — Plan (task #3568)
+
+**Goal:** Saving a project's instructions refuses an added line that says what an existing line already says, reworded or
+not, quoting the existing line; a person may force the save by giving a reason.
+
+**Architecture:** #3283 already refuses a line with the same content words in the same order (`repeatedRules`,
+`refuseRepeats`). This adds a second match to `repeatedRules` (same content words in any order, up to a set similarity, with
+no changed negation, limit or number), and an optional `repeatReason` on `instructions.save`, honoured only from a person.
+No stored data, no new state.
+
+**Tech Stack:** TypeScript, vitest (backend `src/superTabs/`).
+
+**Spec:** the task brief (#3568). Way of working: this plan's tests first, then the code; no subagent-driven development.
+
+## Global Constraints
+- Backend only; nothing in `cli/src/core`.
+- A line changed in substance (negation, limit such as "unless"/"only", a number) is never a repeat; the #3283 tests keep passing.
+- Only a person forces a save; a coordinator's `repeatReason` is ignored and the refusal stands, saying a member decides.
+- The reason is kept in the revision's summary, so the History shows the repeat was meant.
+
+## Review Focus
+- False positives of the similarity (a long line with one word swapped) and that the guard words stop them where meaning differs.
+- That an agent cannot force a save.
+
+## Task 1: Reworded repeats (`instructionsDiff.ts`)
+**Files:** `backend/src/superTabs/instructionsDiff.ts`, `instructionsDiff.test.ts`
+**Interfaces:** `repeatedRules(before, after)` unchanged; finds also a near-duplicate (word set Jaccard ≥ 0.85, ≥ 6 words, no
+guard word in the words that differ).
+- [ ] Failing tests: reordered/reworded line is found, a changed guard word/number is not, a different rule is not.
+- [ ] Code: similarity fallback after the exact lookup.
+
+## Task 2: Person's forced save (`commands.ts`, `ruleGuard.ts`)
+**Files:** `backend/src/superTabs/commands.ts`, `ruleGuard.ts`, `instructions.test.ts`
+**Interfaces:** `instructions.save.repeatReason?: string (1-100)`; `refuseRepeats(before, after, forced?)`.
+- [ ] Failing tests: reworded repeat refused with the line quoted; new rule passes; a person's save with a reason passes and the
+ summary keeps it; a coordinator's save with a reason is still refused.
+- [ ] Code.