Scopefolio is our product. This tutorial uses an illustrative implementation, not a description of Scopefolio’s internal code.

Imagine a client writing a change request, pressing Submit, and seeing only a red border. The page has detected a problem, but the client still needs three answers: what failed, where it failed, and how to continue without losing their work.

A useful error-handling flow connects those answers. This small example checks one required request field. It demonstrates feedback and focus-management code locally. It does not save data, call a server, or describe observed Scopefolio behavior.

Start with a named control

Give the input a visible label whose for matches its id. Keep instructions visible after typing begins, rather than hiding them in a placeholder. W3C's labeling guidance explains how that association helps people identify and activate the control.

The example treats whitespace-only text as empty. It waits for submission before displaying an error, so someone composing a request does not receive premature warnings.

Connect the summary to the field

Save the following as form-demo.html and open it in a browser. It has no dependencies or network requests. The button starts disabled so this demonstration cannot submit without its JavaScript handler.

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Change request demo</title>
<style>
  body { max-width: 42rem; margin: 2rem auto; padding: 1rem; }
  input, button { font: inherit; padding: .5rem; }
  input { display: block; max-width: 100%; box-sizing: border-box; }
  :focus-visible, #errors:focus { outline: 3px solid; outline-offset: 4px; }
</style>
<main>
  <h1>Describe a project change</h1>
  <section id="errors" tabindex="-1" aria-labelledby="error-title" hidden>
    <h2 id="error-title">There is a problem</h2>
    <ul><li><a id="error-link" href="#request"></a></li></ul>
  </section>
  <form id="request-form">
    <label for="request">Requested change (required)</label>
    <p id="request-hint">Describe the change you want reviewed.</p>
    <input id="request" name="request" required
           aria-describedby="request-hint">
    <p id="request-error" hidden></p>
    <button disabled>Check request</button>
  </form>
  <p id="result" role="status"></p>
  <noscript>This demonstration needs JavaScript. Nothing has been sent.</noscript>
</main>
<script>
  const byId = id => document.getElementById(id);
  const form = byId('request-form');
  const field = byId('request');
  const summary = byId('errors');
  const error = byId('request-error');
  const link = byId('error-link');
  const result = byId('result');

  link.addEventListener('click', event => {
    event.preventDefault();
    field.focus();
  });

  form.addEventListener('submit', event => {
    event.preventDefault();
    result.textContent = '';
    const message = field.value.trim()
      ? '' : 'Requested change: describe the change you want reviewed.';
    error.textContent = message;
    error.hidden = !message;
    summary.hidden = !message;
    link.textContent = message;
    if (message) {
      field.setAttribute('aria-invalid', 'true');
      field.setAttribute('aria-describedby', 'request-hint request-error');
      summary.focus();
    } else {
      field.removeAttribute('aria-invalid');
      field.setAttribute('aria-describedby', 'request-hint');
      result.textContent = 'Checks passed. Demo only: nothing was sent.';
    }
  });
  form.noValidate = true;
  form.querySelector('button').disabled = false;
</script>
</html>

On failure, the script requests focus on the summary. Its link calls focus() on the affected input. The inline message uses the same wording, and aria-describedby retains the instruction while adding the error. Values are never cleared. The input receives aria-invalid only after a failed check. Errors remain visible while the person edits; validation runs again on the next submission. Once a corrected value passes, the script removes that state and the error reference together, leaving the original hint in place. Hiding an old paragraph while keeping stale validation state can otherwise leave the visual form and its accessibility information describing different situations.

A summary becomes especially useful when a longer form has several errors. Add one link per invalid field in page order. W3C's notification guidance covers linked summaries and inline feedback; the GOV.UK error-summary component also documents moving keyboard focus to the summary.

This example attempts to notify users by moving focus, without adding an assertive live region to the same summary. W3C’s notification tutorial also describes an alert-region approach for dynamically inserted error lists. This simplified example is not a reproduction of the GOV.UK component. Test whether its focused section and linked error are announced clearly in your supported browser and screen-reader combinations before adopting it. On a successful check, the existing role="status" region changes without moving focus. That role has implicit polite announcement behavior, as documented by MDN.

Choose who owns validation feedback

Native HTML validation is a reasonable starting point: required, suitable input types, and browser feedback need little code. A custom summary gives the application control over wording and the complete error list, but also makes the application responsible for presenting and updating it.

Here, noValidate suppresses native interactive validation after the handler is installed. Otherwise, the browser could stop an invalid submission before the custom submit handler runs. It does not remove the need for server validation. MDN explains these distinctions in its constraint-validation guide.

For a real endpoint, validate again on the server and enforce authorization for every request. OWASP’s authorization guidance explains why client-side checks cannot make that decision. Preserve entered values on failure, render field errors through the same pattern, and announce success only after a confirmed save. A network failure needs its own message and a safe retry path; do not label it a malformed request field.

Verify the recovery path

Nine local JavaScript tests passed using a simulated DOM: empty and whitespace submissions, focus requests, the summary-link handler, retained input, removal of stale errors, and repeated validation. This checks the script’s state transitions, not actual browser focus or spoken announcements.

The attempted browser verification was blocked at browser launch by the test environment. Manual keyboard and screen-reader testing, zoom/reflow review, and a full accessibility audit were not performed. This example makes no WCAG conformance claim. Before shipping, verify the spoken label and error, visible keyboard focus, repeated submissions, and recovery from server failures in the actual portal.

This standalone example parses USD decimal strings, adds integer cents, and formats the result. It is a software tutorial, not financial or accounting advice, and it does not describe Scopefolio’s implementation.

A small total makes the goal concrete. Save the functions below as money.mjs, then put this in example.mjs:

import { parseUsd, formatUsd } from './money.mjs';

const total = parseUsd('19.99') + parseUsd('0.10') + parseUsd('0.20');
console.log(total.toString());
console.log(formatUsd(total));

The output is 2029, followed by USD 20.29. The amount stays exact from input to display, including when its cent count exceeds JavaScript’s safe-integer range.

Choose an input contract first

JavaScript’s Number uses binary floating point. Decimal fractions can lose precision: 0.1 + 0.2 evaluates to 0.30000000000000004. ECMAScript defines the Number representation.

Integer cents are useful, but a Number still has a limit. Its maximum safe integer is 9007199254740991; larger integers are not all distinguishable. The specification documents that boundary. This example uses BigInt so integer addition stays exact beyond it.

The parser accepts an optional minus sign, ASCII digits, a decimal point, and exactly two fractional digits. Examples are "0.10", "19.99", and "-2.50". It rejects whitespace, grouping separators, exponent notation, leading zeros, and extra decimal places. Inputs must already be strings: converting a rounded number to a string cannot recover its original value.

This strict grammar suits an API boundary. A user-facing form may need a separate normalization step with clear validation messages. Keeping that step separate lets the calculation layer receive one predictable format.

Parse once, then calculate in cents

export function parseUsd(text) {
  if (typeof text !== 'string') throw new TypeError('Expected a string');
  if (text.length > 40) throw new RangeError('Amount is too long');
  const m = /^(-?)(0|[1-9][0-9]*)\.([0-9]{2})$/.exec(text);
  if (!m) throw new SyntaxError('Expected USD decimal');
  const cents = BigInt(m[2]) * 100n + BigInt(m[3]);
  return m[1] ? -cents : cents;
}

export function formatUsd(cents) {
  if (typeof cents !== 'bigint') throw new TypeError('Expected bigint');
  const sign = cents < 0n ? '-' : '';
  const magnitude = cents < 0n ? -cents : cents;
  const whole = magnitude / 100n;
  const fraction = (magnitude % 100n).toString().padStart(2, '0');
  return `USD ${sign}${whole}.${fraction}`;
}

The parser converts the whole and fractional digit groups separately. "19.99" becomes 19n * 100n + 99n, or 1999n. It never calls parseFloat, multiplies a decimal Number, or guesses a rounding rule. The 40-character limit is an example input-size guard, not a USD rule; choose bounds appropriate to your application.

Use bigint literals such as 100n consistently in arithmetic. BigInt represents integers and defines exact addition. It cannot represent a fractional cent. The parser therefore rejects "1.005" rather than silently choosing whether it means 100 or 101 cents.

The formatter separates the sign before dividing, then pads the remainder to two digits. That keeps -1n readable as USD -0.01. An input of "-0.00" becomes 0n and displays as USD 0.00.

Test the boundaries

Save this as money.test.mjs alongside the other files:

import test from 'node:test';
import assert from 'node:assert/strict';
import { parseUsd, formatUsd } from './money.mjs';

test('adds exact cents', () => {
  const total = parseUsd('19.99') + parseUsd('0.10') + parseUsd('0.20');
  assert.equal(total, 2029n);
  assert.equal(formatUsd(total), 'USD 20.29');
});

test('preserves cents beyond the Number safe-integer limit', () => {
  const cents = parseUsd('90071992547409.93');
  assert.equal(cents, 9007199254740993n);
  assert.equal(formatUsd(cents), 'USD 90071992547409.93');
});

test('handles negatives and normalizes negative zero', () => {
  assert.equal(formatUsd(parseUsd('-0.01')), 'USD -0.01');
  assert.equal(formatUsd(parseUsd('-0.00')), 'USD 0.00');
});

test('rejects malformed input and wrong types', () => {
  for (const value of ['', '1', '1.0', '01.00', '+1.00', ' 1.00',
    '1.00\n', '1,000.00', '1e2', '1.001']) {
    assert.throws(() => parseUsd(value), SyntaxError);
  }
  assert.throws(() => parseUsd(1), TypeError);
  assert.throws(() => parseUsd('9'.repeat(41)), RangeError);
  assert.throws(() => formatUsd(100), TypeError);
});

test('round-trips every cent from -100.00 through 100.00', () => {
  for (let cents = -10000n; cents <= 10000n; cents++) {
    assert.equal(parseUsd(formatUsd(cents).slice(4)), cents);
  }
});

Run node example.mjs and node --test money.test.mjs. These commands use Node’s built-in test runner, so no package installation is needed.

The example and this exact suite were executed on Node v26.11.1. All five tests passed, with zero failures or skips. The final test checked 20,001 round trips. This verifies the listed behavior in that runtime; it does not establish that every money-related requirement is covered.

The large-value case matters because ordinary-looking examples can pass even when a later conversion loses precision. The invalid-input cases also document decisions: "1.0" is rejected intentionally, and a trailing newline is not silently ignored.

Keep currency, display, and rounding explicit

formatUsd produces a fixed ASCII representation without locale-specific separators. For localized display, current Intl.NumberFormat semantics can preserve decimal-string input without first converting it to Number. ECMA-402 specifies that conversion. Test the behavior in your target runtime, and avoid introducing a lossy Number(cents) conversion just to format a result.

At an API or database boundary, preserve both the amount and its unit. For example, a record might store a currency code of USD and a decimal-string cent count of "2029". Define a matching validation rule when reading that record back; it is a different format from the dollar input accepted here. Never infer the unit from the number alone: 2029 cents and 2029 dollars are very different values.

The factor of 100 belongs to this USD contract. Other currencies can use different fractional-digit counts; ECMA-402 treats currency digits separately. A multi-currency system should carry a currency code with each amount and reject addition across currencies unless an explicit conversion has occurred.

Finally, percentages and allocation need their own rules. BigInt division truncates toward zero, so splitting 100 cents three ways produces a remainder. Decide how to round and distribute that remainder before implementing taxes, discounts, or splits.

For this limited workflow, the invariant is simple: validated USD strings enter, bigint cents are added, and formatting preserves every cent. Keep that invariant visible in both the API and the tests.

A project integration receives a completion event, saves the new status, and loses its HTTP response on the way back to the sender. The sender retries. Your endpoint now has to recognize work it already committed.

Recording an event ID helps, but the receipt and project update need to succeed together. Saving the receipt first can lose work after a crash. Saving it afterward can allow the same work twice.

Define the guarantees before the handler

This illustrative integration receives immutable events containing a project snapshot and an increasing integer revision. A revision identifies one project state. The trusted connection key identifies the provider and source account; project IDs and event IDs are unique within that connection.

Those are requirements of this example, not universal webhook guarantees. Stripe's webhook documentation, for example, warns about both duplicate deliveries and unordered events. An event timestamp is not a reliable substitute for a resource revision.

Save this as store.mjs. It uses Node's built-in SQLite module, without installing packages:

import {DatabaseSync} from "node:sqlite";

export function store() {
  const db = new DatabaseSync(":memory:");
  db.exec(`
    CREATE TABLE receipts (
      connection TEXT NOT NULL, id TEXT NOT NULL,
      PRIMARY KEY(connection, id)
    );
    CREATE TABLE projects (
      connection TEXT NOT NULL, id TEXT NOT NULL,
      version INTEGER NOT NULL,
      status TEXT NOT NULL CHECK(status IN ('active', 'done')),
      PRIMARY KEY(connection, id)
    );
  `);
  const receipt = db.prepare(`INSERT INTO receipts VALUES (?, ?)
    ON CONFLICT(connection, id) DO NOTHING`);
  const update = db.prepare(`INSERT INTO projects VALUES (?, ?, ?, ?)
    ON CONFLICT(connection, id) DO UPDATE SET
      version = excluded.version, status = excluded.status
    WHERE excluded.version > projects.version`);

  function apply(e) {
    if (!e || ![e.connection, e.id, e.project, e.status].every(
      value => typeof value === "string" && value.length > 0) ||
      !Number.isSafeInteger(e.version) || e.version < 1) {
      throw new Error("Invalid event");
    }
    db.exec("BEGIN IMMEDIATE");
    try {
      let result = "duplicate";
      if (receipt.run(e.connection, e.id).changes) {
        result = update.run(e.connection, e.project, e.version, e.status)
          .changes ? "applied" : "stale";
      }
      db.exec("COMMIT");
      return result;
    } catch (error) {
      db.exec("ROLLBACK");
      throw error;
    }
  }
  return {db, apply};
}

Keep two decisions separate

The receipt's unique key handles repeated deliveries of one event. The conditional update handles a different event that describes an older or equal revision. Both are necessary. A previously unseen event can still contain stale state.

The receipt remains committed for a stale event because processing it is complete. A failed update rolls back its new receipt, allowing a retry after the underlying problem is fixed. SQLite documents these transaction boundaries and the conditional behavior of UPSERT.

Exercise the failure path

Save this as store.test.mjs:

import assert from "node:assert/strict";
import test from "node:test";
import {store} from "./store.mjs";

test("duplicate, stale, isolated, and failed deliveries", () => {
  const {db, apply} = store();
  const e = {connection: "tracker:team-a", id: "e2",
    project: "p1", version: 2, status: "done"};
  try {
    assert.equal(apply(e), "applied");
    assert.equal(apply(e), "duplicate");
    assert.equal(apply({...e, id: "e1", version: 1, status: "active"}), "stale");
    assert.equal(db.prepare("SELECT status FROM projects").get().status, "done");
    assert.equal(apply({...e, connection: "tracker:team-b"}), "applied");
    assert.throws(() => apply({...e, id: "e3", version: 3, status: "invalid"}));
    assert.equal(db.prepare("SELECT count(*) AS n FROM receipts WHERE id='e3'")
      .get().n, 0);
    assert.equal(apply({...e, id: "e3", version: 3, status: "active"}), "applied");
  } finally {
    db.close();
  }
});

Run node --test store.test.mjs. This exact example passed its test and eight assertions on Node v24.19.0. The test uses memory storage and does not demonstrate durability across process crashes or concurrent workers.

Connect this core carefully

Verify the provider's signature using its documented method before creating trusted input. For Stripe, verification needs the unmodified request body. Validate the event type and schema, and resolve the connection from authenticated configuration. An event ID cannot authenticate a sender. Stripe's verification guidance explains that boundary.

A deployed handler needs persistent storage, migrations, lock-contention handling, and a receipt-retention policy covering supported replays. Acknowledge success only after this short transaction, or after durably queuing the event for later processing.

Keep the connection namespace in both tables. Two independent customer accounts may each have a project named p1 and an event named e2. A globally unique receipt key alone would let the first account suppress the second account's update. The isolation assertion exercises this exact collision.

Log the event ID, connection, and result without storing unnecessary payload data. Repeated duplicate results can be normal; database errors need investigation. If one revision ever arrives with conflicting state, the source has violated this model's assumptions. Flag that inconsistency rather than silently choosing whichever payload arrived first.

If a provider supplies no reliable revision, use a provider-specific reconciliation strategy instead of inventing ordering from arrival time. For notifications or other external effects, write an outbox job in the same transaction and make its consumer idempotent too. A database rollback cannot unsend an email.

An invoice is marked paid. A refund arrives, but the label stays unchanged because the refund handler never updates it. Every screen now has to recalculate the balance.

Record invoice, payment, and refund entries, then derive payment status from the billed amount and net payments. This is an illustrative software model, not accounting guidance.

Make the model explicit

This example handles one positive-total invoice in USD, with amounts in integer cents. Entries arrive in ledger order: issuance first, and each refund after its referenced payment. Only confirmed payment and refund events belong here. Pending attempts, fees, credit notes, cancellation, tax calculation, and currency conversion are outside the model.

A refund reduces net payments without changing the billed amount. Therefore, a refund can reopen the balance. A full refund produces unpaid, while the separate refund total preserves the history. If your workflow also reduces the billed amount, add an explicit adjustment model before using these statuses for customer-facing decisions.

The four statuses are unpaid when net payments are zero, partial when they are below the invoice total, paid at equality, and overpaid above it. A negative balance means excess payment; it must remain visible.

Encode the invariants

JavaScript's BigInt specification defines integer arithmetic without a fixed bit-width. Here, 10000n means 10,000 cents. The reducer accepts positive BigInt amounts directly; text parsing and display formatting belong at the boundaries.

Save this as ledger.mjs:

export function summarize(entries) {
  const invoice = entries[0];
  if (invoice?.type !== 'invoice' || typeof invoice.invoiceId !== 'string' || !invoice.invoiceId)
    throw Error('Invoice must be first');
  const ids = new Set();
  const refundable = new Map();
  let billed = 0n, paid = 0n, refunded = 0n;

  for (const e of entries) {
    if (typeof e.id !== 'string' || !e.id || ids.has(e.id))
      throw Error('Invalid or duplicate entry ID');
    if (e.currency !== 'USD' || e.invoiceId !== invoice.invoiceId)
      throw Error('Wrong currency or invoice');
    if (typeof e.amount !== 'bigint' || e.amount <= 0n)
      throw Error('Amount must be positive BigInt cents');
    ids.add(e.id);

    if (e.type === 'invoice' && billed === 0n) {
      billed = e.amount;
    } else if (e.type === 'payment') {
      paid += e.amount;
      refundable.set(e.id, e.amount);
    } else if (e.type === 'refund') {
      const available = refundable.get(e.paymentId) ?? 0n;
      if (e.amount > available) throw Error('Invalid refund');
      refundable.set(e.paymentId, available - e.amount);
      refunded += e.amount;
    } else {
      throw Error('Unknown type or second invoice');
    }
  }

  const netPaid = paid - refunded;
  const balance = billed - netPaid;
  const status = netPaid === 0n ? 'unpaid'
    : balance > 0n ? 'partial'
    : balance === 0n ? 'paid' : 'overpaid';
  return { status, billed, paid, refunded, netPaid, balance };
}

The important checks are structural. Each entry has a unique ID, belongs to the same invoice and currency, and has a supported type. Refunds consume the remaining refundable amount of a specific payment. Checking only total refunds against total payments would allow one payment to be over-refunded while another hides the mistake.

Returning totals alongside the label lets screens explain results and tests verify the arithmetic: balance = billed - paid + refunded.

Exercise the transitions

Save this as ledger.test.mjs beside the reducer. The fixture issues a $100 invoice, receives $100, and refunds $25, producing a partial payment status with a $25 balance.

import test from 'node:test';
import assert from 'node:assert/strict';
import { summarize } from './ledger.mjs';

const entry = (id, type, amount, paymentId) => ({
  id, type, amount, paymentId, invoiceId: 'inv-1', currency: 'USD'
});
const invoice = entry('i1', 'invoice', 10000n);
const payment = entry('p1', 'payment', 10000n);
const refund = entry('r1', 'refund', 2500n, 'p1');
const fixture = [invoice, payment, refund];

test('fixture reopens a paid balance', () => {
  assert.deepEqual(summarize(fixture), {
    status: 'partial', billed: 10000n, paid: 10000n,
    refunded: 2500n, netPaid: 7500n, balance: 2500n
  });
});

test('all four statuses', () => {
  for (const [amount, status] of [
    [0n, 'unpaid'], [1n, 'partial'],
    [10000n, 'paid'], [10001n, 'overpaid']
  ]) {
    const rows = amount ? [invoice, { ...payment, amount }] : [invoice];
    assert.equal(summarize(rows).status, status);
  }
});

test('rejects duplicate IDs and excessive cumulative refunds', () => {
  assert.throws(() => summarize([...fixture, payment]), /duplicate/);
  const excess = entry('r2', 'refund', 7501n, 'p1');
  assert.throws(() => summarize([...fixture, excess]), /Invalid refund/);
});

Run node --test ledger.test.mjs using Node's built-in test runner. These three tests passed on Node.js v24.19.0. They cover the fixture, every status, duplicate records, and cumulative refund limits. They do not exercise a database or payment provider.

Protect the write path too

This pure function validates a snapshot. Two concurrent refund requests can each read the same available amount and both pass individually. The persistence layer must serialize the relevant check and append, using a transaction with suitable locking or a version check that rejects stale writes. Otherwise, a correct reducer simply discovers the invalid history afterward.

Keep ledger records append-only through your write API. Model corrections with explicit events and documented effects rather than editing old amounts. At ingestion, use a stable provider event identifier with a database uniqueness constraint. Receiving the same event twice should not create two ledger rows; conflicting payloads for one identifier deserve investigation.

A stored status can be a cache: rebuild it from the ledger, associate it with the ledger version, and test replay. During migration, compare derived results with existing labels and investigate differences before changing screens.

An import preview should answer a practical question: what would change if this file were accepted? A reassuring “dry run” label provides little protection when the same function can update records, send notifications, and then attempt a rollback.

A clearer design separates planning from execution. Give the planner a current snapshot and staged candidate records. It returns proposed changes and validation errors. It has no database connection, filesystem access, or network client.

Here, staging means holding a parsed candidate in memory. Nothing is persisted. All fixture records are invented, and the implementation is an independent teaching example.

Define the import policy

This miniature importer handles records with exactly two fields: id and name. IDs follow a deliberately narrow pattern, such as A01. Names must contain non-whitespace text and stay within 100 UTF-16 code units. Each input array is limited to 1,000 records; these are example limits rather than capacity measurements.

An existing ID can change its name. A new ID becomes a proposed creation. Identical records produce no action. Missing IDs never imply deletion, and duplicate IDs in the uploaded data block the entire plan.

Choose these policies with the person responsible for the data. In particular, do not silently use “last row wins” when two uploaded rows disagree. That converts a validation problem into an order-dependent decision.

Build and test the planner

The code below expects JSON-derived records and a trusted current snapshot. It does not defend against executable getters or other arbitrary JavaScript objects. A Map provides the explicit ID lookup; its key-value behavior is defined in the ECMAScript specification.

Save the whole block as import-plan.test.mjs and run node import-plan.test.mjs. No third-party packages are required.

import assert from 'node:assert/strict';

const valid = row => row !== null && typeof row === 'object'
  && Object.keys(row).sort().join(',') === 'id,name'
  && typeof row.id === 'string' && /^[A-Z][0-9]{2}$/.test(row.id)
  && typeof row.name === 'string' && row.name.trim().length > 0
  && row.name.length <= 100;

export function buildPlan(current, incoming) {
  if (![current, incoming].every(a => Array.isArray(a) && a.length <= 1000))
    throw new TypeError('Expected bounded arrays');
  const existing = new Map();
  for (const row of current) {
    if (!valid(row) || existing.has(row.id))
      throw new TypeError('Invalid current snapshot');
    existing.set(row.id, row.name);
  }
  const seen = new Set(), errors = [], actions = [];
  for (const [index, row] of incoming.entries()) {
    if (!valid(row)) {
      errors.push({row: index + 1, reason: 'Invalid schema'});
      continue;
    }
    if (seen.has(row.id)) {
      errors.push({row: index + 1, reason: 'Duplicate id'});
      continue;
    }
    seen.add(row.id);
    const before = existing.get(row.id);
    if (before !== row.name) actions.push({
      kind: existing.has(row.id) ? 'update' : 'create',
      id: row.id, before: before ?? null, after: row.name,
    });
  }
  return {ready: errors.length === 0, errors,
    actions: errors.length ? [] : actions};
}

const current = [{id: 'A01', name: 'Draft'}, {id: 'B02', name: 'Keep'}];
const incoming = [{id: 'A01', name: 'Ready'}, {id: 'C03', name: 'New'},
  {id: 'B02', name: 'Keep'}];
const snapshot = structuredClone({current, incoming});
const plan = buildPlan(current, incoming);
assert.deepEqual(plan, {ready: true, errors: [], actions: [
  {kind: 'update', id: 'A01', before: 'Draft', after: 'Ready'},
  {kind: 'create', id: 'C03', before: null, after: 'New'},
]});
assert.deepEqual({current, incoming}, snapshot);
assert.deepEqual(buildPlan(current, incoming), plan);
assert.deepEqual(buildPlan(current, []), {ready: true, errors: [], actions: []});
for (const bad of [null, {id: 'D04', name: ''}, {id: 4, name: 'Bad'},
  {id: 'D04', name: 'Okay', extra: true}]) {
  const blocked = buildPlan(current, [...incoming, bad]);
  assert.equal(blocked.ready, false);
  assert.deepEqual(blocked.actions, []);
  assert.equal(blocked.errors[0].row, 4);
}
assert.equal(buildPlan(current, [...incoming, incoming[0]]).errors[0].reason,
  'Duplicate id');
assert.throws(() => buildPlan([...current, current[0]], []), TypeError);
assert.throws(() => buildPlan(current, Array(1001).fill(incoming[0])), TypeError);
console.log('Import-plan acceptance checks passed');

This exact file ran on Node.js v24.19.0 and printed Import-plan acceptance checks passed. The assertions check proposed creations and updates, unchanged inputs, repeatable results, empty imports, malformed records, duplicate IDs, and the row limit.

Make the preview actionable

The plan includes old and proposed values, so a reviewer can understand each change. Error positions are one-based array rows, not physical CSV line numbers. A quoted multiline CSV field can occupy several physical lines, so keep parser location information separately if your interface needs it.

A single invalid incoming row removes every executable action from the returned plan. This all-or-nothing preview policy prevents callers from accidentally applying the valid subset while ignoring errors. The planner also refuses an invalid current snapshot rather than making proposals from an ambiguous baseline.

For an actual client dataset, keep previews access-controlled and avoid writing complete rows into logs. Display only the fields needed for review. The names in this tutorial are short labels, not real client identities.

Keep confirmation and execution outside this function

A valid plan is still only a proposal. After explicit confirmation, the application must recheck permissions and the underlying data, and apply only the reviewed input. Keep the reviewed input server-side; do not trust a browser-supplied list of arbitrary write operations.

If another process changes the data after preview, reject the stale plan and request a fresh review. The actual executor needs transactional writes and appropriate concurrency checks. PostgreSQL’s transaction documentation explains atomic commit and rollback; its isolation documentation explains why concurrent changes need separate attention.

Keep notifications and other external effects out of preview entirely. A successful preview never authorizes those effects. Database rollback cannot retract an email already sent. The useful boundary is visible in the function signature: the preview receives values and produces values, while a separately authorized operation owns persistence.

“Export these records as CSV” leaves several decisions unresolved. Does an empty export contain a header? Can a note contain a comma? What happens when a record has fewer fields than the header? A screenshot of a successful download answers none of those questions.

For a small client project, a useful next step is to turn each decision into an input and an exact expected result. The exercise below builds a bounded, in-memory exporter. It is an independent teaching example, with fictional data.

Write the contract before the function

This export has five acceptance criteria:

1. Always include the supplied header, even when there are no data rows
2. End every record with carriage return plus line feed, written as \r\n
3. Quote fields containing a comma, double quote, carriage return, or line feed; double every embedded quote
4. Preserve empty strings and spaces; reject missing cells and non-string values
5. Reject oversized input instead of silently truncating it

The quoting and record-separator choices follow the conventions described in RFC 4180. That document is informational, and CSV consumers vary. These criteria describe this exporter’s explicit contract rather than every application that opens CSV.

Notice that these rules apply to headers too. A header containing a comma needs the same escaping as a data field. Keeping one encoding path prevents the two from drifting apart.

Run the implementation and its examples

Save this complete file as csv.test.mjs, then run node csv.test.mjs. It uses Node’s built-in strict assertions, so no package installation is needed.

import assert from 'node:assert/strict';

export function toCsv(headers, rows) {
  if (!Array.isArray(headers) || headers.length < 1 || headers.length > 20)
    throw new TypeError('Expected 1–20 headers');
  if (!Array.isArray(rows) || rows.length > 1000)
    throw new TypeError('Expected at most 1000 rows');
  let result = '';
  for (const row of [headers, ...rows]) {
    if (!Array.isArray(row) || row.length !== headers.length)
      throw new TypeError('Wrong column count');
    const cells = Array.from(row, value => {
      if (typeof value !== 'string' || value.length > 10000)
        throw new TypeError('Expected a short string');
      return /[",\r\n]/.test(value)
        ? `"${value.replaceAll('"', '""')}"` : value;
    });
    result += cells.join(',') + '\r\n';
    if (result.length > 1000000) throw new RangeError('Export too large');
  }
  return result;
}

assert.equal(toCsv(['name', 'note'], []), 'name,note\r\n');
assert.equal(toCsv(['name', 'note'], [['Mina', 'ready']]),
  'name,note\r\nMina,ready\r\n');
for (const [input, encoded] of [
  ['a,b', '"a,b"'], ['a"b', '"a""b"'],
  ['a\nb', '"a\nb"'], ['a\rb', '"a\rb"'],
  ['a\r\nb', '"a\r\nb"'], ['', ''], [' x ', ' x '],
]) assert.equal(toCsv(['value'], [[input]]), `value\r\n${encoded}\r\n`);
assert.equal(toCsv(['a,b'], [['ok']]), '"a,b"\r\nok\r\n');
for (const rows of [[['too', 'wide']], [[null]], [Array(1)]])
  assert.throws(() => toCsv(['value'], rows), TypeError);
assert.throws(() => toCsv([], []), TypeError);
assert.throws(() => toCsv(['v'], Array(1001).fill(['x'])), TypeError);
assert.throws(() => toCsv(['v'], [['x'.repeat(10001)]]), TypeError);
assert.throws(() => toCsv(['v'], Array(101).fill(['x'.repeat(10000)])), RangeError);
assert.equal(toCsv(['value'], [['=1+1']]), 'value\r\n=1+1\r\n');
console.log('CSV acceptance checks passed');

The file was run with Node.js v24.19.0 and printed CSV acceptance checks passed. That result covers these fixtures; it does not establish compatibility with every spreadsheet or downstream importer.

Make failures explain the requirement

The expected strings are written independently of the encoder. Constructing expected values by calling the same escaping helper would allow a shared mistake to pass. The quote fixture distinguishes doubling an embedded quote from merely wrapping the cell. Separate carriage-return and line-feed fixtures catch a common incomplete check that only looks for \n.

An export containing the right number of lines can still corrupt a quoted newline, so compare complete records rather than splitting on newlines.

The sparse-array case is deliberate. JavaScript arrays can have a length without a value at each position. Array.from visits those positions and passes undefined to validation, preventing an accidental empty-field conversion.

The limits are teaching defaults: 20 columns, 1,000 data rows, 10,000 UTF-16 code units per cell, and 1,000,000 code units in the output. They are not UTF-8 byte limits or measured capacity recommendations. This function holds the output in memory; a large production export needs a streaming design and separately tested backpressure and cancellation behavior.

Keep format correctness separate from product decisions

The last assertion preserves =1+1 exactly. That is important evidence about the contract: CSV quoting alone does not prevent spreadsheet formula interpretation. If users will open untrusted values in a spreadsheet, agree on a separate safety policy and test it against the actual consumer. OWASP’s CSV injection guidance describes this risk and cautions that mitigations vary across spreadsheet workflows.

Also decide how your application selects records, checks export permissions, formats dates, encodes the returned string, and names the download. Those belong in additional tests at their own boundaries. This example deliberately accepts already formatted strings and performs no file or network writes.

Acceptance criteria become useful when a reader can point to a failing example and understand which promise was broken. Start with that mapping, then expand the test set whenever a real input exposes another decision.

A JSON diff can tell you that an array changed on six lines. A developer reviewing a project update needs a more useful answer: which requirement was added, what changed in the export feature, and whether someone merely rearranged the list.

A small semantic diff can answer those questions without an AI service or a general-purpose diff dependency. The important work is choosing identity and comparison rules before writing the loop.

Give each requirement an identity

Use a stable ID that survives renaming and reordering. A title is editable content. An array position changes whenever someone inserts an item above it. Neither makes a reliable identity.

This example compares three fields: title, acceptance text, and estimated whole hours. Extra metadata is ignored deliberately. Duplicate IDs are rejected because silently overwriting a record would hide a change.

A JavaScript Map makes those ID lookups explicit; its keys are unique, as described in the ECMAScript Map specification. Save this as diff.mjs:

export function index(rows) {
  if (!Array.isArray(rows)) throw new Error("Expected an array");
  const map = new Map();
  for (const row of rows) {
    if (!row || typeof row.id !== "string" || !row.id.trim() ||
        typeof row.title !== "string" ||
        typeof row.acceptance !== "string" ||
        !Number.isSafeInteger(row.hours) || row.hours < 0) {
      throw new Error("Invalid requirement");
    }
    if (map.has(row.id)) throw new Error(`Duplicate ID: ${row.id}`);
    map.set(row.id, row);
  }
  return map;
}

export function diff(before, after) {
  const old = index(before), next = index(after);
  const added = after.filter(row => !old.has(row.id));
  const removed = before.filter(row => !next.has(row.id));
  const modified = [];
  for (const row of after) {
    const previous = old.get(row.id);
    if (!previous) continue;
    const changes = [];
    for (const field of ["title", "acceptance", "hours"]) {
      if (previous[field] !== row[field]) {
        changes.push({field, before: previous[field], after: row[field]});
      }
    }
    if (changes.length) modified.push({id: row.id, changes});
  }
  const oldOrder = before.filter(row => next.has(row.id)).map(row => row.id);
  const newOrder = after.filter(row => old.has(row.id)).map(row => row.id);
  const reordered = oldOrder.some((id, i) => id !== newOrder[i]);
  return {added, removed, modified, reordered};
}

Compare the surviving sequence

The order check first removes IDs absent from the other snapshot. That detail prevents a misleading result: inserting a new requirement at the top shifts every numeric position, but the existing requirements still have the same relative order.

Reversing two surviving IDs sets reordered to true. Their content stays out of modified unless a compared field also changed. A single update can therefore contain both content edits and a reorder.

String comparison is exact. Changing punctuation or whitespace in acceptance text appears as an edit. If your domain treats certain formatting as equivalent, define that normalization at the input boundary and preserve the original text for display. Automatically lowercasing requirements could conceal meaningful changes in identifiers or examples.

Check the cases that confuse line diffs

Save this beside the implementation as diff.test.mjs:

import assert from "node:assert/strict";
import test from "node:test";
import {diff} from "./diff.mjs";

const a = {id: "export", title: "Export", acceptance: "CSV download", hours: 4};
const b = {id: "search", title: "Search", acceptance: "Match titles", hours: 3};
const c = {id: "sort", title: "Sort", acceptance: "Newest first", hours: 2};
const empty = {added: [], removed: [], modified: [], reordered: false};

test("identity and property order do not create changes", () => {
  assert.deepEqual(diff([a], [{hours: 4, acceptance: a.acceptance,
    title: a.title, id: a.id}]), empty);
});
test("addition and removal retain their records", () => {
  assert.deepEqual(diff([a, b], [a, c]), {...empty, added: [c], removed: [b]});
});
test("rename and estimate change stay attached to the same ID", () => {
  assert.deepEqual(diff([a], [{...a, title: "Export CSV", hours: 6}]).modified,
    [{id: "export", changes: [
      {field: "title", before: "Export", after: "Export CSV"},
      {field: "hours", before: 4, after: 6}
    ]}]);
});
test("reordering leaves content unchanged", () => {
  assert.deepEqual(diff([a, b], [b, a]), {...empty, reordered: true});
});
test("insertion does not move surviving requirements", () => {
  assert.equal(diff([a, b], [c, a, b]).reordered, false);
});
test("duplicates and invalid estimates fail explicitly", () => {
  assert.throws(() => diff([a, a], [a]), /Duplicate ID/);
  assert.throws(() => diff([a], [a, a]), /Duplicate ID/);
  assert.throws(() => diff([a], [{...a, hours: NaN}]), /Invalid/);
});

Run node --test diff.test.mjs. These exact files were executed on Node v24.19.0: six tests passed, with no failures or skips. The Node test runner documentation covers the built-in runner.

Turn the result into a useful summary

Render modifications by ID and field: “Export: estimated hours changed from 4 to 6.” Keep additions and removals separate. Show a short ordering notice when reordered is true; the boolean does not identify a minimal set of moves.

Keep both source snapshots alongside the result. This function returns references for added and removed records, so clone them if the caller will mutate the snapshots. When displaying text in HTML, use text nodes or your framework's normal escaping.

Finally, keep identity stable across storage and editing. Regenerating every ID on save makes every requirement look newly created. A readable summary begins with a data model that can recognize the same requirement tomorrow.

A client adds an export feature to a software project due on Friday, November 13, 2026. The estimated schedule impact is two working days. With a Monday–Friday calendar, the proposed delivery date becomes Tuesday, November 17.

Two bugs can quietly move that date again. A calculator might add a weekend adjustment after it has already skipped weekends. Or an edited scope request might add its entire estimate to an already revised deadline.

The following standalone JavaScript example prevents both: visit each calendar date once, and recalculate from the unchanged original deadline using the latest total schedule impact.

Define a working day

This example uses a deliberately small policy:

• Saturday and Sunday are nonworking days
• Counting starts the day after the original deadline
• Zero extra days leaves the original date unchanged, even on a weekend
• Explicit holiday dates are also excluded
• Inputs are whole working days, from zero through 3,660

The holiday list belongs to the project calendar. November 16 is a fictional team closure in the example below, with no claim about any country's public holidays. Weekend holidays receive no additional adjustment. Observed holidays must be supplied explicitly.

First decide the schedule impact of a scope change. Two person-days of effort do not necessarily move delivery by two days: parallel work, dependencies, and availability can change the result. The function accepts an already assessed delay in working days.

Keep calendar arithmetic independent of local time

Store deadlines as strict YYYY-MM-DD strings. Internally, use UTC fields consistently, keeping local timezone offsets and daylight-saving transitions out of the calculation. UTC is an implementation convention here; the deadline remains a calendar date.

Save this as delivery-date.mjs:

function parseDateOnly(value) {
  if (typeof value !== 'string' || value.length !== 10 ||
      !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
    throw new TypeError('Expected YYYY-MM-DD');
  }
  const [year, month, day] = value.split('-').map(Number);
  const date = new Date(0);
  date.setUTCFullYear(year, month - 1, day);
  if (year < 1 || date.getUTCFullYear() !== year ||
      date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
    throw new RangeError('Invalid calendar date');
  }
  return date;
}

export function revisedDeliveryDate(base, totalDays, holidays = new Set()) {
  const date = parseDateOnly(base);
  if (!Number.isInteger(totalDays) || totalDays < 0 || totalDays > 3660) {
    throw new RangeError('Expected 0 to 3660 whole working days');
  }
  if (!(holidays instanceof Set) || holidays.size > 1000) {
    throw new TypeError('Expected a Set of at most 1000 holiday dates');
  }
  for (const holiday of holidays) parseDateOnly(holiday);
  let remaining = totalDays;
  while (remaining > 0) {
    date.setUTCDate(date.getUTCDate() + 1);
    if (date.getUTCFullYear() > 9999) {
      throw new RangeError('Result exceeds year 9999');
    }
    const weekday = date.getUTCDay();
    const key = date.toISOString().slice(0, 10);
    if (weekday !== 0 && weekday !== 6 && !holidays.has(key)) remaining--;
  }
  return date.toISOString().slice(0, 10);
}

JavaScript's date setters normalize overflowing fields, so the parser checks the resulting year, month, and day against the supplied values. That rejects impossible dates such as 2026-02-29. The exact-length check also rejects trailing newlines. ECMAScript specifies the UTC year setter.

Inside the loop, one calendar day is visited per iteration. The remaining count decreases only when that date is both a weekday and absent from the holiday set. There is no separate weekend-padding pass. The UTC date setter defines the calendar rollover behavior.

The 3,660-day and 1,000-holiday limits are example application bounds. The supported year range is 0001–9999; overflow is rejected. Every holiday is validated, including when the requested offset is zero.

Recalculate from the original deadline

Save this as example.mjs beside the function:

import assert from 'node:assert/strict';
import { revisedDeliveryDate as revise } from './delivery-date.mjs';

const original = '2026-11-13';
assert.equal(revise(original, 2), '2026-11-17');
assert.equal(revise(original, 2), '2026-11-17'); // Recalculate safely.
assert.equal(revise(original, 3), '2026-11-18'); // New total, same base.
assert.equal(original, '2026-11-13');
const holidays = new Set(['2026-11-16']); // Fictional team closure.
assert.equal(revise(original, 2, holidays), '2026-11-18');
console.log('Examples passed');

Run node example.mjs; successful execution prints Examples passed.

The second call deliberately repeats the first. Both return November 17 because the inputs are identical. When the total grows from two to three working days, the proposal becomes November 18. Passing the previous proposal back as the base would apply the earlier delay again. In this example, adding two working days to November 17 produces November 19, even though the scope estimate has not changed.

Keep the original deadline, the latest total schedule impact, and the proposed date as separate values. When an estimate decreases or a request is removed, recompute from the same original deadline. Also preserve the calendar used for the proposal: changing holiday inputs can legitimately change the result.

At the storage boundary, keep the date-only string intact. A form should display that calendar date without first converting it into a local timestamp. Store review timestamps separately when you need to know precisely when a proposal was created or approved. These values answer different questions and need different validation rules.

Test before using the proposal

This exact implementation and a 15-test companion suite were executed on Node v24.19.0 under UTC, America/New_York, Europe/London, Asia/Kolkata, and Pacific/Auckland. All 15 tests passed in each timezone, with zero failures or skips.

The suite covers repeated calculations, weekend/holiday overlap, zero offsets, leap years, year boundaries, daylight-saving transition weekends, invalid inputs, and the supported bounds. Run equivalent cases in your target runtime and project calendar.

Finally, show the calculation alongside the scope revision: original deadline, total additional working days, calendar assumptions, and proposed date. Keep client approval as a separate recorded decision. A deterministic calculation makes a proposal reproducible; it does not establish agreement to a new delivery commitment.

A short delivery review helps you answer those questions before launch. Start with the agreed scope and approved changes, then give the client one review link, one checklist and a clear decision to make.

1. Identify the exact version being reviewed

Label the delivery with a date or version and include its staging link. List the pages, features and approved changes included in that version.

Keep a dated record of what the client reviewed. If you change something material afterward, identify the change and ask for the relevant checks again. An approval attached to an old preview leaves everyone guessing.

2. Check the agreed customer journeys

Ask the client to work through the journeys that matter to this website:

• Find the service, product or information a visitor needs.
• Use the navigation and agreed mobile layouts.
• Submit a test enquiry and confirm it reaches the intended inbox.
• Complete any included booking, purchase or account flow in the appropriate test environment.
• Check page copy, contact details, images and download links.

Choose checks that match your agreed deliverables. Share your own test results alongside the review request so the client has evidence to work from.

3. Record remaining issues before requesting approval

Make one short list containing each issue, its owner and the agreed next step. Mark anything that prevents launch. For smaller items, get an explicit decision about whether they can follow after launch and when they are due.

Keep feedback specific. A form that fails an agreed acceptance check is a defect to assess against the agreement. A newly requested customer portal is a scope change. Clarifications and included revisions may need their own treatment.

Resolve that classification before promising a fix date or quoting extra work. For the longer process, see our guide to handling scope changes in fixed-price web projects.

4. Confirm ownership and the handover plan

List each service or asset the client needs to operate the site:

• Domain registration, DNS and hosting
• CMS, repository and deployment access, where included
• Analytics, enquiry forms and other connected services
• Source files, content assets and applicable licence information
• Setup notes and any agreed training or walkthrough

For each item, record the owner, billing responsibility and how access will be provided. Use named accounts and provider invitations where available. If credentials must be transferred, use an agreed password-manager sharing method rather than ordinary email or chat.

Confirm the client can actually sign in and perform the agreed tasks at handover. Record which freelancer access remains necessary for support.

5. Agree on launch and aftercare

Name the person who can approve the delivery and authorise launch. Confirm the launch window, who performs it, the immediate live-site checks and who handles problems.

Write down the support period, reporting channel, included coverage and who owns ongoing updates, backups and renewals. Use specific dates rather than “support after launch.”

Copyable delivery-approval message

Hi [name],

The [version/date] website delivery is ready to review: [staging link].

Please check [acceptance checklist] and review [handover plan]. Open items and their proposed next steps are here: [list].

By [review date], please reply with either:

• Approval of this delivery, including any explicitly agreed open items; or
• The page/feature, expected result and actual result for anything needing attention.

Please also confirm whether you authorise launch during [window]. We’ll confirm the handover and live-site checks separately.

The agreed support period is [dates], covering [coverage]. Report issues through [channel].

Thanks,
[name]

Keep this review with the project’s other decisions so everyone can find what was accepted and what still needs work.

This article is from Scopefolio Support, with AI assistance. Scopefolio offers free early access for recording scope, client approvals, deliveries and handover responsibilities: https://scopefolio.neatgrove.com/.

Drafted with AI assistance

Scopefolio is our product.

A client asks for “one small change.” Before estimating it, work out which promise the request touches. You may owe a correction, have room for an included revision, or need a new agreement. Classifying the request fairly gives a freelance web developer a better starting point than its apparent size. Use the process below to protect the agreed delivery while giving the client a clear choice.

Compare the request with the agreement

Use three working categories, based on the scope and review terms you actually agreed:

• A defect is work that fails an agreed requirement. If the gallery was meant to show complete images but crops them, investigate and correct that failure under the existing agreement. A missed requirement does not become extra work because fixing it takes longer than expected.

• An included revision changes an existing deliverable within the agreed review allowance. Reordering supplied gallery images might qualify. Define what a round covers and how feedback is collected; “one round” should not leave either side guessing about its limits.

• A scope change alters the agreed result, quantity or process. Adding gallery filters may introduce new behaviour. An additional review round can also change the allowance, even if each individual edit seems small.

Split mixed requests into separate items. A client can report a defect and request a feature in the same sentence. Reaching the revision limit should not turn a genuine defect into a paid revision.

Give completion an observable test

Write acceptance criteria before work starts. For a gallery, specify the image count, expected display, interactions and agreed browser checks. Name who supplies the images and whether image editing is included. Record the design version both sides are approving.

Make each check something you can demonstrate together. “Looks professional” invites different interpretations; “displays the twelve supplied images without cropping at the agreed mobile and desktop sizes” gives you a test. Acceptance checks should sit alongside the price, delivery date, client dependencies and review allowance.

Resolve gaps without inventing certainty

Sometimes the brief says only “add a gallery.” A missing detail alone does not establish that a request is chargeable. Review the proposal, approved designs and relevant messages together. Ask what the client expected and explain your interpretation. Then agree the missing detail and its impact before continuing the disputed part.

If you choose a goodwill exception, record exactly what you will include and whether it affects delivery. Do not let an unrecorded favour quietly expand every future request. For an uncertain integration, propose a bounded investigation before promising a fixed implementation price.

Show the whole impact before requesting approval

A useful change proposal identifies the current approved version, the requested result and its new acceptance checks. Estimate implementation, testing and deployment work, and identify any client inputs. Show the price adjustment, complete revised total and revised delivery date. Offer a smaller version, a later phase or the original scope when those are realistic options.

Here is a fictional example. The amounts illustrate the decision, not a recommended rate. A four-page portfolio costs GBP 1,800 and is due on 22 October. It includes a twelve-image gallery without cropping and one consolidated feedback round. During that round, the client requests three things:

• Fix cropped images: a defect against the agreed display requirement

• Reorder the images: an included revision

• Add filters by service: a proposed scope change

The filter proposal adds GBP 240, making the total GBP 2,040, and moves delivery to 26 October. It covers three service filters plus an “All” view, with the selected filter showing only matching images. Delivery assumes approval by 12 October and labels supplied by 14 October. The original fixes and reordering remain covered.

Ask for a decision the client can answer

Copy and adapt this message after checking the request against your agreement. Separate defects and included revisions from proposed changes. If the scope is unclear, resolve that first.

Subject: [Project] change proposal [version]

Hi [client approver],

I’ve checked your request for [request] against our approved scope [version, date and link].

Already covered: [defects or included revisions to handle under the current agreement]

Proposed change: [what will be added, removed or changed]

Reason: [the agreed deliverable, quantity or review limit this changes]

Completion check: [how we’ll verify the changed work]

Price: [currency and current total], with a [currency and increase/decrease] adjustment. The revised project total is [currency and new total].

Delivery: [current date] becomes [proposed date].

Dependencies: approval by [date], plus [client inputs, responsible person and due date].

Please reply “I approve [project] change proposal [exact version], including its scope, revised total, delivery date and dependencies,” or tell me what you’d like adjusted.

I’ll keep the proposed change pending until you approve it. [Explain any effect on the existing work while the decision is pending.] If approval or inputs arrive late, I’ll confirm the delivery date again.

Send the proposal to the designated approver. Save their explicit decision with the exact version. An opened link or unanswered message is not approval. If the scope, price or date changes during discussion, update the proposal and request a decision on that version. Reconfirm delivery if approval or client inputs arrive late.

Check each request before starting

• Which agreed requirement or allowance does this request touch?

• Have defects, included revisions and new work been separated?

• Can both sides test the proposed result?

• Are the revised total, delivery date and dependencies clear?

• If the agreement changes, has the designated approver approved this exact version?

Keep that record with the project so the next request starts from the same agreement.

You can use this workflow in a shared document or explore Scopefolio free early access, with no card required.