aiongside 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moseoh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# AIongside
+
+A local-first workspace where people and AI share everyday work context, Records, Overviews, and rules.
+
+The first goal is simple local work management. The second goal is a validation layer that turns damaged Records, missed updates, and inconsistent generated Views into mechanical failures.
+
+## Status
+
+- MVP CLI implemented.
+- Workspace initialization, work item creation, status movement, dependency management, cancellation, safe discard, and validation implemented.
+- Editable workspace templates implemented.
+- npm packaging and release validation implemented. The first npm release is pending.
+- TypeScript monorepo managed with Bun.
+- Shared Claude and Codex plugin source included.
+- Local Web UI reserved for the distant future.
+- TUI excluded from product scope.
+
+## Quick start
+
+After the first npm release, install AIongside with Node.js 22 or later:
+
+```sh
+npm install --global aiongside
+aiongside --help
+aiongside init ./example
+aiongside --root ./example check
+```
+
+The installed CLI runs on Node.js without requiring Bun. Node.js 22 and 24 are tested for every release candidate.
+
+To run from source before the first release:
+
+```sh
+bun install
+bun run build
+node packages/cli/dist/bin.js init ./example
+node packages/cli/dist/bin.js --root ./example work new "First Work"
+node packages/cli/dist/bin.js --root ./example check
+```
+
+## Templates
+
+`aiongside init` creates editable Markdown templates:
+
+```text
+.aiongside/templates/
+  record.md
+  overview.md
+  plan.md
+```
+
+Edit these files with any text editor. New work items use the current workspace templates. AIongside generates YAML frontmatter separately, so template customization cannot remove machine-owned metadata.
+
+`record.md` and `overview.md` must retain the `{{title}}` placeholder. `aiongside check` reports missing template files and invalid placeholders. Initialization never overwrites an existing template file.
+
+## Workspace files
+
+```text
+work/<ID>/
+  record.md
+  overview.md
+  plan.md              # Created when the work item moves to active
+  references/
+  deliverables/
+  evidence/
+views/
+  open.md
+  closed.md
+```
+
+`record.md` is the canonical work document. It owns status, progress, decisions, and outcomes. `overview.md` is the short human-readable entry point and does not duplicate dynamic state. `plan.md` is optional and is created when a work item moves to `active`.
+
+Each new work item includes three user-owned content directories:
+
+- `references/`: material received from outside the work, such as official documents, vendor replies, source files, and links.
+- `deliverables/`: outputs produced for delivery, such as reports, instructions, presentations, spreadsheets, and exports.
+- `evidence/`: results observed directly in the current environment, such as logs, query results, screenshots, measurements, and command output.
+
+AIongside requires these directories but does not constrain their file names, formats, or nested structure. Their contents are never rewritten automatically. File paths and exact bytes in all three directories are covered by the completion seal, so changing them while work remains `done` fails validation. Direct edits do not update Record metadata or generated Views.
+
+Older workspaces may contain `reports/` instead of `deliverables/` and may not contain `evidence/`. AIongside does not move or delete those files automatically. Review the existing content, move delivery outputs into a new `deliverables/` directory, and create `evidence/` before running further mutations.
+
+Views are generated from Record metadata and must not be edited directly. `aiongside check` compares each View with a deterministic rendering of current Records. Missing, stale, manually modified, or line-ending-converted Views fail validation without changing files. Run `aiongside view rebuild` for explicit recovery.
+
+## Work status
+
+AIongside uses five statuses:
+
+- `inbox`: captured but not currently being worked.
+- `active`: work, review, or verification that can proceed now.
+- `waiting`: no action can proceed until an external response or condition changes.
+- `done`: completion requirements were reviewed and sealed.
+- `cancelled`: intentionally stopped while retaining the Record.
+
+Every status can move to every other status. Preview a move before applying it:
+
+```sh
+aiongside work move AIO-001 waiting --dry-run --json
+aiongside work move AIO-001 waiting \
+  --waiting-reason "Waiting for approval" \
+  --resume-when "Approval is received"
+```
+
+The JSON preview lists stable `requiredInputs`, questions, CLI options, changes, and warnings. Transition answers are written to machine-owned Record frontmatter, not the customizable template body.
+
+Moving to `done` validates review signals stored in Record frontmatter. Confirm them after reviewing the corresponding Record content:
+
+```sh
+aiongside work confirm AIO-001 scope completion
+aiongside work confirm AIO-001 verification
+aiongside work confirm AIO-001 outcome knowledge
+```
+
+- Only `done` requires `scope`, `completion`, `verification`, `outcome`, and `knowledge`.
+- Only `done` requires every ID in `needs` to be `done`.
+- Leaving `done` requires `--reopen-reason` or `--cancellation-reason`, invalidates the completion seal, and resets verification, outcome, and knowledge confirmations.
+- Changing completion-relevant content while the status remains `done` fails `aiongside check`.
+
+`needs` contains stable work item IDs in Record frontmatter. Manage it through the CLI instead of editing frontmatter directly:
+
+```sh
+aiongside work needs add AIO-002 AIO-001
+aiongside work needs remove AIO-002 AIO-001
+```
+
+Adding a dependency rejects missing, duplicate, self-referencing, and cyclic relationships. Removing an absent relationship succeeds without changing files. Reopen `done` work before changing its dependencies. Confirmations are mechanical review signals; they do not prove that prose is true or complete.
+
+## Commands
+
+```text
+aiongside init
+aiongside work new <title>
+aiongside work confirm <id> <checks...>
+aiongside work move <id> <status> --dry-run --json
+aiongside work move <id> <status> [transition options]
+aiongside work needs add <id> <dependency-id>
+aiongside work needs remove <id> <dependency-id>
+aiongside work cancel <id> --cancellation-reason <text>
+aiongside work discard <id> --dry-run
+aiongside view rebuild
+aiongside check
+```
+
+## Development
+
+```sh
+bun run check
+bun run package:check
+```
+
+Node.js 22 and 24 are supported. Development uses Node.js 24.
+
+Publishing requires an npm owner for `aiongside` and an npm Trusted Publisher restricted to `moseoh/aiongside` and `.github/workflows/publish.yml`. A published GitHub Release must use a tag that exactly matches `v<package-version>`. The release workflow rejects version mismatches, existing npm versions, package validation failures, and Node.js 22 or 24 smoke-test failures before publishing.
+
+## License
+
+[MIT](LICENSE)