Scope cleanup - low priority

[LannyRipple]

Problem or motivation

I'm working on getting one of our repo's into compliance with the Error Architecture for AgentForce services program. I've got a directory, reports/, that is being used for transient docs. I notice Twining using it for scope. This directory will be cleaned up before merge so the scope will go away but Twining will still have records of it. Not a big deal for a small repo. If there's no such scope it won't get asked about (except by a larger controlling scope).

Additionally for this project I've seen a lot of decisions and warnings go into Twining that seem transient to this project.

Over time it seems like such things might lead to stale data in Twining.

A decision made during the Error Architecture work. Decision and rationale are good. I'm wondering if future Claude's are going to wonder about and go looking for "HMS Lancaster", "Wave 3", "M6 6.4 compliance" and when not found start hallucinating explanations.

Proposed solution

Provide a garbage collection mechanism for Twining. This could be just a plugin in the marketplace with a command that has an agent review Twining data and suggests stale data to be removed or non-sequitur references cleaned up.

Alternatives considered

No response

Component

MCP Server

[daveangulo]

It's a good idea, the tools already exist with dismiss, prune, and archive. I periodically ask Claude to clean up. I can add a dedicated skill and then some instructions or maybe a schedule to trigger it

[LannyRipple]

Working with it more it might be enough to include the branch in the scope. The problem I see with that is converting that feature branch scope to main once merged.

[daveangulo]

Here is current state and some questions on how it would be best to proceed.

Worth noting we already ship twining_housekeeping (added in
v1.17.0,
dry-run by default; execute: true to apply). It currently: archives old entries, removes
duplicates, surfaces stale provisional decisions, flags dangling warnings, prunes orphaned graph
entities, and rotates old metrics. Worth trying with execute: false first to see what it catches
on your repo — that'll narrow the gap to what this RFE actually needs to add.

A few questions on the gap beyond housekeeping:

1. Trigger — manual command (/twining-gc or similar) you invoke when it feels cluttered, or
   automatic (e.g., housekeeping pass on session start that flags stale entries)?
2. What counts as stale? Housekeeping today flags by age and orphan status. Your example is
   different — decisions that were valid at the time but reference transient concepts ("Wave 3
   compliance") once the project moves on. Options for detecting that: (a) scope path no longer exists
   on disk, (b) references to files that are gone, (c) an explicit "sunset this on date X" flag at
   decision-write time, (d) agent-driven semantic review. What feels right?
3. Interactive or autonomous? Should an agent propose a list and ask before deleting, or should
   cleanup be self-driven once a policy is set?
4. In-core or separate plugin? You hinted at a marketplace plugin — is that your preference
   (keeps core lean), or are you fine extending twining_housekeeping / adding a sibling tool in-core?
5. Purge vs. archive with provenance — for transient project decisions like your example, is the
   goal truly to delete, or to keep them but tag with origin (ticket/branch/sprint) so future-Claude
   can see "this was for a closed sprint, ignore"?

[LannyRipple]

1. I doubt I'd ever even look to decide if it was cluttered so probably best to keep it as housekeeping. I just noticed it was recording things on a branch and those items would be stale on merge.
2. Orphan status is a strong stale smell. I've got this decision but it doesn't reference any file or structure that exists anymore. Maybe have the agent decide on a staleness score and remove things that are 95%+ stale. That threshold might be a setting in twining if anyone wants to get that far into the weeds.
3. I always prefer human in the loop so on a housekeeping pass if stale items are found the user can be asked if they would like to review or are comfortable with Twining's housekeeping. I think once someone looks at a couple they'll quickly decide to leave it up to the agent.
4. I have no preference. My original thought is it might be something I call (the /twining-gc of item (1)) but if housekeeping gets pulled into twining core that works as well. (Probably better.)
5. Archive with provenance. Especially with ticket/sprint the user would have a lot easier time of saying, drop any archived items over a year old/on this branch (we didn't accept that spike), etc

[daveangulo]

Wrap-up summary now that both PRs have landed (#7 was auto-closed by PR #15's "closes" reference earlier today, but here's the consolidated state):

The deterministic portion is shipped across two PRs:

• feat: provenance + staleness detection + archive flow (#7 phases 1-3) #15 (merged) — provenance stamping on every blackboard entry and decision; staleness detection in twining_housekeeping (scope-path / affected-files / branch-gone signals, max-scored, threshold configurable via housekeeping.staleness_threshold); new twining_archive_stale tool that archives caller-confirmed IDs (decisions move to a new archived status; entries are dismissed; provenance preserved). Human-in-the-loop is preserved throughout — nothing auto-archives.
• feat: branch-merge sweep (#7 phase 4 — PR B) #17 (merged) — branch-merge sweep: twining_housekeeping({ merge_sweep: true }) snapshots the local branch set in .twining/.last-known-branches.json and surfaces entries / decisions whose provenance.branch was deleted between runs. Same flow: returns candidates, user confirms, twining_archive_stale acts. Preview passes (execute=false) leave the snapshot untouched so deletions stay visible until consciously committed.

Both PRs are server-only; no plugin bump. Marketplace consumers don't need to update anything.

Tracked separately: the content-reference case ("Wave 3" / "HMS Lancaster") — qualitatively different from orphan-by-structure and needs an LLM in the loop. Filed as #16.

Thanks for the original RFE and the design conversation that nailed down the approach.