Engineering notes

The long argument

Vendoring Code Without a Paper Trail Is Unsecured DebtInlining unverified code severs upstream security alerts and license tracking. Provenance must be captured at intake, not guessed by SBOMs.Provenance, licensing and the paper trail · 6 min read

Everything else

The archive

• From audit JSON to self‑contained repair branch in one stepTurn a static audit JSON into a verified repair branch with SHPBL’s SDK and certification harness in a single script.3 min
• Immutable Log of Build‑Intent Write Proposals for Auditable Post‑Mortem ReviewAn immutable, hash‑chained log of Build‑Intent proposals gives a verifiable audit trail for post‑mortem review.3 min
• Layered Verdicts: Using PROVISIONAL as a Feature Flag GatePrevent runtime surprises by gating production feature flag rollouts on harness execution verdicts rather than binary CI pass/fail states.3 min
• The Gap Between Compilation and CorrectnessA test harness that returns CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED lets teams move beyond green builds toward true code certification.3 min
• The Gate Between Agent Decision and CommitGoverning coding agents at the write path replaces unreliable prompt compliance with invariant checks executed directly in code before disk mutation.3 min
• Eliminate Flaky Tests by Removing Runtime Model CallsRuntime model calls inject non‑determinism into builds, turning flaky tests into a reproducible failure that can be eliminated by static artefacts.3 min
• Post‑Merge Runtime Validation for Automated RepairsRun a focused runtime validation suite after an automated PR merges to catch regressions before they reach production.3 min
• Eliminate External Service Calls to Ensure Repeatable BuildsReplacing live HTTP calls with version‑controlled fixtures eliminates network‑induced flakiness and restores build repeatability.3 min
• Defining Incremental Correctness Levels with Harness VerdictsReplace binary CI status with harness verdicts to make correctness guarantees visible beyond a simple green test.3 min
• Live Load‑Bearing Dependency Graph from Execution TracesRuntime tracing lets you build a load‑bearing dependency graph that reflects only the code actually exercised in production.3 min
• CI Gate on Provisional Harness Verdicts with Optional OverrideUse the certification harness verdict as a CI gate to prevent provisional artefacts from reaching production.3 min
• Enforcing Human Review at the Build‑Intent Gate for Agent WritesEnforcing a mandatory human‑approval flag at the Build‑Intent gate stops unauthorised agent writes before they reach the repository.3 min
• Link SBOM Records to Build‑Intent Proposals for Immutable ProvenanceLink your SBOM entries to exact commit hashes and licence hashes via SHPBL’s Build‑Intent gate for immutable provenance.3 min
• Auto‑Merge Provisional Fixes After Harness PassAuto‑merge provisional fixes after a harness pass to close the audit‑repair loop.3 min
• Property-Based Tests for Provisional VerdictsProperty-based testing strengthens provisional verdicts by replacing narrow examples with invariant checks across generated inputs.3 min
• Cross‑Language Deterministic Build Strategies for MonoreposUse lock‑files, hermetic timestamps, and SHPBL's certification harness to make cross‑language monorepo builds reproducible.3 min
• Measuring Technical Debt Reduction with Automated RepairsUse SHPBL’s repeatable harness to baseline load‑bearing code, apply an automated repair, and quantify the impact on call volume and latency.3 min
• Deterministic Network Mocks to Eliminate Flaky Integration TestsDeterministic network mocks turn flaky integration tests into reproducible CI runs.3 min
• From audit report to merged repair branch in one stepTurn audit JSON into an automated PR using SHPBL’s model‑independent repair library and certification harness.3 min
• From Provisional to Certified: Incremental Harness StrategiesUse the certification harness’s provisional verdicts as a roadmap, adding focused tests until the artifact becomes certified.3 min
• Executable Registry Audits Eliminate Stub EntriesExecutable verification audits replace placeholder stubs with certified grades, turning your registry into a trusted, reusable inventory.3 min
• Sealed Checksums for Deterministic Artifact ReproductionSealed checksums let you verify that a rebuilt artifact matches the original byte‑for‑byte.3 min
• Turn INCONCLUSIVE Harness Results into Targeted Test CoverageUse INCONCLUSIVE harness results as a contract checklist to add targeted test inputs and upgrade verdicts.3 min
• Executable Component Health Dashboard for MonoreposRun every component through SHPBL’s certification harness and visualize the verdicts to turn raw counts into a trustworthy inventory.3 min
• Version-Locked Component Metadata for Reliable ReuseBind every registry row to a git hash and build timestamp to turn a static count into a verifiable, executable inventory.3 min
• From INCONCLUSIVE Harness Verdict to Automated Repair PRAutomated scripts can turn an INCONCLUSIVE harness verdict into a repair PR, closing the audit loop without human tickets.3 min
• Use Provisional Harness Verdicts to Safely Promote ArtifactsUsing provisional harness verdicts lets teams ship faster while ensuring only certified artifacts reach production.3 min
• Detecting Load‑Bearing Code with Execution TracingExecution tracing records real function calls, turning speculative audits into concrete, load‑bearing code insights.3 min
• Seeding Randomness Across Distributed Test WorkersSynchronize a single seed across CI workers to eliminate flaky tests caused by unsynchronized randomness.3 min
• Policy‑Driven Preview Sandboxes Prevent Unauthorized Agent WritesA preview sandbox isolates agent write proposals, ensuring only policy‑approved changes reach the real repository.3 min
• Executable Registry Audits Turn Stubs into Trusted AssetsExecutable verification turns registry stubs into graded assets, letting teams trust their component inventory.3 min
• Prioritizing Refactoring with Provisional VerdictsTreat PROVISIONAL verdicts as actionable tickets to prioritize refactoring where correctness is unverified.4 min
• Detecting Stale Registry Stubs with Execution Smoke TestsRegistry manifests measure metadata, not executability. Use isolated dynamic import harnesses to detect broken builds and dead exports.3 min
• Policy-Driven Review of Agent-Generated Code Before MergeEvaluating agent writes at the intent layer prevents architectural violations and dependency pollution before mutations reach disk or CI.3 min
• Measuring the ROI of Audits vs Full RewritesCalculate the hidden costs of parity delay and regression before greenlighting a rewrite over targeted extraction.4 min
• Linking SBOM Entries to Exact Source CommitsSemver tags and mutable package identifiers leave audit trails broken. Pin SBOM entries directly to upstream commit hashes and tree digests.4 min
• Block Release Promotion on PROVISIONAL VerdictsTreat a PROVISIONAL verdict as a hard CI gate to prevent releases that lack verified correctness.3 min
• Automating Repair Branch Creation from Inconclusive Harness ResultsAutomate the creation of a repair branch directly from an INCONCLUSIVE harness result using SHPBL tools.3 min
• Tracking Upstream Patch Provenance in Vendored Git TreesStore a cryptographic provenance file alongside each vendored source to retain a verifiable upstream commit link.3 min
• Injecting Deterministic Time Providers into Async LibrariesInject a deterministic TimeSource to replace system clocks and make async tests reliably repeatable.3 min
• Turn Audit JSON into Self‑Contained Repair BranchesTurn audit JSON into a self‑contained repair branch that can be auto‑tested and merged via CI.3 min
• Why Harness Setup Errors Must Never Count as Passing TestsTreating test setup failures as green checks creates false assurance. An inconclusive verdict isolates harness limits from true code defects.4 min
• Staging Agent File Mutations in Ephemeral Preview SandboxesDecouple AI code generation from disk writes using ephemeral staging sandboxes and validation gates before mutating local repositories.4 min
• Virtual Clock Schedulers for Flake-Free Async Test FixturesEliminate CI test flakiness by decoupling test fixtures from wall-clock timers and advancing asynchronous state with explicit virtual clock ticks.3 min
• Auditing Vendored Source Trees for Missing AttributionRecover provenance and license terms for orphaned vendored files using Git blob hashes, Software Heritage identifiers, and commit-tree verification.3 min
• Building Hermetic Release Archives from Historical Git TagsGit tags point to commit trees, not network state. Here is how to construct offline, reproducible release archives with fixed tarballs and vendored deps.4 min
• Pinning Socket Timeouts and Clocks in Test EnvironmentsEliminate flaky CI runs by replacing ambient wall clocks and real kernel sockets with explicit clock injection and in-memory duplex streams.3 min
• Refactoring Reusable Logic Out of Legacy CodebasesTurn static audit findings into merged pull requests by carving pure calculations out of side-effect-heavy legacy code.3 min
• Tracking Code Provenance When Agents Paste External LogicWhen coding agents paste external logic directly into a repository, manifest-based SBOMs fail. Here is how to enforce origin tagging at ingest time.3 min
• Intercepting MCP Agent Write Requests with Policy GatesPrevent agent state pollution and licensing violations by replacing raw filesystem tools with a two-phase proposal and commitment MCP gate.4 min
• What Inconclusive Harness Runs Reveal About Test InputsWhen a test runner fails to construct valid input preconditions, reporting a code defect corrupts verification and leads to compromised production code.4 min
• Why Registry Metadata Lies About Component HealthManifest declarations verify syntax and intention, not runtime execution. Active runtime verification is required to catalog real software.3 min
• Consolidating Duplicate Utility Functions Across MonoreposTurn dead-end duplicate code audits into safe monorepo consolidation using invariant testing, union contracts, and automated AST codemods.4 min
• Replacing Runtime Model Calls with Static PrimitivesPlacing runtime model calls in operational data pipelines introduces variance and cost. Replace bounded inference with static, model-independent code.3 min
• Metering Agent Proposals with Dry Run Build IntentDecouple agent planning from repository mutation by enforcing dry-run build intent gates before issuing write authority.3 min
• Handling Inconclusive Test Harness Runs in Merge QueuesDistinguish between artifact defects and harness setup failures in CI merge queues by routing inconclusive verification runs through policy.3 min
• Grading Internal Library Code Before Promoting to a RegistryStatic metadata creates phantom registries; requiring isolated execution verdicts prevents unverified snippets from entering production paths.3 min
• Harvesting Shared Primitives Before Monorepo RewritesTotal rewrites discard years of operational scar tissue. Extract framework-independent domain logic into verified primitives before tearing down legacy services.3 min
• Sealed Checksums for Byte-for-Byte Reproducible BuildsEliminate non-deterministic timestamps, directory order, and UID drift to produce byte-for-byte reproducible release archives.3 min
• Verifying License Compatibility for Transitive DependenciesDirectly vendoring code severs the package graph, hiding transitive copyleft obligations. Here is how to gate imports against license term collisions.4 min
• Restricting Agent Filesystem Access to Preview SandboxesDirect write access lets agents pollute working trees with broken syntax. Gating edits behind a preview sandbox enforces invariant checks before disk writes.3 min
• Capturing License Metadata at the Build-Intent GatePost-hoc SCA scanning loses context and identity. Enforcing license metadata at the Build Intent gate halts non-compliant writes before they hit disk.4 min
• Distinguishing Provisional from Certified Artifacts in CIA green exit code only confirms execution, not correctness. Here is how to structure CI gates between provisional and certified software.3 min
• Lock Clocks to Fixed Timestamps for Stable CI TestsInject a deterministic clock provider to eliminate CI test flakiness caused by clock drift.3 min
• Automate Repair PRs for Provisional Harness VerdictsAutomate fixing provisional harness verdicts by generating repair PRs directly from the verdict payload.3 min
• Audit Agent Write Intent Logs to Detect Unauthorized ProposalsAnalyze structured build intent logs to detect agent policy violations, out-of-bounds writes, and brute-force evasion before code reaches review.3 min
• Identify Unexecutable Registry Entries with a Simple CI CheckPrevent phantom registry entries by verifying that registered components dynamically import and export runnable symbols in CI.3 min
• Convert Audit Findings into a Prioritised Repair BacklogTurn audit reports into structured, call-graph-prioritised repair tickets paced strictly to match sprint velocity and avoid backlog paralysis.3 min
• Prioritising Repairs by Load‑Bearing ImpactPrioritize audit findings by weighting code paths that power critical product features.3 min
• Eliminate Flaky CI Tests with Deterministic Clock & Seeded RandomReplace Node’s native time and random APIs with SHPBL’s deterministic shims to eliminate flaky CI tests caused by hidden nondeterminism.3 min
• Treat Provisional Verdicts as Actionable Signals in CIProvisional verdicts signal reproducible artifacts with incomplete contract coverage, letting teams target testing precisely.3 min
• Embedding Certification Harnesses to Verify SHPBL Catalog EntriesEmbedding SHPBL’s certification harness in CI ensures each catalog entry is verified with a reproducible verdict.3 min
• Resolving Transitive License Obligations in Multi‑Level VendoringGenerate a repeatable SBOM, resolve every transitive licence, and record provenance to eliminate hidden compliance liabilities.3 min
• Layered Verdicts: From Provisional to Certified in CI PipelinesAdd a repeatable verification harness to CI to upgrade provisional verdicts to certified, ensuring contract‑level safety before release.3 min
• Runtime Guardrails: Enforcing License Policies at the Build‑Intent GateEnforce licensing policies at the build‑intent gate so autonomous agents can’t write prohibited code into your repository.3 min
• Tracking License Obligations in Copied Source SnippetsBind each harvested component to an immutable provenance record and certify it with a repeatable harness to keep license compliance through refactoring.3 min
• Grading Test Harness Flakiness with Explicit VerdictsBinary test runners treat retried flakes as passing code. Multi-verdict harnesses isolate harness execution limits from true invariant failures.4 min
• Cataloguing In-Tree Utilities to Prevent Duplicate WorkDuplicate utilities spread when searching an unindexed codebase costs more than rewriting. Here is how to isolate, index, and consolidate pure primitives.4 min
• Why Passing Test Suites Fail to Validate Input ContractsExample tests verify point execution paths, not input domains. A green test suite often masks unexercised boundary conditions and false positives.3 min
• Mapping Load-Bearing Code Across Deep Dependency TreesSeparate quiet, invariant-enforcing logic from loud transport scaffolding to find the computational code that actually carries production risk.3 min
• Integrating Repair Pull Requests into Your Release CadenceTurn audit reports into automatic repair pull requests that merge before the release tag, closing the audit loop each cycle.3 min
• Automated License Inheritance Mapping for Vendored CodeVendored code inherits complex license obligations across subdirectories. Learn how to map file-level license inheritance in CI pipelines.3 min
• Policy-Driven Build Intent Gates for Multi-Agent EnvironmentsPrevent multi-agent file collisions and unauthorized repo mutations by enforcing deterministic policy gates at the MCP tool boundary.3 min
• Executable Verification Turns Registry Stubs into Real AssetsPackage manifests assert intent rather than execution. An automated certification harness weeds out registry stubs and isolates real software assets.3 min
• Eliminating Timestamp Drift in Binary Release ChecksumsUse GNU tar’s deterministic flags to eliminate timestamp drift and achieve reproducible release archives across machines.3 min
• Enforce schema contracts for agent‑generated code at merge timeA deterministic, model‑independent validator can block non‑conforming agent code at merge time, keeping the main branch clean.3 min
• Link SBOM entries to exact source commitsStore Git blob hashes in your SBOM to link every file entry to its exact source bytes, enabling instant provenance verification.3 min
• Automating CI Verification of SHPBL Registry EntriesA minimal CI harness can certify each registry entry by loading and executing its main function, turning stubs into verified artifacts.3 min
• Handling Inconclusive Harness Runs in CI PipelinesTreat INCONCLUSIVE harness verdicts as warnings in CI to separate test‑infrastructure limits from real code defects.3 min
• Separating Agent Proposals from Repository Mutation GatesPrevent agents from polluting git history by routing proposed diffs through an ephemeral validation gate before granting write access.4 min
• Seeding Entropy for Stable Test Runs in CICapture PRNG seeds and clock offsets in CI to keep dynamic test inputs reproducible without resorting to static, bug-masking fixtures.3 min
• Embedding Build Intent Checks into Pull‑Request TemplatesEmbedding a verified Build Intent token in PR templates creates a deterministic gate that stops unapproved agent writes before merge.3 min
• Detecting Orphaned Functions in a MonorepoBarrel files and isolated unit tests hide dead code in monorepos. Find orphaned functions by tracing reachability from declared production roots.4 min
• From Audit Report to Pull Request: Automating the Repair LoopTransform static analysis audits into verified pull requests by pairing machine-readable diagnostics with a strict certification harness.3 min
• Why an SBOM Without Origin Hashes Is MeaninglessAn SBOM based solely on package names and declared licenses records your intent, not the actual bytes running in production.4 min
• Proving Input Contracts on Pure Library PrimitivesPassing unit tests only prove code matches author assumptions. Hardening pure primitives requires boundary contracts and property-driven harnesses.4 min
• Isolating Network Ordering in Asynchronous Test SuitesEliminate asynchronous test flakiness by swapping kernel loopback sockets for caller-stepped virtual transports and deterministic queues.3 min
• Making In-Tree Prior Art Searchable to Stop Rebuilding ItLexical code search fails because it indexes naming choices instead of contracts. Here is how to index in-tree prior art by executable behavior.4 min
• Automating Dead Branch Pruning After Legacy System AuditsStatic analyzers miss dynamic dispatch. Safely prune legacy dead code by coupling runtime execution logging with syntax-aware AST excision.4 min
• Tracing Load-Bearing Code When Dependencies Mask LogicSBOM inventories show what sits in your build, but fail to reveal when critical tenant boundaries sit inside unmaintained transitive dependencies.3 min
• Testing Input Contract Boundaries When Green Suites LiePassing tests prove only that an implementation survived its own assumptions. True contract verification requires testing discrete domain boundaries.3 min
• Enforcing Pre-Commit Schema Contracts on Agent Code WritesPrevent agent regressions by moving AST and schema validation from post-hoc PR reviews directly to authoritative in-memory write gates.4 min
• Extracting Pure Primitives from Tangled MonolithsShrink refactoring blast radius by carving pure, deterministic business logic out of I/O-heavy monolithic controllers before attempting major rewrites.3 min
• Why Runtime Model Calls Break Deterministic Test GuaranteesRuntime model calls introduce hardware-level non-determinism that breaks CI assertions. The hallucination surface belongs at compile time.3 min
• Resolving License Invariants at the Agent Write BoundaryAI agents bypass package managers to emit raw source directly. Protect your codebase by resolving license invariants at an intent gate before disk writes.4 min
• Evaluating Agent Code Proposals Before Commits HappenInspecting AI agent output at the pull request fails. Intercept code proposals at a deterministic build intent gate before commits alter the repository.4 min
• Preventing Blind Agent Writes with Build Intent Terminal StatesPrevent agent drift and polluted git history by intercepting file modifications at a Build Intent gate before touching the disk.3 min
• Seeding Clocks and Entropy in Production Test SuitesEliminate flaky test runs by treating physical clocks and random number generators as explicit, seedable inputs rather than ambient global state.3 min
• Locking Byte-for-Byte Reproducibility in Release ArchivesCompilers and archivers inject timestamps and host paths into binaries by default. Standardising build epochs and sorting yields byte-for-byte verifiable releases.3 min
• Harvesting Load-Bearing Logic Before Authorising a RewriteTotal rewrites fail because legacy code silently encodes edge cases. Extract and verify deterministic domain logic before authorising new plumbing.3 min
• Detecting Stubs Disguised as Internal LibrariesInternal catalogs frequently count scaffolded stubs as real software. Here is how static analysis fails to catch them and how to verify execution.3 min
• Finding the Eleven Retry Loops in Your MonorepoLexical search fails to surface duplicate control-flow primitives. Structural dataflow analysis indexes reusable logic by functional contract.3 min
• Why Code Audits Get Ignored Without Automated RepairsAudits fail when detection is detached from remediation. Resolving technical debt requires pairing AST findings with verifiable, deterministic patches.3 min
• The Operational Cost of Provisional Test VerdictsPassing CI suites prove execution, not verification. Treating provisional test runs as verified proofs creates brittle downstream production failures.4 min
• Tracing Agent Generated Functions Back to Source LicensesAI assistants vendor copyleft algorithms directly into files, bypassing manifest-based SBOMs and introducing silent compliance debt.3 min
• When the Harness Fails Instead of the CodeA test suite exiting zero proves nothing if preconditions failed silently. Separating harness limits from code defects restores CI signal.3 min
• Auditing Vendored Dependencies Beyond the LICENSE FileA top-level LICENSE file is an assertion, not proof. Learn how to audit vendored dependencies using cryptographic provenance and file-level diffing.4 min
• The Four Verdicts Between Green Tests and Correct CodeBinary CI exit codes conflate unexercised mocks with verified logic. A four-verdict taxonomy separates mechanical execution from genuine invariant proofs.Pillar
• Closing the Loop from Repository Audit to Merged RepairStatic audits fail because they catalog symptoms instead of isolating boundaries. Here is how to convert legacy audit findings into verifiable, merged patches.Pillar
• A Component Count Is Not an InventoryWhy internal component registries decay into unverified technical debt and how to calculate the true yield of reusable code.Pillar
• Why Model Independence Is an Engineering PostureReplacing parsers with runtime LLM calls trades deterministic invariants for statistical tendencies. Logic must be owned at runtime.Pillar
• Governing Code Agents at the Build Intent GateWhy prompt guardrails fail on coding agents, and how to govern mutations by placing a deterministic build gate between intent and disk writes.Pillar

What we write about

Six standing arguments

• Software inventory you can trust

  A count of components is a claim, not an inventory. What makes an inventory real is that each row can be read, executed and graded.

• Certifying that code does something

  Between 'it compiles' and 'it is correct' there is a whole ladder of verdicts, and naming your rung honestly is more useful than claiming the top one.

• Model independence and repeatable builds

  Software that calls a model at runtime inherits the model's variance. Owning your logic outright is a different engineering posture, not a smaller one.

• Provenance, licensing and the paper trail

  Every line you did not write is a liability until you can say where it came from and under what terms.

• Governing agents that write code

  The interesting control point is not the model. It is the gate between an agent deciding to write and the write happening.

• Audit, then actually repair

  An audit that ends in a report is a cost. An audit that ends in a merged repair and a kept capability is an asset.