Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan

deepworkplan

Verified

DeepWorkPlan — turn any repo AI-first and run Deep Work Plans. Routes to create, execute, refine, resume, status, verify, upgrade, and repo-onboarding sub-skills based on intent. Use when the developer wants to plan, execute, manage, or verify structured multi-task work, or make a repository AI-agent-ready.

FileKindSize
SKILL.mdskill md12.0 KB
TRUST.mdmarkdown16.1 KB
addons/README.mdmarkdown11.7 KB
addons/machine-installs.mdmarkdown2.9 KB
examples/CREATE_PLAN.mdmarkdown6.9 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_create_child_dwp.mdmarkdown15.0 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.mdmarkdown16.7 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_integration_checkpoint.mdmarkdown9.0 KB
examples/PROMPTS_TEMPLATE.mdmarkdown4.0 KB
examples/TEAM_AGENTS_TASK_TEMPLATE.mdmarkdown5.1 KB
examples/V6_PLAN_EXAMPLE.mdmarkdown5.5 KB
guide/GUIDE.mdmarkdown8.0 KB
guide/authoring.mdmarkdown28.5 KB
guide/execution.mdmarkdown21.0 KB
guide/large-repo-onboarding.mdmarkdown3.3 KB
guide/orchestration-at-scale.mdmarkdown11.4 KB
guide/orchestrator.mdmarkdown37.9 KB
guide/prompts.mdmarkdown10.1 KB
guide/skills-integration.mdmarkdown6.5 KB
guide/structure.mdmarkdown6.2 KB
guide/swarm.mdmarkdown21.2 KB
guide/team-agents.mdmarkdown12.3 KB
shared/adaptation.mdmarkdown2.7 KB
shared/addon_sync.pyscript17.7 KB
shared/benchmark.pyscript97.6 KB
shared/config.pyscript41.5 KB
shared/context.shscript4.2 KB
shared/context_manifest.pyscript40.8 KB
shared/contract_v6.pyscript82.7 KB
shared/delegators.pyscript3.0 KB
shared/dwp-paths.mdmarkdown5.8 KB
shared/finalize_plan.pyscript7.2 KB
shared/install-verification.mdmarkdown1.8 KB
shared/ledger.pyscript141.5 KB
shared/migrate_v6.pyscript46.5 KB
shared/outcomes.pyscript27.2 KB
shared/plan_paths.pyscript4.8 KB
shared/resources.pyscript49.0 KB
shared/scheduler.pyscript41.6 KB
shared/state_contract.pyscript9.8 KB
shared/swarm.pyscript27.3 KB
shared/troubleshooting.mdmarkdown7.4 KB
shared/update-state.pyscript12.5 KB
shared/views.pyscript21.0 KB
shared/working-principles.mdmarkdown7.1 KB
spec/ADDONS.mdmarkdown27.4 KB
spec/AGENT_PROTOCOL.mdmarkdown28.0 KB
spec/ARCHETYPES.mdmarkdown10.6 KB
spec/BENCHMARK.mdmarkdown20.3 KB
spec/CONFIG.mdmarkdown8.7 KB
spec/DOCUMENTATION_STANDARD.mdmarkdown40.7 KB
spec/DWP_SPECIFICATION.mdmarkdown65.1 KB
spec/LITE_PLANS.mdmarkdown4.0 KB
spec/PLAN_STATE.mdmarkdown34.9 KB
spec/README.mdmarkdown11.5 KB
spec/V6_CONTEXT.mdmarkdown6.4 KB
spec/V6_CONTRACT.mdmarkdown12.3 KB
spec/V6_LIFECYCLE.mdmarkdown13.5 KB
spec/V6_RESOURCES.mdmarkdown4.7 KB
spec/V7_ABILITIES.mdmarkdown4.9 KB
spec/V7_CONTRACT.mdmarkdown6.4 KB
spec/V7_ROADMAP.mdmarkdown4.6 KB
spec/schema/addon-descriptor-v1.schema.jsonconfig5.5 KB
spec/schema/benchmark-record.schema.jsonconfig14.0 KB
spec/schema/context-manifest-v6.schema.jsonconfig12.5 KB
spec/schema/dwp-config-v1.schema.jsonconfig3.5 KB
spec/schema/dwp-handoff-v1.schema.jsonconfig3.0 KB
spec/schema/journal-event-v6.schema.jsonconfig22.3 KB
spec/schema/journal-event-v7.schema.jsonconfig24.9 KB
spec/schema/learnings-record.schema.jsonconfig6.0 KB
spec/schema/plan-contract-v6.schema.jsonconfig16.4 KB
spec/schema/plan-contract-v7.schema.jsonconfig16.6 KB
spec/schema/plan-manifest-v2.schema.jsonconfig1.0 KB
spec/schema/plan-manifest-v5.schema.jsonconfig1.3 KB
spec/schema/plan-manifest-v6.schema.jsonconfig2.0 KB
spec/schema/plan-manifest-v7.schema.jsonconfig1.7 KB
spec/schema/plan-manifest.schema.jsonconfig1.8 KB
spec/schema/plan-snapshot-v6.schema.jsonconfig7.8 KB
spec/schema/plan-state-v2.schema.jsonconfig6.4 KB
spec/schema/plan-state-v5.schema.jsonconfig6.7 KB
spec/schema/plan-state.schema.jsonconfig3.7 KB

shared/views.py

View on GitHub
#!/usr/bin/env python3
"""v6 deterministic generated views and the human-edit rule (RFC 4.4).

Generated views are explicit projections of journal + snapshot, written to
``views/<NAME>.md`` files that carry an identity header (view name,
contract_id, source snapshot digest and the snapshot's own updated_at).
Every header value derives from the rendered snapshot — never the wall
clock and never the render's own bookkeeping — so re-rendering unchanged
records is a byte-identical no-op by construction: a render appends its
``view_render`` provenance event ONLY when it actually wrote something.

The human-edit rule: a view file that differs from what render would
produce (its marker proves it was machine-rendered, so a difference means
a human edit) is NEVER silently overwritten. Render reports the divergence
and exits nonzero until the operator picks a reconciliation mode:

  * ``--reconcile human-wins``  — the human edit stays as the view; the
    generated output is written beside it as ``<name>.generated.md``;
  * ``--reconcile generated-wins`` — the generated view is written; the
    human edit is preserved as ``<name>.human.md``.

Both record a ``reconciliation`` event carrying the trigger, the editor
whose change won and the operator-supplied authority (D2-4: authority is
recorded content, not a mechanism label). Direct edits to README.md and
PROGRESS.md remain markdown-wins as in v5; under the journal a
reconciliation regenerates the snapshot and appends the event — the
journal never discards history.

Audit posture (U3/B1, D12): the audit view lists every refusal and
intervention with reasons and proposal pointers — labeled records of
recorded proposals, never aggregated into indices or ratings. A completion
profile (B4) shows, per criterion, the closing mechanism — the evidence
item with its trust label and pointer — or that it is open.

Python 3.9+ stdlib only; imports only its sibling modules.
"""
import argparse
import hashlib
import json
import os
import sys

sys.dont_write_bytecode = True  # never leave caches inside an installed pack

import contract_v6  # noqa: E402
import ledger  # noqa: E402

VIEWS = ('tasks', 'evidence', 'audit', 'completion')
MARKER = '<!-- dwp-view: %s | contract:%s | snapshot:%s | rendered-at:%s -->'


class ViewsError(Exception):
    """Operator-visible failure (exit 1)."""


class DivergenceError(ViewsError):
    """A human-edited generated view refuses silent overwrite (exit 5)."""


# The snapshot is stale when the journal holds STATE events beyond it
# (render provenance never counts — see ledger.PROVENANCE_TYPES).
STATE_TYPES = frozenset(contract_v6.JOURNAL_EVENT_TYPES) - \
    frozenset(ledger.PROVENANCE_TYPES)


def _snapshot(rec, writer):
    """Load state.json, re-projecting when state events outgrew it.

    A snapshot is reused as long as no state-bearing event has landed since
    it was projected (provenance events do not count), so consecutive
    renders of unchanged records share one snapshot and one digest.
    """
    if os.path.isfile(rec.state_path):
        with open(rec.state_path, encoding='utf-8') as fh:
            state = json.load(fh)
        projected = max([p.get('seq', 0) for p in
                         (state.get('positions') or {}).values()] or [0])
        live = max([e.get('seq', 0) for e in writer.events
                    if e.get('type') in STATE_TYPES] or [0])
        if live <= projected:
            return state
    return writer.project()


def render_view(name, events, snapshot, contract, digest):
    """Deterministic Markdown for one view (pure function of its inputs)."""
    lines = []
    if name == 'tasks':
        lines += ['# Task table', '',
                  '| Task | Title | Status | Started at |',
                  '|---|---|---|---|']
        for task in snapshot.get('tasks', []):
            lines.append('| %s | %s | %s | %s |' % (
                task['id'], _md(task.get('title')),
                task.get('status'), task.get('started_seq') or '—'))
        lines += ['', '_Pure projection of the snapshot; statuses are '
                  'derived, never narrated._']
    elif name == 'evidence':
        lines += ['# Evidence index', '',
                  '| Seq | Type | Trust | Subject | Exit | Pointer |',
                  '|---|---|---|---|---|---|']
        for event in events:
            if event.get('type') not in contract_v6.EVIDENCE_TYPES:
                continue
            subject = event.get('criterion') or event.get('limit_id') or ''
            lines.append('| %s | %s | %s | %s | %s | %s |' % (
                event.get('seq'), event.get('type'), event.get('trust', '—'),
                subject, event.get('exit_code', '—'),
                event.get('evidence_path', '—')))
        if len(lines) == 4:
            lines += ['| — | — | — | — | — | — |']
        lines += ['', '_Every evidence item with its trust label; a '
                  'checksum proves byte identity, not the truth of a '
                  'claim._']
    elif name == 'audit':
        lines += ['# Refusals and interventions', '']
        refusals = [e for e in events if e.get('type') == 'refusal']
        interventions = [e for e in events
                         if e.get('type') == 'intervention']
        lines += ['## Refusals (%d)' % len(refusals), '']
        for event in refusals:
            lines += ['- seq %s — %s at %s: %s' % (
                event.get('seq'), event.get('subject'),
                event.get('stage'), event.get('reason'))]
        if not refusals:
            lines += ['_No refusals recorded — this records that nothing '
                      'was proposed, not that nothing would have been '
                      'refused._']
        lines += ['', '## Interventions (%d)' % len(interventions), '']
        for event in interventions:
            lines += ['- seq %s — %s: %s — question: %s' % (
                event.get('seq'), event.get('category'),
                event.get('description'), event.get('question'))]
        if not interventions:
            lines += ['_No interventions recorded._']
    elif name == 'completion':
        lines += ['# Completion profile', '',
                  '| Task | Criterion | Satisfied | Mechanism | Pointer |',
                  '|---|---|---|---|---|']
        for task in snapshot.get('tasks', []):
            for crit in task.get('criteria', []):
                if crit.get('satisfied'):
                    mech = 'evidence (seq %s, trust %s)' % (
                        crit.get('via_seq'), crit.get('trust'))
                    pointer = crit.get('evidence_path') or '—'
                else:
                    mech = 'open'
                    pointer = '—'
                lines.append('| %s | %s | %s | %s | %s |' % (
                    task['id'], crit.get('criterion'),
                    'yes' if crit.get('satisfied') else 'no', mech, pointer))
        lines += ['', '_Per criterion: the closing mechanism — the '
                  'evidence item with its trust label — never a bare '
                  'claim (A4). Reconciled-authority closures are v6.0 '
                  'amendments until lifecycle wiring renders them '
                  'here._']
    else:
        raise ViewsError('unknown view %r' % name)
    return '\n'.join(lines) + '\n'


def render(plan_dir, names, out_dir=None, reconcile=None, authority=None,
           force=False):
    """Render views; enforce the human-edit rule; record view_render."""
    rec = ledger.PlanRecords(plan_dir)
    lock = ledger.CooperativeLock(plan_dir).acquire(force=force)
    try:
        writer = ledger.Writer(rec, lock)
        snapshot = _snapshot(rec, writer)
        digest = rec.snapshot_digest()
        if not digest:
            raise ViewsError('projection produced no snapshot to anchor a '
                             'view marker to')
        ts = snapshot.get('updated_at') or ''
        out_dir = out_dir or os.path.join(plan_dir, 'views')
        os.makedirs(out_dir, exist_ok=True)
        written = []
        digests = {}
        for name in names:
            body = render_view(name, writer.events, snapshot,
                               rec.contract, digest)
            header = MARKER % (name, rec.contract_id[:16], digest[:16], ts)
            content = header + '\n\n' + body
            digests[name] = hashlib.sha256(
                content.encode('utf-8')).hexdigest()
            target = os.path.join(out_dir, name + '.md')
            existing = None
            if os.path.isfile(target):
                with open(target, encoding='utf-8') as fh:
                    existing = fh.read()
                if existing == content:
                    continue  # unchanged records: an idempotent no-op
            if existing is not None and not _machine_written(
                    writer.events, name, existing):
                # N3: the bytes on disk are compared with the per-view
                # digest the last render recorded. A file that differs
                # from render output AND from that digest is human-edited
                # whether or not its marker survived — never a silent
                # overwrite. A file that still matches the recorded
                # digest is the untouched output of an earlier snapshot,
                # so refreshing it loses nothing.
                if reconcile is None:
                    raise DivergenceError(
                        '%s was human-edited after its last render; '
                        'refusing to overwrite silently — pass '
                        '--reconcile human-wins or generated-wins '
                        '(with --authority)' % target)
                if authority is None:
                    raise ViewsError('reconciliation requires --authority '
                                     '(recorded content, D2-4)')
                if reconcile == 'human-wins':
                    with open(target[:-3] + '.generated.md', 'w',
                              encoding='utf-8') as fh:
                        fh.write(content)
                    outcome = 'human edit kept; generated output beside it'
                    written.append('%s (reconciled: %s)' %
                                   (name, reconcile))
                else:
                    with open(target[:-3] + '.human.md', 'w',
                              encoding='utf-8') as fh:
                        fh.write(existing)
                    with open(target, 'w', encoding='utf-8') as fh:
                        fh.write(content)
                    outcome = 'generated view written; human edit preserved'
                    written.append('%s (reconciled: %s)' %
                                   (name, reconcile))
                _record_reconciliation(writer, name, authority, outcome)
                continue
            with open(target, 'w', encoding='utf-8') as fh:
                fh.write(content)
            written.append(name)
        if written:
            # provenance is recorded ONLY for a render that wrote — a
            # re-render of unchanged records appends nothing (and never
            # feeds back into the snapshot; see ledger.PROVENANCE_TYPES)
            writer.append('view_render',
                          {'view': '+'.join(w.split(' ')[0] for w in written),
                           'snapshot_digest': digest,
                           'digests': {n: digests[n] for n in
                                       [w.split(' ')[0] for w in written]}},
                          actor={'kind': 'helper',
                                 'identity': ledger.LEDGER_IDENTITY})
        return written
    finally:
        lock.release()


def _machine_written(events, name, existing):
    """N3: prove a marker-less view file is machine output.

    Every view_render event records a per-view digest of exactly what
    render wrote. A file whose bytes match ANY recorded digest for that
    view is machine output — the untouched result of an earlier render,
    possibly older than a later render to another ``--out`` directory —
    so refreshing it loses nothing. Anything else (or no recorded digest
    at all) is treated as an edit. Accepted trade-off: a deliberate
    restore of an exact earlier render is refreshed without a
    reconciliation record; its content stays reproducible from the journal.
    """
    actual = hashlib.sha256(existing.encode('utf-8')).hexdigest()
    return any(event.get('type') == 'view_render' and
               isinstance(event.get('digests'), dict) and
               event['digests'].get(name) == actual for event in events)


def _record_reconciliation(writer, name, authority, outcome):
    """Record reconciliation once per unchanged state (idempotent)."""
    for event in reversed(writer.events):
        if event.get('type') != 'reconciliation':
            continue
        if event.get('editor') == 'human edit of views/%s.md' % name and \
                event.get('authority') == authority and \
                event.get('note') == outcome:
            return  # already recorded for this exact state
        break
    writer.append('reconciliation',
                  {'trigger': 'generated-view divergence',
                   'editor': 'human edit of views/%s.md' % name,
                   'authority': authority},
                  # the helper's caller acts under the named authority;
                  # the record never claims a human actor it cannot prove
                  actor={'kind': 'agent', 'identity': authority},
                  note=outcome)


def _md(text):
    return str(text or '').replace('|', '\\|').replace('\n', ' ')


# ---------------------------------------------------------------- selftest

def self_test():
    import tempfile
    failures = []
    probes = [0]

    def check(label, ok, detail=''):
        probes[0] += 1
        if not ok:
            failures.append('%s%s' % (label,
                                      (': ' + detail) if detail else ''))

    with tempfile.TemporaryDirectory() as tmp:
        plan = os.path.join(tmp, 'PLAN_selftest_v6')
        os.makedirs(plan)
        contract = contract_v6._selftest_contract()
        cid = contract_v6.compute_contract_id(contract)
        with open(os.path.join(plan, 'contract.json'), 'w',
                  encoding='utf-8') as fh:
            json.dump(dict(contract, contract_id=cid), fh)
        lock = ledger.CooperativeLock(plan).acquire()
        writer = ledger.Writer(ledger.PlanRecords(plan), lock)
        writer.append('approval', {'authority': 'selftest',
                                   'mechanism': 'plan_authorship',
                                   'plan_digest': 'a' * 64},
                      actor={'kind': 'human', 'identity': 'selftest'},
                      idempotent=True)
        writer.append('task_start', {'task': 'T-implement'},
                      actor={'kind': 'agent', 'identity': 'selftest'},
                      idempotent=True)
        # observed evidence comes from the executor, never an append
        writer.run_gate('T-implement', 'true', criterion='AC-one')
        writer.project()
        lock.release()
        # 1. render is deterministic across two runs
        r1 = render(plan, ['tasks', 'audit'])
        with open(os.path.join(plan, 'views', 'tasks.md'),
                  encoding='utf-8') as fh:
            body1 = fh.read()
        r2 = render(plan, ['tasks', 'audit'])
        with open(os.path.join(plan, 'views', 'tasks.md'),
                  encoding='utf-8') as fh:
            body2 = fh.read()
        check('re-render of unchanged records is byte-identical',
              body1 == body2)
        check('re-render of unchanged records writes nothing (idempotent)',
              r2 == [], 'second render returned %r' % (r2,))
        rec0 = ledger.PlanRecords(plan)
        renders0 = [e for e in rec0.read_journal()[0]
                    if e.get('type') == 'view_render']
        check('one provenance event for the batch that wrote',
              len(renders0) == 1)
        # 2. human edit refuses silent overwrite
        target = os.path.join(plan, 'views', 'tasks.md')
        with open(target, 'a', encoding='utf-8') as fh:
            fh.write('\nHUMAN NOTE\n')
        try:
            render(plan, ['tasks'])
            check('human edit must refuse overwrite', False)
        except DivergenceError:
            check('human edit refuses overwrite', True)
        # 3. reconciliation modes preserve both copies + record the event
        render(plan, ['tasks'], reconcile='generated-wins',
               authority='selftest operator')
        check('human copy preserved',
              os.path.isfile(target[:-3] + '.human.md'))
        rec = ledger.PlanRecords(plan)
        events, _torn, _framing = rec.read_journal()
        reconciliations = [e for e in events
                           if e.get('type') == 'reconciliation']
        check('reconciliation recorded with authority',
              len(reconciliations) == 1 and
              reconciliations[0].get('authority') == 'selftest operator')
        # 4. a view rendered before new state events is stale but intact
        #    (its bytes still match the digest its render recorded): it
        #    refreshes in place with no divergence and no reconciliation
        #    event — only bytes no render produced count as a human edit
        audit_path = os.path.join(plan, 'views', 'audit.md')
        with open(audit_path, encoding='utf-8') as fh:
            stale_audit = fh.read()
        try:
            refreshed = render(plan, ['audit'])
            check('stale intact view refreshes without divergence',
                  refreshed == ['audit'], 'rendered %r' % (refreshed,))
        except DivergenceError as exc:
            check('stale intact view refreshes without divergence',
                  False, str(exc))
        with open(audit_path, encoding='utf-8') as fh:
            audit = fh.read()
        check('refresh replaced the stale snapshot marker',
              audit != stale_audit)
        check('audit states the empty-refusal meaning',
              'nothing was proposed' in audit)
        events, _torn, _framing = ledger.PlanRecords(plan).read_journal()
        check('refreshing an intact view records no reconciliation',
              len([e for e in events
                   if e.get('type') == 'reconciliation']) == 1)
        # 5. a marker-carrying view edited after its refresh still refuses:
        #    the edit makes the bytes differ from the recorded digest
        with open(audit_path, 'a', encoding='utf-8') as fh:
            fh.write('\nHUMAN NOTE\n')
        try:
            render(plan, ['audit'])
            check('edited marker-carrying view must refuse overwrite', False)
        except DivergenceError:
            check('edited marker-carrying view refuses overwrite', True)
    return (not failures, failures, probes[0])


# --------------------------------------------------------------------- CLI

def main(argv):
    usage = ('usage: views.py --plan DIR {render|self-test} '
             '[--view tasks,evidence,audit,completion|--all] [--out DIR] '
             '[--reconcile human-wins|generated-wins] [--authority WHO] '
             '[--force]')
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument('--plan')
    parser.add_argument('command')
    parser.add_argument('--view')
    parser.add_argument('--all', action='store_true')
    parser.add_argument('--out')
    parser.add_argument('--reconcile',
                        choices=['human-wins', 'generated-wins'])
    parser.add_argument('--authority')
    parser.add_argument('--force', action='store_true')
    try:
        args = parser.parse_args(argv)
    except SystemExit:
        print(usage)
        return 2
    if args.command in ('-h', '--help'):
        print(usage)
        return 0
    if args.command == 'self-test':
        ok, failures, probes = self_test()
        for failure in failures:
            print('FAIL', failure)
        print('self-test: %s (%d probes)' %
              ('OK' if ok else 'FAILED', probes))
        return 0 if ok else 1
    if args.command != 'render':
        print(usage)
        return 2
    if args.all:
        names = list(VIEWS)
    elif args.view:
        names = [n.strip() for n in args.view.split(',') if n.strip()]
    else:
        names = ['tasks', 'evidence', 'audit']
    for name in names:
        if name not in VIEWS:
            print('unknown view %r (choose from %s)' % (name, ', '.join(VIEWS)))
            return 2
    try:
        rendered = render(ledger.find_plan_dir(args.plan), names,
                          out_dir=args.out, reconcile=args.reconcile,
                          authority=args.authority, force=args.force)
        if rendered:
            print('OK: rendered %s' % ', '.join(rendered))
        else:
            print('OK: no view changed — records unchanged, nothing written')
        return 0
    except DivergenceError as exc:
        print('DIVERGENCE: %s' % exc, file=sys.stderr)
        return 5
    except ViewsError as exc:
        print('ERROR: %s' % exc, file=sys.stderr)
        return 1
    except ledger.LedgerError as exc:
        print('ERROR: %s' % exc, file=sys.stderr)
        return 1


if __name__ == '__main__':
    sys.exit(main(sys.argv[1:]))
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall