RFC: Pre-declare SpecKit refresh + post-close Batch 7.4 — two patterns surfaced in Sentinel CHARTER-18

[montfort]

RFC: Pre-declare SpecKit refresh + post-close audit-driven Batch 7.4 — two patterns surfaced in Sentinel CHARTER-18

Author: Claude Opus 4.7 (claude-code-v1.0) on behalf of StrangeDaysTech/sentinel adopter (operator José Villaseñor Montfort)
Source: StrangeDaysTech/sentinel CHARTER-18 (CommsHub US5 — Cloud Tasks failover + tracking + anomaly) end-of-chain retrospective
Date: 2026-05-15
Local RFC file: .straymark/06-evolution/charter-18-pattern-evolution-rfc.md (Sentinel PR filed in parallel)
Telemetry artifact: .straymark/charters/CHARTER-18.telemetry.yaml
Audit cycle: 7th cross-family pair (gemini-2.5-pro + gpt-5.3-codex)
Precedent: this RFC follows issue #111 — empirical observation in Sentinel → local pattern → upstream proposal with adoption path.

Resumen ejecutivo

CHARTER-18 was the seventh and final user-story Charter of the CommsHub module — a 7-Charter chain (CHARTER-08 → 13 → 14 → 15 → 16 → 17 → 18) where accumulated empirical learnings from prior charters had drifted the SpecKit artifacts (plan / data-model / contracts / quickstart / research) far enough that going straight from CHARTER-17 close into CHARTER-18 declare would have caused systematic mid-flight scope expansions. The adopter's response was to (1) interpose a pre-declare SpecKit refresh PR that integrated 14 categorized learnings + 15 empirical corrections + 3 operator decisions BEFORE Charter declare, and to (2) later apply a post-close audit-driven Batch 7.4 amendment when external audit cycle 7 surfaced findings that required code changes after status: closed.

Both patterns produced verifiable telemetry signals worth surfacing to StrayMark as candidate framework conventions. This issue tracks them for upstream consideration.

Pattern 1 — Pre-declare SpecKit refresh

Hallazgo

StrayMark's Charter pattern assumes the SpecKit artifacts (the contract surface a Charter declares scope against) are stable enough at declare-time to plan against. Over a 7-Charter chain in a single module, that assumption breaks empirically. By CHARTER-17 close, 14 categorized learnings had accumulated from CHARTER-08..17:

• 7 reusable patterns (withRLS wrapper, cursor pagination tuple, brand-cache LRU, core.processed_events dedup, FR-005 PL/pgSQL trigger pattern, EnvSecretLoader, shared BrandCache).
• 4 code gaps (commshub_anomaly_pauses unwired since CHARTER-07; Mailgun ParseWebhook = ErrUnsupported stub; Recipient.tenant_id column gap; webhook_dispatcher sync-with-retry placeholder).
• 3 discipline patterns (cross-family audit pair; Batch 7.4 remediation; per-batch close discipline via straymark charter batch-complete).

Plus 15 empirical corrections (EC1..EC15) — places where the original spec drifted from the implementation (migration numbering, table naming conventions, framework version assumptions).

Without integration, the next Charter (CHARTER-18) would have re-discovered each pattern mid-flight, producing R<N> (new, not in Charter) entries documenting "we should have known this". The cost is not abstract — prior charters in the chain produced 5-10 emergent R<N> entries each, with the trend visibly rising.

Implementación (Sentinel-side)

Sentinel codified a dedicated refresh PR between CHARTER-17 close and CHARTER-18 declare:

• PR: StrangeDaysTech/sentinel#76 (commit d1d7292, 2026-05-14): "spec(002-commshub): US5 plan refresh — LOCKED-aware Phase 7+8 redesign"
• AIDEC: AIDEC-2026-05-14-001-speckit-plan-scope-limited-us5-refresh
• Files touched: non-locked sections of specs/002-commshub/{plan,data-model,quickstart,research,spec}.md + contracts/*.md.

The refresh integrated the 14 prior-chain learnings into a categorized table in research.md, plus 15 empirical corrections, plus 3 operator decisions (D1 / D2 / D3) ratified pre-declare. CHARTER-18's ## Context section then explicitly cites each pattern + correction + decision by ID, so the Charter scope is grounded in the refreshed reality.

Telemetría — qué señales produjo

From CHARTER-18.telemetry.yaml:

Field	Value	Reading
pre_work.items_declared	5	Forward-pointers from CHARTER-17 to be consumed
pre_work.items_completed_before_planning	5	All closed pre-declare (refresh did the work)
pre_work.items_discovered_during_planning	0	Nothing surfaced mid-Charter
pre_work.pre_work_quality	"high"	Explicit operator rating
effort.estimation_drift_factor	1.0	On-budget across 10 batches
outcome.completed_as_planned	true	First Charter in the chain to close cleanly without a mid-flight remediation Charter
qualitative.overall_satisfaction	5 / 5	Adopter's qualitative score
qualitative.wins[1]	"EC1..EC15 empirical-corrections inventory absorbed pre-execution risk into in-execution awareness. Five risks (EC4 idempotency, EC8 Mailgun ParseWebhook closure, EC15 channel_id PRIMARY KEY) would have been emergent R-entries in prior Charters; their pre-declaration in research.md eliminated mid-flight surprise."	Direct evidence the pattern delivered

Operator's effort.estimation_drift_reason statement: "On budget. ... the SpecKit refresh from PR #76 ... eliminated most ambiguity that drove drift in prior Charters. No mid-flight remediation Charter required — the EC1..EC15 empirical-corrections inventory in research.md absorbed what would have been pre-execution risk into in-execution awareness."

Patrón propuesto para StrayMark

Name: Pre-declare SpecKit refresh (or: Empirical Corrections Inventory).

When it applies: a module with N ≥ 3 user-story charters where the average r_n_plus_one_emergent_count per charter has been rising AND the SpecKit artifacts were authored against the framework version at module start (not refreshed since).

Mechanics:

1. Refresh PR before next Charter declare. Touches non-locked sections of plan.md, data-model.md, contracts/*, quickstart.md, research.md. Optional AIDEC documenting the refresh decision + alternatives considered.
2. Categorized learnings table in research.md with at least these buckets: reusable patterns, code gaps, discipline patterns, empirical corrections.
3. Operator decisions (Dn) listed explicitly with alternatives + chosen path + rationale — these are the contracts the next Charter inherits.
4. Next Charter's ## Context cites each pattern + correction + decision by ID so scope grounding is explicit.

Trigger heuristic (could be a straymark charter refresh-suggest <module> CLI command):

• IF module has ≥ 3 closed charters AND
• IF the rolling mean agent_quality.r_n_plus_one_emergent_count of the last 3 charters is > some threshold (Sentinel's data suggests > 6) AND
• IF no refresh PR has landed in this module since the last charter chain branch point
• THEN suggest a refresh before declaring the next charter

Telemetry slot suggestion: add to charter_telemetry:

pre_declare_refresh:
  enabled: true | false
  refresh_pr: <url or null>
  refresh_aidec: <id or null>
  reusable_patterns_integrated: <count>
  code_gaps_integrated: <count>
  discipline_patterns_integrated: <count>
  empirical_corrections_integrated: <count>
  operator_decisions_ratified: <count>

so the framework can correlate pre_declare_refresh.enabled=true charters against effort.estimation_drift_factor + outcome.completed_as_planned across the StrayMark adopter dataset.

Pattern 2 — Post-close audit-driven Batch 7.4 amendment

Hallazgo

StrayMark v1 audit cycle docs the in-Charter "Batch 7.4 remediation pattern": when external audit findings emerge before close, apply them atomically pre-close in the same commit/PR. But what about findings that surface after status: closed? Audit cycles in Sentinel run post-close (the audit prompt is generated at close ceremony, auditors execute asynchronously, the operator runs /straymark-audit-review whenever both auditors have written their reports). For a Charter that closes 2026-05-15 with audit reports landing 2026-05-15..05-17, findings can arrive after the close ceremony.

The framework's options today:

• (a) Open a new Charter for remediation. Heavy: full declare + Tasks + ceremony for what might be ~5 file edits.
• (b) Surface findings in the audit review.md and leave them open. Loses the "atomic with the Charter" property.
• (c) Bend the in-Charter Batch 7.4 pattern to a post-close amendment commit, which is technically what the in-Charter doc encourages ("Track each finding remediation as F in AILOG; track each new emergent risk as R<N+1> (new, not in Charter)").

Sentinel chose (c) for CHARTER-18 because the 5 findings (4 from gpt-5.3-codex, 1 from gemini-2.5-pro) were code-level fixes (not architectural reopens), the fix surface was cohesive (19 files, +2257/-106 lines) but bounded — a single PR landed atomically — and a new Charter would have created multi-week governance overhead for ~6h of focused engineering.

Implementación (Sentinel-side)

• Branch: charter-18-execute (the original execute branch, still mergeable to main).
• Commit: f8e135d — "charter-18(batch-7.4): audit-driven remediation — DI wiring + worker retry + decommission filter + attempt-counter fix".
• AILOG: AILOG-2026-05-15-050 (NEW, risk_level: high, review_required: true). The original AILOG-2026-05-14-049 was amended in §R16 with a "Historical correction" subsection pointing forward to 050.
• PR: StrangeDaysTech/sentinel#78 (the original CHARTER-18 execute PR, augmented with the Batch 7.4 commit before merge).
• Telemetry: the external_audit: YAML array in CHARTER-18.telemetry.yaml was populated via manual merge (the CLI --merge-into rejected — see sub-issue below).

Findings closed

Finding	Severity	Auditor	Closure
F1	Critical	gpt-5.3-codex (C1)	DI wiring completo: extends wire.Struct(SenderDeps) with Providers + RetryEnqueuer; extends wire.Struct(ServiceDeps) with CloudTasks; chains WithCloudTasksEnqueuer / WithWebhookProviders / WithWorkerOIDC / WithSendRetrier in ProvideCommsHandler + ProvideWebhookDispatcher
F2	High	gpt-5.3-codex (H1)	Sender.RetryFromTask implements the failover-with-skip-previous-providers logic; runSendRetry replaces ACKNOWLEDGED_NOT_IMPLEMENTED_YET
F3	High	gpt-5.3-codex (H2)	runWebhookDispatch reads X-Cloudtasks-Taskretrycount header instead of hardcoded task.AttemptNumber=1
F4	High	gpt-5.3-codex (H3)	CancelServiceTasks filters by service_id via JSON-probe before DeleteTask, closing multi-tenant data-loss vector
F5	Medium (was Critical)	gemini-2.5-pro (C1)	Makefile adds explicit -timeout=$(INTEG_TIMEOUT) default 600s; recalibrated severity in the calibrator review
FX	Medium	calibrator (missed by all)	AILOG-049 §R16 historical correction — wire promise was made in Batch 7 but never honored; closed in Batch 7.4

Plus a follow-up CI hardening PR (#79) adding an Integration Tests (testcontainers) job to ci.yml so FU-074's trigger is now mechanical (gate failure) rather than operator-reactive.

Sub-issue surfaced — CLI --merge-into rejects empty placeholder

When straymark charter close <id> runs at close ceremony, it writes a telemetry YAML with external_audit: [] (empty array placeholder). When the audit cycle completes later and /straymark-audit-review runs straymark charter audit <id> --merge-reports --merge-into <telemetry-yaml>, the CLI rejects with:

error: <telemetry-yaml> already has an `external_audit:` block.
Re-audit (appending to an existing array) is not supported in v0.
Re-run `straymark charter audit <id> --finalize` (without --merge-into)
to print the new YAML, then merge manually if you want to append.

The semantics make sense for the case "audit was already merged once, refusing to merge twice", but external_audit: [] (empty array) and external_audit: [<entries>] (non-empty) are not distinguished — the CLI rejects both. The fallback path (Branch B in the /straymark-audit-review skill) works, but it shifts the merge to manual operator edit, which then risks YAML indentation errors (the Sentinel operator hit one — external_audit: ended up at column 0 instead of column 2 inside charter_telemetry:, requiring a follow-up fix-up edit).

Recommendation: relax the v0 check to "already has a populated external_audit: array" so the placeholder case (empty array at close) doesn't block the post-close merge.

Patrón propuesto para StrayMark

Name: Post-close audit-driven amendment (or: Batch N.4 extended to post-close).

When it applies: external audit findings arrive after the Charter's status: closed but before sufficient time has passed that a new Charter is the more natural unit.

Mechanics:

1. Same execute branch (do not branch off main). The Charter's original branch is mergeable to main; the amendment commit rides along.
2. New AILOG (not amend the original — risk_level may have changed, audit decisions are distinct from execute decisions).
3. Historical correction subsections in the original AILOG for any §R entries that the amendment proves were stale.
4. PR comment on the original PR (do not open a new PR if the execute branch hasn't merged yet) describing the amendment + closed findings.
5. Telemetry update: the external_audit: array gets populated (manual merge if CLI rejects per the sub-issue above).

Trigger heuristic:

• IF Charter status: closed AND
• IF audit findings emerge in review.md that are graded Critical or High AND
• IF the closure_criterion of the Charter is materially unmet by the un-remediated findings AND
• IF the fix surface fits in one cohesive PR (~ < 25 files, no architectural reopen)
• THEN apply Batch 7.4 amendment instead of opening a new Charter

Telemetry slot suggestion: add to charter_telemetry:

post_close_amendment:
  applied: true | false
  trigger: "external_audit" | "production_incident" | "deferred_implementation"
  ailog_id: AILOG-YYYY-MM-DD-NNN (the amendment AILOG)
  findings_closed: <count>
  files_modified: <count>
  effort_hours: <float>

so the framework can correlate amendment frequency against original Charter quality + audit-cycle yield.

Cross-pattern observation — they compose

A charter that received the pre-declare refresh (Pattern 1) is more likely to avoid the post-close amendment (Pattern 2), because the refresh absorbs the pre-execution risk that the audit would have surfaced post-close.

But CHARTER-18 needed both — the refresh handled the spec-level drift (architectural assumptions, table naming, framework version), and the amendment handled the runtime-level drift (DI wiring that the spec didn't reach into). The two patterns are complementary, not substitutable. StrayMark's framework should encourage Pattern 1 at the chain level (module-wide retrospective) and tolerate Pattern 2 at the cycle level (post-audit per-charter remediation).

Adopter contribution

Sentinel's adopter (StrangeDaysTech/sentinel, operator José Villaseñor Montfort) is contributing this RFC as feedback to StrayMark v1 governance + telemetry schema iteration. The patterns are already live in Sentinel's .straymark/ tree; this issue codifies them for upstream consumption.

References:

• Sentinel local RFC file: .straymark/06-evolution/charter-18-pattern-evolution-rfc.md (committed via Sentinel PR alongside this issue)
• CHARTER-18 telemetry: .straymark/charters/CHARTER-18.telemetry.yaml
• AILOGs: AILOG-2026-05-14-049 (execute) + AILOG-2026-05-15-050 (Batch 7.4 amendment)
• Audit artifacts: .straymark/audits/CHARTER-18/ — audit-prompt.md, report-gemini-2-5-pro.md, report-gpt-5-3-codex.md, review.md, external-audit-pending.yaml
• SpecKit refresh evidence: specs/002-commshub/research.md §EC1..EC15 + §Reusable Patterns
• Sentinel PRs: #76 (refresh) + #78 (execute + Batch 7.4) + #79 (CI gate for FU-074)

[montfort]

Round-trip closure — adoption confirmed in StrangeDaysTech/sentinel

Filing this comment from the adopter side to close the loop on Issue #156. The framework bump to v4.16.0 lands two PRs on the Sentinel side:

Sentinel PR #82 — framework bump fw-4.15.0 → fw-4.16.0

Pulls v4.16.0 into the adopter repo. Verified the upstream artifacts ship as expected:

• Governance: .straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md (EN + i18n ES + i18n zh-CN) — full pattern reference, both Pattern 1 and Pattern 2 documented with mechanics + trigger heuristic + telemetry slots.
• Framework directive: STRAYMARK.md §15.A + §15.B as canonical sub-sections of the Charter pattern.
• Schema: .straymark/schemas/charter-telemetry.schema.v0.json v0.2 addendum with pre_declare_refresh: + post_close_amendment: opt-in sub-objects.
• CLI: cli-3.14.0 adds straymark charter refresh-suggest <module> (read-only heuristic per the trigger description in the RFC) + straymark charter amend CHARTER-NN (scaffolding helper for Batch N.4 amendments).
• Sub-issue resolved: STRAYMARK.md §15.B explicitly notes that the v0.2+ schema tolerates external_audit: [] placeholders in the audit --merge-reports --merge-into round-trip — the manual-YAML-merge friction we hit during CHARTER-18 close ceremony is closed.

Same-day round-trip from RFC filing to upstream release (filed and released both on 2026-05-15) is exceptional — thank you for the responsiveness.

Sentinel PR #83 — retroactive telemetry population

CHARTER-18 did apply both patterns in practice (PR #76 was the SpecKit refresh; PR #78 commit f8e135d was the Batch 7.4 amendment). With v0.2 schema landed, .straymark/charters/CHARTER-18.telemetry.yaml now gets retroactively populated with both blocks so CHARTER-18 becomes the first machine-readable example of the patterns in production data.

Populated values:

pre_declare_refresh:
  enabled: true
  refresh_pr: "StrangeDaysTech/sentinel#76"
  refresh_aidec: "AIDEC-2026-05-14-001-speckit-plan-scope-limited-us5-refresh"
  reusable_patterns_integrated: 7    # research.md §Reusable patterns #1-#7
  code_gaps_integrated: 4             # #8-#11
  discipline_patterns_integrated: 3   # #12-#14
  empirical_corrections_integrated: 15  # EC1..EC15
  operator_decisions_ratified: 3      # D1, D2, D3

post_close_amendment:
  applied: true
  trigger: "external_audit"
  ailog_id: "AILOG-2026-05-15-050"
  findings_closed: 5    # F1-F4 (gpt-5.3-codex) + F5 (gemini-2.5-pro);
                        # FX (calibrator-missed-by-all) excluded from
                        # external_audit count
  files_modified: 19    # commit f8e135d
  effort_hours: 6

Inline YAML comments in the file cite Issue #156 + originating PRs/AILOGs + count rationale per field, so a future adopter (or a re-audit) can trace any number back to its empirical source.

Principle #12 progression

The patterns remain at N=1 domain until a second adopter validates them — but the machine-readable shape is no longer hypothetical, and the next adopter who reads CHARTER-CHAIN-EVOLUTION.md can now click through to CHARTER-18.telemetry.yaml for a worked example. That should accelerate N=1 → N=2 if/when another StrayMark project hits a similar 7-Charter-chain wall.

Observed during adoption — minor docs polish opportunity

Two small things noticed while pulling v4.16.0 into Sentinel; flagging in case they're worth a v4.16.1 docs pass (none are blocking):

1. AGENTS.md injection mechanic: v4.15.0 added AGENTS.md to dist-manifest.yml::injections: but straymark repair doesn't auto-create the target file when missing. The adopter has to create it manually first (with the <!-- straymark:begin --> / <!-- straymark:end --> markers) before straymark update will respect it on subsequent runs. Probably intentional (opt-in semantics matching the other injection targets) but a one-liner in STRAYMARK.md §Directive Injection Markers explaining "Targets are opt-in — create the file with markers and straymark update will manage the marker section" would save the next adopter five minutes of investigation.

2. straymark charter refresh-suggest heuristic threshold visibility: the --help output mentions "default 6" for the r_n_plus_one_emergent_count threshold. Useful to know if that's tunable per-project (e.g., via .straymark/config.yml) or whether the operator should run with --threshold flag if they have a domain with different scale assumptions. Either way is fine; just a note for future maintainers.

Thanks again for the rapid upstream adoption.

— Sentinel adopter (José Villaseñor Montfort), Claude Opus 4.7 (claude-code-v1.0)

[montfort]

fw-4.16.1 published

Both observations from the closure comment above are addressed in PR #158, released as fw-4.16.1 (framework-only patch; cli-3.14.0 remains current).

Changes

1. STRAYMARK.md §Directive Injection Markers — clarified missing-target behavior per command. straymark init and straymark update-framework walk dist-manifest.yml::injections: end-to-end and create the target file if it does not exist (see cli/src/inject.rs:60-64). straymark repair is narrower: it re-injects only when STRAYMARK.md itself is missing (gate at cli/src/commands/repair.rs:232). Practical guidance for the AGENTS.md case (single target deleted while STRAYMARK.md intact): re-run straymark update-framework, not straymark repair.

2. CLI-REFERENCE.md (EN + ES + zh-CN) — clarified that --threshold N is the only override path for straymark charter refresh-suggest in v0.2; no config.yml field for the heuristic threshold yet (tuning lives at operator-invocation level until a second adopter validates a project-wide default).

Also fixed

The EN CLI-REFERENCE.md versioning row had been left at fw-4.15.0 through the fw-4.16.0 cycle — corrected to fw-4.16.1 in this patch.

Out of scope (noted for future work)

The underlying behavior of straymark repair (gating per-target restore on STRAYMARK.md presence) is documented as-is here. A broader CLI fix — per-target presence check in repair.rs:232 so a single missing injection target is restored without requiring STRAYMARK.md to also be absent — is a candidate for a future cli-3.14.1 or cli-3.15.0 if the gate proves to be a recurring friction point.

Issue can be considered closed.

[montfort]

Second round-trip — repair-missing-targets fix landed in Sentinel

Posting an empirical follow-up: framework fw-4.16.2 + CLI cli-3.14.1 (the bump that ships the straymark repair fix for missing injection targets) is now integrated in StrangeDaysTech/sentinel via PR #85.

Sub-issue #1 closure — repair behavior verified

The fix described in STRAYMARK.md §Directive Injection Markers — "Missing-target behavior (refined in fw-4.16.2 / cli-3.14.1)" — works as documented when exercised against a real adopter state. Concrete evidence from the Sentinel update session:

Stage	Local state of .cursor/rules/straymark.md	straymark repair behavior
Before bump (cli-3.14.0)	Declared in dist-manifest.yml::injections: since fw-4.15.0 but absent on disk	Reported "structure is healthy, nothing to repair"; target stayed missing
After bump (cli-3.14.1)	Restored	Emitted "Restored .cursor/rules/straymark.md" and created the file with canonical <!-- straymark:begin --> ... <!-- straymark:end --> marker block

The restored file was committed alongside the bump as a NEW addition. No manual marker authoring was required.

Historical note observation

The STRAYMARK.md bullet explicitly citing the version pair where the gate existed (cli-3.14.0 / fw-4.16.1) and the version where it was removed (cli-3.14.1) is useful trazabilidad — an adopter who runs into intermediate versions can map the symptom to the specific release boundary without git archaeology. Worth keeping as a documentation convention for future behavior-corrective fixes.

Sub-issue #2 still open

The second observation from the original adopter comment — straymark charter refresh-suggest <module> threshold tunability (whether the default 6 for r_n_plus_one_emergent_count is overridable via .straymark/config.yml, a --threshold flag, or hard-coded) — has not been addressed in fw-4.16.2. Not blocking; flagging that the surface is the same as when first raised so it does not get lost.

State of Issue #156 from the adopter side

• Pattern documentation: ✓ adopted as CHARTER-CHAIN-EVOLUTION.md (fw-4.16.0)
• Schema fields: ✓ adopted as pre_declare_refresh: + post_close_amendment: v0.2 addendum (fw-4.16.0)
• CLI subcommands: ✓ shipped as straymark charter refresh-suggest + amend (cli-3.14.0)
• --merge-into empty-placeholder rejection sub-issue: ✓ documented as resolved in v0.2+ schema (fw-4.16.0)
• Repair missing-targets sub-issue (feat: rebrand to Strange Days Tech + CLI scaffolder + repo restructure #1): ✓ behavior fix in cli-3.14.1 (fw-4.16.2)
• Refresh-suggest threshold tunability sub-issue (refactor: consolidate distribution files under dist/ and update docs #2): ◯ open

From the adopter side the issue can be considered substantively closed pending sub-issue #2. Maintainers may close it whenever convenient.