@lenardangeloolajay/len-toolkit 1.1.0

package/src/installer.js

@@ -0,0 +1,236 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const TEMPLATES_DIR = path.join(PACKAGE_ROOT, 'templates');
+
+/**
+ * Ensures directory exists
+ */
+export function ensureDir(dirPath) {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  } catch (err) {
+    throw new Error(`Failed to create directory "${dirPath}": ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Recursively copies directory contents
+ */
+export function copyDir(src, dest, overwrite = false) {
+  try {
+    ensureDir(dest);
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath, overwrite);
+      } else {
+        if (!fs.existsSync(destPath) || overwrite) {
+          fs.copyFileSync(srcPath, destPath);
+        }
+      }
+    }
+  } catch (err) {
+    throw new Error(`Failed to copy directory from "${src}" to "${dest}": ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Safely copies a single file
+ */
+export function copyFile(src, dest, overwrite = false) {
+  try {
+    ensureDir(path.dirname(dest));
+    if (!fs.existsSync(dest) || overwrite) {
+      fs.copyFileSync(src, dest);
+      return true;
+    }
+    return false;
+  } catch (err) {
+    throw new Error(`Failed to copy file from "${src}" to "${dest}": ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Installs skills into target directory
+ * Destination will be: targetDir/.agents/skills/ (or targetDir directly if global)
+ */
+export function installSkills(targetDir, isGlobal = false, overwrite = false) {
+  const srcSkillsDir = path.join(TEMPLATES_DIR, 'skills');
+  const destDir = isGlobal
+    ? path.join(os.homedir(), '.gemini', 'config', 'skills')
+    : path.join(targetDir, '.agents', 'skills');
+
+  copyDir(srcSkillsDir, destDir, overwrite);
+  if (!isGlobal) {
+    copyDir(path.join(TEMPLATES_DIR, 'docs'), path.join(targetDir, '.agents', 'templates', 'docs'), overwrite);
+  }
+  return destDir;
+}
+
+function templateFiles(source, destination) {
+  return fs.readdirSync(source, { withFileTypes: true }).flatMap((entry) => {
+    const src = path.join(source, entry.name);
+    const dest = path.join(destination, entry.name);
+    return entry.isDirectory() ? templateFiles(src, dest) : [{ src, dest }];
+  });
+}
+
+/** Prepare local instructions without replacing user files or approving work. */
+export function startWorkspace(targetDir) {
+  const root = path.resolve(targetDir);
+  const git = (...args) => execFileSync('git', args, {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, LC_ALL: 'C' },
+  }).trim();
+  try {
+    git('--version');
+  } catch (err) {
+    throw new Error('Git is unavailable. Install Git and ensure it is on PATH, then rerun start.', { cause: err });
+  }
+
+  let initialized = false;
+  try {
+    if (git('rev-parse', '--is-inside-work-tree') !== 'true') {
+      throw new Error('Run start in a working tree, not a bare repository or Git metadata directory.');
+    }
+  } catch (err) {
+    // Do not initialize over a broken or untrusted repository.
+    if (!String(err.stderr).includes('not a git repository')) throw err;
+    for (let directory = root; ; directory = path.dirname(directory)) {
+      if (fs.lstatSync(path.join(directory, '.git'), { throwIfNoEntry: false })) {
+        throw new Error(`Existing Git metadata at "${directory}" is not usable. Repair it before rerunning start.`, { cause: err });
+      }
+      if (directory === path.dirname(directory)) break;
+    }
+    git('init');
+    initialized = true;
+  }
+
+  const entries = [
+    ...['AGENTS.md', 'GEMINI.md'].map((file) => ({ src: path.join(TEMPLATES_DIR, 'rules', file), dest: path.join(root, file) })),
+    { src: path.join(TEMPLATES_DIR, 'rules', 'GEMINI.md'), dest: path.join(root, '.agents', 'rules', 'GEMINI.md') },
+    ...templateFiles(path.join(TEMPLATES_DIR, 'skills'), path.join(root, '.agents', 'skills')),
+    ...templateFiles(path.join(TEMPLATES_DIR, 'docs'), path.join(root, '.agents', 'templates', 'docs')),
+    { src: path.join(TEMPLATES_DIR, 'configs', '.editorconfig'), dest: path.join(root, '.editorconfig') },
+    { src: path.join(TEMPLATES_DIR, 'configs', 'sample.gitignore'), dest: path.join(root, '.gitignore') },
+  ];
+  // Refuse symlinks/junctions before copying anything, including links in parents.
+  for (const { dest } of entries) {
+    for (let current = dest; current !== root; current = path.dirname(current)) {
+      const stat = fs.lstatSync(current, { throwIfNoEntry: false });
+      if (stat?.isSymbolicLink() || (stat && (current === dest ? !stat.isFile() : !stat.isDirectory()))) {
+        throw new Error(`Cannot install through "${current}": expected an ordinary ${current === dest ? 'file' : 'directory'}. Review this path and rerun start.`);
+      }
+    }
+  }
+
+  const installed = [];
+  const differences = [];
+  for (const { src, dest } of entries) {
+    if (copyFile(src, dest)) installed.push(path.relative(root, dest));
+    else if (fs.readFileSync(src, 'utf8').replace(/\r\n/g, '\n') !== fs.readFileSync(dest, 'utf8').replace(/\r\n/g, '\n')) {
+      differences.push({ path: path.relative(root, dest), proposed: src });
+    }
+  }
+
+  const identityWarnings = [];
+  for (const identity of ['GIT_AUTHOR_IDENT', 'GIT_COMMITTER_IDENT']) {
+    try { git('var', identity); }
+    catch { identityWarnings.push(`${identity} is unavailable. Configure your Git name/email before phase commits.`); }
+  }
+  return {
+    initialized,
+    repository: git('rev-parse', '--show-toplevel'),
+    branch: git('branch', '--show-current') || '(detached HEAD)',
+    changes: git('status', '--short'),
+    installed, differences, identityWarnings,
+    documents: ['docs/SPEC_INDEX.md', 'HANDOFF.md', 'IMPLEMENTATION_PLAN.md'].map((file) => ({
+      path: file, exists: fs.statSync(path.join(root, file), { throwIfNoEntry: false })?.isFile() === true,
+    })),
+  };
+}
+
+/**
+ * Installs project agent rules (GEMINI.md, AGENTS.md, .cursorrules)
+ */
+export function installRules(targetDir, overwrite = false) {
+  const srcRulesDir = path.join(TEMPLATES_DIR, 'rules');
+  const installed = [];
+
+  const files = ['GEMINI.md', 'AGENTS.md', '.cursorrules'];
+  for (const file of files) {
+    const src = path.join(srcRulesDir, file);
+    const dest = path.join(targetDir, file);
+    if (copyFile(src, dest, overwrite)) {
+      installed.push(file);
+    }
+  }
+
+  // Also copy GEMINI.md into .agents/rules/ if .agents directory exists
+  const agentsDir = path.join(targetDir, '.agents');
+  if (fs.existsSync(agentsDir)) {
+    const agentsRulesDir = path.join(agentsDir, 'rules');
+    ensureDir(agentsRulesDir);
+    copyFile(path.join(srcRulesDir, 'GEMINI.md'), path.join(agentsRulesDir, 'GEMINI.md'), overwrite);
+  }
+
+  return installed;
+}
+
+/**
+ * Installs standard dev configs (.editorconfig, .gitignore if not present)
+ */
+export function installConfigs(targetDir, overwrite = false) {
+  const installed = [];
+  const srcConfigsDir = path.join(TEMPLATES_DIR, 'configs');
+
+  // .editorconfig
+  const editorConfigSrc = path.join(srcConfigsDir, '.editorconfig');
+  const editorConfigDest = path.join(targetDir, '.editorconfig');
+  if (copyFile(editorConfigSrc, editorConfigDest, overwrite)) {
+    installed.push('.editorconfig');
+  }
+
+  // .gitignore
+  const gitignoreSrc = path.join(srcConfigsDir, 'sample.gitignore');
+  const gitignoreDest = path.join(targetDir, '.gitignore');
+  if (copyFile(gitignoreSrc, gitignoreDest, overwrite)) {
+    installed.push('.gitignore');
+  }
+
+  return installed;
+}
+
+/**
+ * Generates a starter IMPLEMENTATION_PLAN.md in target directory
+ */
+export function createPlanTemplate(targetDir, featureName = 'New Feature', overwrite = false) {
+  try {
+    const planPath = path.join(targetDir, 'IMPLEMENTATION_PLAN.md');
+    if (fs.existsSync(planPath) && !overwrite) {
+      return { created: false, path: planPath };
+    }
+
+    const timestamp = new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString().replace('Z', '+08:00');
+    const content = fs.readFileSync(path.join(TEMPLATES_DIR, 'docs', 'IMPLEMENTATION_PLAN.md'), 'utf8')
+      .replaceAll('{{TIMESTAMP}}', timestamp)
+      .replaceAll('{{FEATURE_NAME}}', () => featureName);
+    fs.writeFileSync(planPath, content, 'utf-8');
+    return { created: true, path: planPath };
+  } catch (err) {
+    throw new Error(`Failed to create plan template at "${targetDir}": ${err.message}`, { cause: err });
+  }
+}

package/templates/configs/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/configs/sample.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+build/
+.env
+.env.local
+*.log
+.DS_Store
+Thumbs.db

package/templates/docs/FEATURE.md

@@ -0,0 +1,40 @@
+# FEAT-[NNN]: [Feature name]
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+Revision: 1
+Status: Draft
+
+## Purpose and success
+
+[Who needs it, why, and the observable outcome.]
+
+## Scope and non-goals
+
+[What this version includes and excludes.]
+
+## User flows
+
+[Main flow and relevant loading, empty, offline, error, denied-permission, and recovery states.]
+
+## Requirements and acceptance criteria
+
+| ID | Required behavior | Observable pass/fail criterion |
+| --- | --- | --- |
+| REQ-001 | [Behavior] | [Specific scenario and expected result] |
+
+## Data and interfaces
+
+[Link shared data definitions; add only feature-specific differences.]
+
+## Quality constraints
+
+[Link shared constraints; define relevant measurable feature requirements.]
+
+## Decisions and assumptions
+
+[Separate confirmed requirements, observed facts, proposed decisions, and assumptions.]
+
+## Open questions and readiness
+
+[Blocking questions and actual chat approval of this revision when available.]

package/templates/docs/HANDOFF.md

@@ -0,0 +1,39 @@
+# Current handoff
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+State: Awaiting approval
+Feature: [ID]
+
+## Read first
+
+[Relative links to project rules, index, approved baseline, architecture, feature, and plan.]
+Reread these files and inspect actual Git status before acting; prior chat memory is not authoritative.
+
+## Approval and allowed work
+
+| Document | Approved revision or commit | Actual Len chat approval reference |
+| --- | --- | --- |
+
+Allowed phases: None until approval is recorded.
+Architecture and behavior changes return to Len; this handoff cannot override the linked specs.
+
+## Progress and working tree
+
+[Current phase, completed and unfinished work, checkpoint messages or verified hashes, and unrelated edits to preserve.]
+Reconcile this record with Git before resuming, especially after an interrupted commit.
+
+## Checks and evidence
+
+[Actual checks run, results, environments, evidence links, and checks not run.]
+
+## Blockers and attempts
+
+| Problem | Fix-and-check attempts used (maximum 3) | Changes tried and observed result | Required decision or access |
+| --- | --- | --- | --- |
+
+Do not reset a count on a new session or silently reinterpret a failed check as passing.
+
+## Next action
+
+[One concrete next action within approved scope, or the decision needed to unblock it.]

package/templates/docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,47 @@
+# Implementation Plan: {{FEATURE_NAME}}
+
+Created: {{TIMESTAMP}}
+Updated: {{TIMESTAMP}}
+Revision: 1
+Status: Awaiting approval
+Feature spec and revision: [Unresolved]
+Approved baseline and architecture revisions: [Unresolved]
+Len's chat approval: Not recorded
+Target branch: [Verify in this repository]
+
+## Scope
+
+[Link approved requirement IDs; identify existing edits to preserve.]
+Resolve the fields and exact checks before presenting this plan for approval.
+Use as many phases as the work needs; one phase is sufficient for a small feature.
+
+## Phase 1: [Testable outcome]
+
+Requirements: [FEAT-NNN/REQ-NNN]
+State: Awaiting approval
+
+### Tasks
+
+- [ ] [Specific work within the approved architecture.]
+
+### Verification
+
+- [ ] [Exact command or reproducible scenario, expected result, and environment.]
+- [ ] [Evidence path containing actual results and limitations.]
+
+### Review and checkpoint
+
+- [ ] Review correctness, scope, dependencies, and unrelated changes.
+- [ ] Update plan, evidence, and current handoff.
+- [ ] Stage only reviewed phase-related paths and verify the staged diff.
+- [ ] Commit with a unique phase message and verify Git reports success.
+
+Checkpoint message: [Choose a conventional commit message for this phase]
+Phase completion requires all gates and a successful commit; the message identifies the checkpoint without needing its own hash inside the commit.
+Continue automatically to the next approved phase.
+
+## Recovery
+
+Follow project `AGENTS.md` for the three-attempt limit and immediate blockers.
+Record unresolved work and attempt counts in the current handoff.
+Interrupted or failing work remains uncommitted and the phase remains incomplete.

package/templates/docs/SPEC_INDEX.md

@@ -0,0 +1,12 @@
+# Specification index
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+
+| Category | ID | Current path | Revision | Status | Replaces |
+| --- | --- | --- | --- | --- | --- |
+
+Add only existing documents, using relative links.
+Use `product/`, `features/`, `plans/`, `evidence/`, and `archive/` as needed.
+Link the single root `HANDOFF.md` and identify the current implementation plan.
+Update overlapping specs rather than creating dated duplicates.

package/templates/docs/VERIFICATION.md

@@ -0,0 +1,14 @@
+# Verification: FEAT-[NNN]
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+
+| Requirement / phase | Check or scenario | Environment and conditions | Actual result | When run | Evidence / limitations |
+| --- | --- | --- | --- | --- | --- |
+
+Use Not run, Passed under stated conditions, Failed, or Blocked.
+Record actual commands or repeatable scenarios, not just conclusions.
+Attach screenshots for meaningful UI checks when capture is available.
+Keep emulator, physical-device, hardware-bench, and field validation distinct.
+Len performs physical-device checks; keep them pending until Len supplies results.
+Neither implementation nor a simulation establishes effectiveness in the intended environment.

package/templates/docs/product/ARCHITECTURE.md

@@ -0,0 +1,22 @@
+# Architecture: [Name]
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+Revision: 1
+Status: Draft
+
+## Observed facts and assumptions
+
+[Verified project reality versus unverified assumptions.]
+
+## Components, boundaries, and flows
+
+[Responsibilities, data flow, trust boundaries, and external dependencies.]
+
+## Decisions and trade-offs
+
+[Chosen architecture, alternatives considered, failure modes, and reasons.]
+
+## Open questions and approval
+
+[Blocking decisions and actual Len approval reference when available.]

package/templates/docs/product/CONSTRAINTS.md

@@ -0,0 +1,22 @@
+# Shared constraints: [Name]
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+Revision: 1
+Status: Draft
+
+## Platform and environment
+
+[Supported platforms, connectivity, hardware, and deployment conditions.]
+
+## Quality and boundaries
+
+[Relevant accessibility, security, privacy, reliability, and measurable performance requirements.]
+
+## Evidence required
+
+[Required checks and their limits; separate emulator, physical device, hardware bench, and field validation.]
+
+## Open questions and approval
+
+[Untested targets, blocking questions, and actual approval reference when available.]

package/templates/docs/product/DATA_MODEL.md

@@ -0,0 +1,22 @@
+# Shared data model: [Name]
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+Revision: 1
+Status: Draft
+
+## Entities and ownership
+
+[Fields, types, relationships, source of truth, and lifecycle.]
+
+## Interfaces and validation
+
+[Inputs, outputs, validation boundaries, permissions, and error behavior.]
+
+## Storage and recovery
+
+[Relevant offline behavior, persistence, retention, migrations, and recovery.]
+
+## Open questions and approval
+
+[Unresolved assumptions and actual approval reference when available.]

package/templates/docs/product/OVERVIEW.md

@@ -0,0 +1,22 @@
+# Product overview: [Name]
+
+Created: [ISO 8601 timestamp +08:00]
+Updated: [ISO 8601 timestamp +08:00]
+Revision: 1
+Status: Draft
+
+## Purpose and users
+
+[Problem, users, real scenarios, and observable success.]
+
+## Planned capabilities and main flows
+
+[Inventory all planned features and their relationships before detailing individual features.]
+
+## Scope and non-goals
+
+[Release boundaries and exclusions.]
+
+## Open questions and approval
+
+[Blocking decisions, proposed defaults, and actual Len approval reference when available.]

package/templates/examples/flutter-handoff/EXERCISES.md

@@ -0,0 +1,16 @@
+# Workflow inspection exercises
+
+This is a fictional documentation fixture, not a working Flutter app.
+Use its [index](docs/SPEC_INDEX.md) to inspect the complete handoff chain.
+The situations below are hypothetical inspection prompts, not evidence that an agent executed them.
+
+| Situation | Expected decision |
+| --- | --- |
+| Tomorrow Len clarifies the note length requirement | Revise FEAT-001, its affected criteria and plan, and timestamps; do not create a new daily spec. |
+| Len replaces local note creation with a different capability | Preserve the superseded spec in `docs/archive/`, link its replacement, update the index and incoming references, and obtain approval for new scope. |
+| Gemini resumes with no earlier chat | Read the handoff and authorities, inspect Git, and stop because the example has no actual approval. |
+| An approved phase was interrupted after edits but before tests | Reconcile the diff, preserve the edits, run remaining approved checks, and leave the phase incomplete until its commit succeeds. |
+| The same failure survives three corrections and checks | Record all attempts, remaining edits, affected requirements, and needed decision; stop affected work. |
+| Gemini prefers a new storage library | Report the preference, continue the approved design if feasible, and do not introduce the library. |
+| The actual storage API cannot persist records | Report an architecture blocker immediately rather than fake persistence or silently change the design. |
+| An emulator scenario passes | Record the emulator configuration and actual result; physical-device verification is still pending. |

package/templates/examples/flutter-handoff/HANDOFF.md

@@ -0,0 +1,32 @@
+# Current handoff: Pocket Notes example
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+State: Awaiting approval
+Feature: FEAT-001
+
+## Read first
+
+In a real target repository, read its project-root AGENTS.md first.
+Then read [the index](docs/SPEC_INDEX.md), its four product documents, [the feature](docs/features/FEAT-001-local-note.md), [the plan](docs/plans/FEAT-001-implementation.md), and [the evidence](docs/evidence/FEAT-001-verification.md).
+
+## Approval and scope
+
+No real approval exists for this fictional example.
+All baseline, architecture, feature, and plan documents are revision 1 drafts.
+Allowed phases: None.
+Do not implement or infer approval from this example.
+
+## Progress and checks
+
+No Flutter code was written, no checks were run, and no phase commit exists.
+Working-tree state must be inspected in the actual target repository rather than copied from this example.
+
+## Blockers and attempts
+
+The real storage API, Android support, branch, and commands must be established before approval.
+Fix-and-check attempts: 0; no implementation has begun.
+
+## Next action
+
+GPT should inspect the real project, resolve those baseline questions with Len, and present the completed baseline, feature, and plan for chat approval.

package/templates/examples/flutter-handoff/docs/SPEC_INDEX.md

@@ -0,0 +1,19 @@
+# Pocket Notes example index
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+Status: Fictional draft example, not approved for execution
+
+| Category | Current document | Revision / status |
+| --- | --- | --- |
+| Product | [Overview](product/OVERVIEW.md) | 1 / Draft |
+| Architecture | [Architecture](product/ARCHITECTURE.md) | 1 / Draft |
+| Data | [Data model](product/DATA_MODEL.md) | 1 / Draft |
+| Constraints | [Constraints](product/CONSTRAINTS.md) | 1 / Draft |
+| Feature | [FEAT-001 local note creation](features/FEAT-001-local-note.md) | 1 / Draft |
+| Plan | [FEAT-001 implementation](plans/FEAT-001-implementation.md) | 1 / Awaiting approval |
+| Evidence | [FEAT-001 verification](evidence/FEAT-001-verification.md) | Not run |
+| Handoff | [Current handoff](../HANDOFF.md) | Awaiting approval |
+
+Refinements to local note creation belong in FEAT-001, not a new dated spec.
+No archive exists because no document has been superseded.

package/templates/examples/flutter-handoff/docs/evidence/FEAT-001-verification.md

@@ -0,0 +1,14 @@
+# FEAT-001 verification example
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+
+| Requirement | Check | Environment | Actual result | When run | Limitation |
+| --- | --- | --- | --- | --- | --- |
+| REQ-001 | Empty and oversized input | Not selected | Not run | Never | No Flutter implementation |
+| REQ-002 | Repeated Save while pending | Not selected | Not run | Never | No implementation |
+| REQ-003 | Controlled storage failure and retry | Not selected | Not run | Never | Storage API not inspected |
+| REQ-004 | Save offline, restart, inspect list | Android emulator not selected | Not run | Never | No emulator session |
+| All | Physical-device follow-up | Len's device | Not run | Never | Pending Len's actual results |
+
+No passing result, screenshot, hardware result, or field result is asserted.

package/templates/examples/flutter-handoff/docs/features/FEAT-001-local-note.md

@@ -0,0 +1,40 @@
+# FEAT-001: Create a local note
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+Revision: 1
+Status: Draft example
+
+## Purpose and success
+
+Capture a short note offline and find it when reopening the app.
+
+## Scope and non-goals
+
+Includes creation and newest-first listing.
+Deletion, editing an existing note, search, and sharing are outside this feature.
+
+## User flow
+
+The empty list invites the user to enter a note.
+Save validates the text, indicates a pending write, and adds the saved result to the list only after success.
+An error leaves the draft visible with a retry action.
+
+## Requirements
+
+| ID | Behavior | Acceptance criterion |
+| --- | --- | --- |
+| REQ-001 | Validate text | Whitespace-only text and more than 200 Unicode scalar values show an error and create no record; valid trimmed text can be saved. |
+| REQ-002 | Prevent duplicate writes | Repeated Save taps while the same write is pending create at most one note. |
+| REQ-003 | Preserve failed drafts | A failed write leaves the entered text intact, shows an accessible error, and permits retry. |
+| REQ-004 | Persist offline | With connectivity disabled, a successful save appears first in the list and is still present after restarting the app. |
+
+## Data and quality
+
+Use the shared [data model](../product/DATA_MODEL.md), [architecture](../product/ARCHITECTURE.md), and [constraints](../product/CONSTRAINTS.md).
+
+## Decisions and readiness
+
+The storage API and Android support remain unverified assumptions.
+Resolve these before Len approves this feature and its [plan](../plans/FEAT-001-implementation.md).
+No implementation tasks or test results are implied by this specification.