picagear 0.1.0-next.0

package/LICENSE

@@ -0,0 +1,59 @@
+# PolyForm Strict License 1.0.0
+
+<https://polyformproject.org/licenses/strict/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose, other than distributing the software or making changes or new works based on the software.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,171 @@
+# Picagear
+
+A local code factory for one developer and one repository.
+
+Picagear takes a large epic, proposes a capacity-safe weekly commitment, asks for one approval, compiles each approved task into a strict work order, and then runs one task per pull request through Codex and Claude Code in isolated git worktrees. It verifies fresh artifacts and declared gates itself instead of trusting a worker's exit status, retries once in a fresh worktree when a run produces nothing, and blocks with evidence when that fails. A terminal dashboard shows the line as an assembly line.
+
+Picagear runs locally, requires no Picagear service to receive repository content, and sends work only through the coding providers the user has configured. It is not a chat application, a hosted development environment, or a project manager.
+
+## Status
+
+Picagear `0.1.0-next.0` is a preview published to npm under the `next` tag. It is a functional foreground command line tool. It never merges a pull request and it never deletes a worktree. A full lifecycle system integration run against the installed package and live task performance with real providers are not yet proven.
+
+### Install and initialize
+
+Picagear requires Node 22.13 or later, Git, and the provider CLIs you enable. Install the preview as a development dependency of a private consumer project with package scripts disabled, then run the installed bin. A source checkout does not link its own bin, so this path does not exist there.
+
+```sh
+cd <consumer-directory>
+npm init --yes
+npm pkg set private=true --json
+npm install --save-dev --ignore-scripts picagear@next
+./node_modules/.bin/picagear --help
+./node_modules/.bin/picagear init --repo <path> --adapters codex,claude
+```
+
+A reviewed local archive remains a supported alternative. The [installation guide](docs/local-installation.md) covers both paths. Decadra advisory integration is optional and installed separately from a reviewed local archive. The Decadra package currently published on npm does not provide that integration.
+
+Factory data lives under `PICAGEAR_HOME`. The default is `~/.picagear`. The global `--home <dir>` option takes precedence over the environment variable.
+
+Commands select the factory for the Git repository containing the current directory. Use the global `--factory <id>` option to select one explicitly. Outside a repository, Picagear refuses an ambiguous home containing more than one factory and lists the available identifiers.
+
+Set `PICAGEAR_ADAPTERS=fake` before running commands for a quota-free pilot. This keeps Git real but replaces provider execution, pull request creation, and Decadra with deterministic fakes. With no `PICAGEAR_FAKE_SCRIPT`, fake execution produces no artifact, which exercises the retry and block path.
+
+### Add an epic
+
+Save an epic request as `epic.json`. Each backlog entry becomes a task brief at intake.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "epic-config-validation",
+  "title": "Validate project configuration",
+  "objective": "Reject invalid project configuration with clear local diagnostics.",
+  "constraints": ["Keep configuration parsing offline."],
+  "horizonDays": 7,
+  "backlog": [
+    {
+      "id": "validate-config",
+      "title": "Add configuration validation",
+      "outcome": "Create a bounded configuration validator and tests for missing required fields.",
+      "category": "build",
+      "tier": "standard",
+      "priority": 80,
+      "dependsOn": [],
+      "allowedPaths": ["src/app", "test"],
+      "prohibitedPaths": ["src/adapters"],
+      "expectedArtifacts": [
+        { "path": "src/app/config.ts", "kind": "created", "required": true },
+        { "path": "test/config.test.ts", "kind": "created", "required": true }
+      ],
+      "gates": ["test"],
+      "verification": [["npm", "test", "--", "test/config.test.ts"]],
+      "completionEvidence": ["Invalid configuration is rejected and the focused test passes."],
+      "contextRefs": ["src/app"],
+      "estimatedMinutes": 120,
+      "reviewBurden": 1,
+      "ambiguity": 0,
+      "blastRadius": 0,
+      "reversibility": 2,
+      "gateStrength": 2,
+      "interpretation": "strict",
+      "requestedTools": ["read", "edit", "write", "grep"],
+      "requestedPermissions": ["read", "edit", "write", "run-gates"],
+      "needsBrowser": false,
+      "needsVisual": false
+    }
+  ],
+  "references": ["README.md"],
+  "completionDefinition": "The validator is independently verified and ready for review."
+}
+```
+
+```sh
+picagear epic add epic.json
+```
+
+A supplied backlog is normalized as written. An epic with an empty backlog is decomposed by objective sentences into at most eight reviewable implementation slices. Each slice is bounded to one charter allowed root and the mandatory charter gates. Intake only proposes briefs. It cannot execute before plan approval. Epic constraints are copied into every normalized brief and compiled work order.
+
+### Plan and approve once
+
+`plan` proposes a capacity-safe weekly subset. Capacity allowances are attempt counts kept separately for each adapter. Provider-native units are never converted or summed. Inspect the proposal before giving the single approval that creates the active commitment. Approval binds the hash of every included brief.
+
+```sh
+picagear plan
+picagear plan show
+picagear plan approve
+```
+
+Use `picagear plan approve --remove <task-id>` to remove a task before approval. Use `--plan <id>` to approve a specific proposal.
+
+### Compile and run
+
+The first scheduling tick compiles committed briefs into strict work orders pinned to the current base revision. A dependent brief waits until each prerequisite is complete and integrated, then compiles against a base that contains those revisions. Later ticks dispatch, verify, retry, or block work. A tick that dispatches an attempt waits for that attempt to finish because Picagear has no daemon. Both `tick` and `run` hold the coordinator lock, so a competing tick exits with status 4.
+
+```sh
+picagear tick
+picagear tick
+picagear tick
+```
+
+Use the foreground supervisor when you want repeated ticks.
+
+```sh
+picagear run
+```
+
+`picagear run --max-ticks 10` bounds a foreground run. In another terminal, watch the event log projection.
+
+```sh
+picagear dashboard --watch 5
+picagear inspect validate-config
+picagear work-order show validate-config
+```
+
+After Picagear has independently verified an attempt, open its pull request and record the review decision. Pull request creation requires retained artifact observations for the exact attempt and order, a changed tree inside scope, the current work order hash, and a passed result for every mandatory gate and verification command. Picagear pushes the immutable verified revision and confirms the remote branch head. Existing pull requests for the attempt branch are reconciled before a new one is created.
+
+```sh
+picagear pr open validate-config
+picagear approve validate-config
+picagear archive validate-config
+```
+
+Use `picagear reject validate-config --reason "Tests need a narrower fixture"` instead of approval when review fails. Archiving is allowed only after completion.
+
+### Control and diagnose
+
+Pause prevents new dispatch while allowing verification to continue. Resume restores dispatch. Stop records cancellation requests for active attempts and keeps every worktree.
+
+```sh
+picagear pause --reason "Review queue is full"
+picagear resume
+picagear stop --reason "End the current run"
+picagear doctor
+```
+
+Use `picagear status` for a compact projection. Use `picagear retry <task>` only for a blocked task that is eligible for manual retry. A compile failure, worker mismatch, or rejected review can use a replacement brief. Save a complete corrected `TaskBriefV1` object with the same task and epic identifiers, then run the following commands. The replacement remains pending until its explicit approval, and a new plan approval is still required.
+
+```sh
+picagear brief replace validate-config corrected-brief.json
+picagear brief approve <proposal-id>
+picagear plan
+picagear plan approve
+```
+
+### Documentation
+
+Read the [architecture overview](docs/architecture/overview.md), [data file reference](docs/architecture/data-files.md), [compiler diagnostics](docs/architecture/compiler-diagnostics.md), [work order contract](docs/work-order-contract.md), [execution adapter reference](docs/execution-adapters.md), [privacy boundary](docs/privacy-and-data-boundary.md), [testing guide](docs/testing/README.md), [decisions](docs/decisions/README.md), and [delivery plan](docs/plans/2026-09-14-v1-vertical-slice.md).
+
+## Development
+
+```
+npm install
+npm run check
+node dist/cli.js doctor
+```
+
+Read `AGENTS.md` before changing code.
+
+## License
+
+Picagear is licensed under the [PolyForm Strict License 1.0.0](LICENSE). It permits use for noncommercial purposes as the license defines them. It does not grant rights to distribute the software or to make changes or new works based on it. Public availability on npm does not grant further rights. Read the license text for the full terms.